Bump furo from 2022.6.21 to 2022.9.15 in /docs (#3277)

[etc/vim.git] / src / black / __init__.py

diff --git a/src/black/__init__.py b/src/black/__init__.py
index 405a01082e7877d828691dd88be8f40e9e6b358e..ded4a7368228949c1ec43448c7fc241e0604f10b 100644 (file)
--- a/src/black/__init__.py
+++ b/src/black/__init__.py
@@ -1,20 +1,16 @@
-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

 import io
 import io

-from multiprocessing import Manager, freeze_support
-import os
-from pathlib import Path
-from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
+import json
+import platform

 import re
 import re

-import signal

 import sys
 import tokenize
 import traceback
 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 pathlib import Path

 from typing import (
     Any,
     Dict,
 from typing import (
     Any,
     Dict,


@@ -24,6 +20,7 @@ from typing import (
     MutableMapping,
     Optional,
     Pattern,
     MutableMapping,
     Optional,
     Pattern,

+    Sequence,

     Set,
     Sized,
     Tuple,
     Set,
     Sized,
     Tuple,


@@ -32,43 +29,61 @@ from typing import (
 
 import click
 from click.core import ParameterSource
 
 import click
 from click.core import ParameterSource

-from dataclasses import replace

 from mypy_extensions import mypyc_attr
 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
-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, get_cache_info, read_cache, write_cache

 from black.comments import normalize_fmt_off
 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.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.const import (
+    DEFAULT_EXCLUDES,
+    DEFAULT_INCLUDES,
+    DEFAULT_LINE_LENGTH,
+    STDIN_PLACEHOLDER,
+)
+from black.files import (
+    find_project_root,
+    find_pyproject_toml,
+    find_user_pyproject_toml,
+    gen_python_files,
+    get_gitignore,
+    normalize_path_maybe_ignore,
+    parse_pyproject_toml,
+    wrap_stream_for_windows,
+)

 from black.handle_ipynb_magics import (
 from black.handle_ipynb_magics import (

-    mask_cell,
-    unmask_cell,
-    remove_trailing_semicolon,
-    put_trailing_semicolon_back,
-    TRANSFORMED_MAGICS,

     PYTHON_CELL_MAGICS,
     PYTHON_CELL_MAGICS,

+    TRANSFORMED_MAGICS,

     jupyter_dependencies_are_installed,
     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 black.trans import iter_fexpr_spans

 from blib2to3.pgen2 import token
 from blib2to3.pgen2 import token

-
-from _black_version import version as __version__
+from blib2to3.pytree import Leaf, Node

 
 COMPILED = Path(__file__).suffix in (".pyd", ".so")
 
 
 COMPILED = Path(__file__).suffix in (".pyd", ".so")
 


@@ -101,8 +116,6 @@ class WriteBack(Enum):
 # Legacy name, left for integrations.
 FileMode = Mode
 
 # 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]
 
 def read_pyproject_toml(
     ctx: click.Context, param: click.Parameter, value: Optional[str]


@@ -225,6 +238,16 @@ def validate_regex(
         "(useful when piping source on standard input)."
     ),
 )
         "(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",
 @click.option(
     "-S",
     "--skip-string-normalization",


@@ -241,16 +264,13 @@ def validate_regex(
     "--experimental-string-processing",
     is_flag=True,
     hidden=True,
     "--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",
     is_flag=True,
     help=(
 )
 @click.option(
     "--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."
     ),
 )
         " functionality in the next major release."
     ),
 )


@@ -283,7 +303,8 @@ def validate_regex(
     type=str,
     help=(
         "Require a specific version of Black to be running (useful for unifying results"
     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(
     ),
 )
 @click.option(


@@ -343,9 +364,8 @@ def validate_regex(
     "-W",
     "--workers",
     type=click.IntRange(min=1),
     "-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",
 )
 @click.option(
     "-q",


@@ -367,7 +387,10 @@ def validate_regex(
 )
 @click.version_option(
     version=__version__,
 )
 @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",
 )
 @click.argument(
     "src",


@@ -393,7 +416,7 @@ def validate_regex(
     help="Read configuration from FILE path.",
 )
 @click.pass_context
     help="Read configuration from FILE path.",
 )
 @click.pass_context

-def main(
+def main(  # noqa: C901

     ctx: click.Context,
     code: Optional[str],
     line_length: int,
     ctx: click.Context,
     code: Optional[str],
     line_length: int,


@@ -404,6 +427,7 @@ def main(
     fast: bool,
     pyi: bool,
     ipynb: bool,
     fast: bool,
     pyi: bool,
     ipynb: bool,

+    python_cell_magics: Sequence[str],

     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,
     skip_string_normalization: bool,
     skip_magic_trailing_comma: bool,
     experimental_string_processing: bool,


@@ -416,13 +440,26 @@ def main(
     extend_exclude: Optional[Pattern[str]],
     force_exclude: Optional[Pattern[str]],
     stdin_filename: Optional[str],
     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:
     """The uncompromising code formatter."""
     ctx.ensure_object(dict)
     src: Tuple[str, ...],
     config: Optional[str],
 ) -> None:
     """The uncompromising code formatter."""
     ctx.ensure_object(dict)

-    root, method = find_project_root(src) if code is None else (None, None)
+
+    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, stdin_filename) if code is None else (None, None)
+    )

     ctx.obj["root"] = root
 
     if verbose:
     ctx.obj["root"] = root
 
     if verbose:


@@ -433,7 +470,9 @@ def main(
             )
 
             normalized = [
             )
 
             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(
                 for source in src
             ]
             srcs_string = ", ".join(


@@ -448,13 +487,27 @@ def main(
 
         if config:
             config_source = ctx.get_parameter_source("config")
 
         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(
+                    "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")
 
     error_msg = "Oh no! 💥 💔 💥"
                 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__:
+    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__}`!"
         err(
             f"{error_msg} The required version `{required_version}` does not match"
             f" the running version `{__version__}`!"


@@ -479,6 +532,7 @@ def main(
         magic_trailing_comma=not skip_magic_trailing_comma,
         experimental_string_processing=experimental_string_processing,
         preview=preview,
         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:
     )
 
     if code is not None:


@@ -526,6 +580,8 @@ def main(
                 report=report,
             )
         else:
                 report=report,
             )
         else:

+            from black.concurrency import reformat_many
+

             reformat_many(
                 sources=sources,
                 fast=fast,
             reformat_many(
                 sources=sources,
                 fast=fast,


@@ -559,13 +615,7 @@ def get_sources(
 ) -> Set[Path]:
     """Compute the set of files to be formatted."""
     sources: Set[Path] = set()
 ) -> 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)
-        gitignore = get_gitignore(ctx.obj["root"])
-    else:
-        gitignore = None
+    root = ctx.obj["root"]

 
     for s in src:
         if s == "-" and stdin_filename:
 
     for s in src:
         if s == "-" and stdin_filename:


@@ -600,6 +650,16 @@ def get_sources(
 
             sources.add(p)
         elif p.is_dir():
 
             sources.add(p)
         elif p.is_dir():

+            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(
                 gen_python_files(
                     p.iterdir(),
             sources.update(
                 gen_python_files(
                     p.iterdir(),


@@ -657,6 +717,9 @@ def reformat_code(
         report.failed(path, str(exc))
 
 
         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:
 def reformat_one(
     src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
 ) -> None:


@@ -708,126 +771,6 @@ def reformat_one(
         report.failed(src, str(exc))
 
 
         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."""
-    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
-        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)
-
-    try:
-        loop.run_until_complete(
-            schedule_formatting(
-                sources=sources,
-                fast=fast,
-                write_back=write_back,
-                mode=mode,
-                report=report,
-                loop=loop,
-                executor=executor,
-            )
-        )
-    finally:
-        shutdown(loop)
-        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,
 def format_file_in_place(
     src: Path,
     fast: bool,


@@ -948,17 +891,7 @@ def check_stability_and_equivalence(
     content differently.
     """
     assert_equivalent(src_contents, dst_contents)
     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:
 
 
 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:


@@ -984,7 +917,7 @@ def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileCo
     return dst_contents
 
 
     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.
     """Check that cell does not already contain TransformerManager transformations,
     or non-Python cell magics, which might cause tokenizer_rt to break because of
     indentations.


@@ -1003,7 +936,10 @@ def validate_cell(src: str) -> None:
     """
     if any(transformed_magic in src for transformed_magic in TRANSFORMED_MAGICS):
         raise NothingChanged
     """
     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
 
 
         raise NothingChanged
 
 


@@ -1023,7 +959,7 @@ def format_cell(src: str, *, fast: bool, mode: Mode) -> str:
     could potentially be automagics or multi-line magics, which
     are currently not supported.
     """
     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
     )
     src_without_trailing_semicolon, has_trailing_semicolon = remove_trailing_semicolon(
         src
     )


@@ -1085,7 +1021,7 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
         raise NothingChanged
 
 
         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
     """Reformat a string and return new contents.
 
     `mode` determines formatting options, such as how many characters per line are


@@ -1115,15 +1051,25 @@ def format_str(src_contents: str, *, mode: Mode) -> FileContent:
         hey
 
     """
         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 = []
     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:
     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)
 
         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)
     lines = LineGenerator(mode=mode)
     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
     empty_line = Line(mode=mode)


@@ -1168,6 +1114,7 @@ def get_features_used(  # noqa: C901
 
     Currently looking for:
     - f-strings;
 
     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;
     - underscores in numeric literals;
     - trailing commas after * or ** in function signatures and calls;
     - positional only arguments in function signatures and lambdas;


@@ -1189,9 +1136,13 @@ 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)
             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 n.type == token.NUMBER:
-            assert isinstance(n, Leaf)
+        elif is_number_token(n):

             if "_" in n.value:
                 features.add(Feature.NUMERIC_UNDERSCORES)
 
             if "_" in n.value:
                 features.add(Feature.NUMERIC_UNDERSCORES)
 


@@ -1246,6 +1197,25 @@ def get_features_used(  # noqa: C901
         ):
             features.add(Feature.ANN_ASSIGN_EXTENDED_RHS)
 
         ):
             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)
+
+        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
 
 
     return features
 
 


@@ -1309,13 +1279,16 @@ def get_future_imports(node: Node) -> Set[str]:
     return imports
 
 
     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)
     except Exception as exc:
         raise AssertionError(
     """Raise AssertionError if `src` and `dst` aren't equivalent."""
     try:
         src_ast = parse_ast(src)
     except Exception as exc:
         raise AssertionError(

-            f"cannot use --safe with this file; failed to parse source file: {exc}"
+            "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 "
+            "that does not support new syntax used in your source file."

         ) from exc
 
     try:
         ) from exc
 
     try:


@@ -1323,7 +1296,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(
     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
             "Please report a bug on https://github.com/psf/black/issues.  "
             f"This invalid output might be helpful: {log}"
         ) from None


@@ -1334,14 +1307,17 @@ 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"
         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 "
+            " source.  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."""
             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)
+    # 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),
     if dst != newdst:
         log = dump_to_file(
             str(mode),


@@ -1375,13 +1351,23 @@ 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.
     """
     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
     try:
         from click import core

-        from click import _unicodefun
-    except ModuleNotFoundError:
-        return
+    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 (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"):
         if hasattr(module, "_verify_python3_env"):
             module._verify_python3_env = lambda: None  # type: ignore
         if hasattr(module, "_verify_python_env"):


@@ -1389,8 +1375,11 @@ def patch_click() -> None:
 
 
 def patched_main() -> 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()
 
     patch_click()
     main()