]> git.madduck.net Git - etc/vim.git/blob - black.py

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

26a2915bac98d561058558ab44b0c5dc9540b354
[etc/vim.git] / black.py
1 import ast
2 import asyncio
3 from concurrent.futures import Executor, ProcessPoolExecutor
4 from contextlib import contextmanager
5 from datetime import datetime
6 from enum import Enum
7 from functools import lru_cache, partial, wraps
8 import io
9 import itertools
10 import logging
11 from multiprocessing import Manager, freeze_support
12 import os
13 from pathlib import Path
14 import pickle
15 import regex as re
16 import signal
17 import sys
18 import tempfile
19 import tokenize
20 import traceback
21 from typing import (
22     Any,
23     Callable,
24     Collection,
25     Dict,
26     Generator,
27     Generic,
28     Iterable,
29     Iterator,
30     List,
31     Optional,
32     Pattern,
33     Sequence,
34     Set,
35     Tuple,
36     TypeVar,
37     Union,
38     cast,
39 )
40 from typing_extensions import Final
41 from mypy_extensions import mypyc_attr
42
43 from appdirs import user_cache_dir
44 from dataclasses import dataclass, field, replace
45 import click
46 import toml
47 from typed_ast import ast3, ast27
48 from pathspec import PathSpec
49
50 # lib2to3 fork
51 from blib2to3.pytree import Node, Leaf, type_repr
52 from blib2to3 import pygram, pytree
53 from blib2to3.pgen2 import driver, token
54 from blib2to3.pgen2.grammar import Grammar
55 from blib2to3.pgen2.parse import ParseError
56
57 from _black_version import version as __version__
58
59 DEFAULT_LINE_LENGTH = 88
60 DEFAULT_EXCLUDES = r"/(\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
61 DEFAULT_INCLUDES = r"\.pyi?$"
62 CACHE_DIR = Path(user_cache_dir("black", version=__version__))
63
64
65 # types
66 FileContent = str
67 Encoding = str
68 NewLine = str
69 Depth = int
70 NodeType = int
71 LeafID = int
72 Priority = int
73 Index = int
74 LN = Union[Leaf, Node]
75 SplitFunc = Callable[["Line", Collection["Feature"]], Iterator["Line"]]
76 Timestamp = float
77 FileSize = int
78 CacheInfo = Tuple[Timestamp, FileSize]
79 Cache = Dict[Path, CacheInfo]
80 out = partial(click.secho, bold=True, err=True)
81 err = partial(click.secho, fg="red", err=True)
82
83 pygram.initialize(CACHE_DIR)
84 syms = pygram.python_symbols
85
86
87 class NothingChanged(UserWarning):
88     """Raised when reformatted code is the same as source."""
89
90
91 class CannotSplit(Exception):
92     """A readable split that fits the allotted line length is impossible."""
93
94
95 class InvalidInput(ValueError):
96     """Raised when input source code fails all parse attempts."""
97
98
99 class WriteBack(Enum):
100     NO = 0
101     YES = 1
102     DIFF = 2
103     CHECK = 3
104
105     @classmethod
106     def from_configuration(cls, *, check: bool, diff: bool) -> "WriteBack":
107         if check and not diff:
108             return cls.CHECK
109
110         return cls.DIFF if diff else cls.YES
111
112
113 class Changed(Enum):
114     NO = 0
115     CACHED = 1
116     YES = 2
117
118
119 class TargetVersion(Enum):
120     PY27 = 2
121     PY33 = 3
122     PY34 = 4
123     PY35 = 5
124     PY36 = 6
125     PY37 = 7
126     PY38 = 8
127
128     def is_python2(self) -> bool:
129         return self is TargetVersion.PY27
130
131
132 PY36_VERSIONS = {TargetVersion.PY36, TargetVersion.PY37, TargetVersion.PY38}
133
134
135 class Feature(Enum):
136     # All string literals are unicode
137     UNICODE_LITERALS = 1
138     F_STRINGS = 2
139     NUMERIC_UNDERSCORES = 3
140     TRAILING_COMMA_IN_CALL = 4
141     TRAILING_COMMA_IN_DEF = 5
142     # The following two feature-flags are mutually exclusive, and exactly one should be
143     # set for every version of python.
144     ASYNC_IDENTIFIERS = 6
145     ASYNC_KEYWORDS = 7
146     ASSIGNMENT_EXPRESSIONS = 8
147     POS_ONLY_ARGUMENTS = 9
148
149
150 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
151     TargetVersion.PY27: {Feature.ASYNC_IDENTIFIERS},
152     TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
153     TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
154     TargetVersion.PY35: {
155         Feature.UNICODE_LITERALS,
156         Feature.TRAILING_COMMA_IN_CALL,
157         Feature.ASYNC_IDENTIFIERS,
158     },
159     TargetVersion.PY36: {
160         Feature.UNICODE_LITERALS,
161         Feature.F_STRINGS,
162         Feature.NUMERIC_UNDERSCORES,
163         Feature.TRAILING_COMMA_IN_CALL,
164         Feature.TRAILING_COMMA_IN_DEF,
165         Feature.ASYNC_IDENTIFIERS,
166     },
167     TargetVersion.PY37: {
168         Feature.UNICODE_LITERALS,
169         Feature.F_STRINGS,
170         Feature.NUMERIC_UNDERSCORES,
171         Feature.TRAILING_COMMA_IN_CALL,
172         Feature.TRAILING_COMMA_IN_DEF,
173         Feature.ASYNC_KEYWORDS,
174     },
175     TargetVersion.PY38: {
176         Feature.UNICODE_LITERALS,
177         Feature.F_STRINGS,
178         Feature.NUMERIC_UNDERSCORES,
179         Feature.TRAILING_COMMA_IN_CALL,
180         Feature.TRAILING_COMMA_IN_DEF,
181         Feature.ASYNC_KEYWORDS,
182         Feature.ASSIGNMENT_EXPRESSIONS,
183         Feature.POS_ONLY_ARGUMENTS,
184     },
185 }
186
187
188 @dataclass
189 class Mode:
190     target_versions: Set[TargetVersion] = field(default_factory=set)
191     line_length: int = DEFAULT_LINE_LENGTH
192     string_normalization: bool = True
193     is_pyi: bool = False
194
195     def get_cache_key(self) -> str:
196         if self.target_versions:
197             version_str = ",".join(
198                 str(version.value)
199                 for version in sorted(self.target_versions, key=lambda v: v.value)
200             )
201         else:
202             version_str = "-"
203         parts = [
204             version_str,
205             str(self.line_length),
206             str(int(self.string_normalization)),
207             str(int(self.is_pyi)),
208         ]
209         return ".".join(parts)
210
211
212 # Legacy name, left for integrations.
213 FileMode = Mode
214
215
216 def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
217     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
218
219
220 def find_pyproject_toml(path_search_start: str) -> Optional[str]:
221     """Find the absolute filepath to a pyproject.toml if it exists"""
222     path_project_root = find_project_root(path_search_start)
223     path_pyproject_toml = path_project_root / "pyproject.toml"
224     return str(path_pyproject_toml) if path_pyproject_toml.is_file() else None
225
226
227 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
228     """Parse a pyproject toml file, pulling out relevant parts for Black
229
230     If parsing fails, will raise a toml.TomlDecodeError
231     """
232     pyproject_toml = toml.load(path_config)
233     config = pyproject_toml.get("tool", {}).get("black", {})
234     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
235
236
237 def read_pyproject_toml(
238     ctx: click.Context, param: click.Parameter, value: Union[str, int, bool, None]
239 ) -> Optional[str]:
240     """Inject Black configuration from "pyproject.toml" into defaults in `ctx`.
241
242     Returns the path to a successfully found and read configuration file, None
243     otherwise.
244     """
245     assert not isinstance(value, (int, bool)), "Invalid parameter type passed"
246     if not value:
247         value = find_pyproject_toml(ctx.params.get("src", ()))
248         if value is None:
249             return None
250
251     try:
252         config = parse_pyproject_toml(value)
253     except (toml.TomlDecodeError, OSError) as e:
254         raise click.FileError(
255             filename=value, hint=f"Error reading configuration file: {e}"
256         )
257
258     if not config:
259         return None
260
261     if ctx.default_map is None:
262         ctx.default_map = {}
263     ctx.default_map.update(config)  # type: ignore  # bad types in .pyi
264     return value
265
266
267 def target_version_option_callback(
268     c: click.Context, p: Union[click.Option, click.Parameter], v: Tuple[str, ...]
269 ) -> List[TargetVersion]:
270     """Compute the target versions from a --target-version flag.
271
272     This is its own function because mypy couldn't infer the type correctly
273     when it was a lambda, causing mypyc trouble.
274     """
275     return [TargetVersion[val.upper()] for val in v]
276
277
278 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
279 @click.option("-c", "--code", type=str, help="Format the code passed in as a string.")
280 @click.option(
281     "-l",
282     "--line-length",
283     type=int,
284     default=DEFAULT_LINE_LENGTH,
285     help="How many characters per line to allow.",
286     show_default=True,
287 )
288 @click.option(
289     "-t",
290     "--target-version",
291     type=click.Choice([v.name.lower() for v in TargetVersion]),
292     callback=target_version_option_callback,
293     multiple=True,
294     help=(
295         "Python versions that should be supported by Black's output. [default: "
296         "per-file auto-detection]"
297     ),
298 )
299 @click.option(
300     "--py36",
301     is_flag=True,
302     help=(
303         "Allow using Python 3.6-only syntax on all input files.  This will put "
304         "trailing commas in function signatures and calls also after *args and "
305         "**kwargs. Deprecated; use --target-version instead. "
306         "[default: per-file auto-detection]"
307     ),
308 )
309 @click.option(
310     "--pyi",
311     is_flag=True,
312     help=(
313         "Format all input files like typing stubs regardless of file extension "
314         "(useful when piping source on standard input)."
315     ),
316 )
317 @click.option(
318     "-S",
319     "--skip-string-normalization",
320     is_flag=True,
321     help="Don't normalize string quotes or prefixes.",
322 )
323 @click.option(
324     "--check",
325     is_flag=True,
326     help=(
327         "Don't write the files back, just return the status.  Return code 0 "
328         "means nothing would change.  Return code 1 means some files would be "
329         "reformatted.  Return code 123 means there was an internal error."
330     ),
331 )
332 @click.option(
333     "--diff",
334     is_flag=True,
335     help="Don't write the files back, just output a diff for each file on stdout.",
336 )
337 @click.option(
338     "--fast/--safe",
339     is_flag=True,
340     help="If --fast given, skip temporary sanity checks. [default: --safe]",
341 )
342 @click.option(
343     "--include",
344     type=str,
345     default=DEFAULT_INCLUDES,
346     help=(
347         "A regular expression that matches files and directories that should be "
348         "included on recursive searches.  An empty value means all files are "
349         "included regardless of the name.  Use forward slashes for directories on "
350         "all platforms (Windows, too).  Exclusions are calculated first, inclusions "
351         "later."
352     ),
353     show_default=True,
354 )
355 @click.option(
356     "--exclude",
357     type=str,
358     default=DEFAULT_EXCLUDES,
359     help=(
360         "A regular expression that matches files and directories that should be "
361         "excluded on recursive searches.  An empty value means no paths are excluded. "
362         "Use forward slashes for directories on all platforms (Windows, too).  "
363         "Exclusions are calculated first, inclusions later."
364     ),
365     show_default=True,
366 )
367 @click.option(
368     "-q",
369     "--quiet",
370     is_flag=True,
371     help=(
372         "Don't emit non-error messages to stderr. Errors are still emitted; "
373         "silence those with 2>/dev/null."
374     ),
375 )
376 @click.option(
377     "-v",
378     "--verbose",
379     is_flag=True,
380     help=(
381         "Also emit messages to stderr about files that were not changed or were "
382         "ignored due to --exclude=."
383     ),
384 )
385 @click.version_option(version=__version__)
386 @click.argument(
387     "src",
388     nargs=-1,
389     type=click.Path(
390         exists=True, file_okay=True, dir_okay=True, readable=True, allow_dash=True
391     ),
392     is_eager=True,
393 )
394 @click.option(
395     "--config",
396     type=click.Path(
397         exists=True, file_okay=True, dir_okay=False, readable=True, allow_dash=False
398     ),
399     is_eager=True,
400     callback=read_pyproject_toml,
401     help="Read configuration from PATH.",
402 )
403 @click.pass_context
404 def main(
405     ctx: click.Context,
406     code: Optional[str],
407     line_length: int,
408     target_version: List[TargetVersion],
409     check: bool,
410     diff: bool,
411     fast: bool,
412     pyi: bool,
413     py36: bool,
414     skip_string_normalization: bool,
415     quiet: bool,
416     verbose: bool,
417     include: str,
418     exclude: str,
419     src: Tuple[str, ...],
420     config: Optional[str],
421 ) -> None:
422     """The uncompromising code formatter."""
423     write_back = WriteBack.from_configuration(check=check, diff=diff)
424     if target_version:
425         if py36:
426             err("Cannot use both --target-version and --py36")
427             ctx.exit(2)
428         else:
429             versions = set(target_version)
430     elif py36:
431         err(
432             "--py36 is deprecated and will be removed in a future version. "
433             "Use --target-version py36 instead."
434         )
435         versions = PY36_VERSIONS
436     else:
437         # We'll autodetect later.
438         versions = set()
439     mode = Mode(
440         target_versions=versions,
441         line_length=line_length,
442         is_pyi=pyi,
443         string_normalization=not skip_string_normalization,
444     )
445     if config and verbose:
446         out(f"Using configuration from {config}.", bold=False, fg="blue")
447     if code is not None:
448         print(format_str(code, mode=mode))
449         ctx.exit(0)
450     try:
451         include_regex = re_compile_maybe_verbose(include)
452     except re.error:
453         err(f"Invalid regular expression for include given: {include!r}")
454         ctx.exit(2)
455     try:
456         exclude_regex = re_compile_maybe_verbose(exclude)
457     except re.error:
458         err(f"Invalid regular expression for exclude given: {exclude!r}")
459         ctx.exit(2)
460     report = Report(check=check, diff=diff, quiet=quiet, verbose=verbose)
461     root = find_project_root(src)
462     sources: Set[Path] = set()
463     path_empty(src, quiet, verbose, ctx)
464     for s in src:
465         p = Path(s)
466         if p.is_dir():
467             sources.update(
468                 gen_python_files_in_dir(
469                     p, root, include_regex, exclude_regex, report, get_gitignore(root)
470                 )
471             )
472         elif p.is_file() or s == "-":
473             # if a file was explicitly given, we don't care about its extension
474             sources.add(p)
475         else:
476             err(f"invalid path: {s}")
477     if len(sources) == 0:
478         if verbose or not quiet:
479             out("No Python files are present to be formatted. Nothing to do 😴")
480         ctx.exit(0)
481
482     if len(sources) == 1:
483         reformat_one(
484             src=sources.pop(),
485             fast=fast,
486             write_back=write_back,
487             mode=mode,
488             report=report,
489         )
490     else:
491         reformat_many(
492             sources=sources, fast=fast, write_back=write_back, mode=mode, report=report
493         )
494
495     if verbose or not quiet:
496         out("Oh no! 💥 💔 💥" if report.return_code else "All done! ✨ 🍰 ✨")
497         click.secho(str(report), err=True)
498     ctx.exit(report.return_code)
499
500
501 def path_empty(
502     src: Tuple[str, ...], quiet: bool, verbose: bool, ctx: click.Context
503 ) -> None:
504     """
505     Exit if there is no `src` provided for formatting
506     """
507     if not src:
508         if verbose or not quiet:
509             out("No Path provided. Nothing to do 😴")
510             ctx.exit(0)
511
512
513 def reformat_one(
514     src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
515 ) -> None:
516     """Reformat a single file under `src` without spawning child processes.
517
518     `fast`, `write_back`, and `mode` options are passed to
519     :func:`format_file_in_place` or :func:`format_stdin_to_stdout`.
520     """
521     try:
522         changed = Changed.NO
523         if not src.is_file() and str(src) == "-":
524             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
525                 changed = Changed.YES
526         else:
527             cache: Cache = {}
528             if write_back != WriteBack.DIFF:
529                 cache = read_cache(mode)
530                 res_src = src.resolve()
531                 if res_src in cache and cache[res_src] == get_cache_info(res_src):
532                     changed = Changed.CACHED
533             if changed is not Changed.CACHED and format_file_in_place(
534                 src, fast=fast, write_back=write_back, mode=mode
535             ):
536                 changed = Changed.YES
537             if (write_back is WriteBack.YES and changed is not Changed.CACHED) or (
538                 write_back is WriteBack.CHECK and changed is Changed.NO
539             ):
540                 write_cache(cache, [src], mode)
541         report.done(src, changed)
542     except Exception as exc:
543         report.failed(src, str(exc))
544
545
546 def reformat_many(
547     sources: Set[Path], fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
548 ) -> None:
549     """Reformat multiple files using a ProcessPoolExecutor."""
550     loop = asyncio.get_event_loop()
551     worker_count = os.cpu_count()
552     if sys.platform == "win32":
553         # Work around https://bugs.python.org/issue26903
554         worker_count = min(worker_count, 61)
555     executor = ProcessPoolExecutor(max_workers=worker_count)
556     try:
557         loop.run_until_complete(
558             schedule_formatting(
559                 sources=sources,
560                 fast=fast,
561                 write_back=write_back,
562                 mode=mode,
563                 report=report,
564                 loop=loop,
565                 executor=executor,
566             )
567         )
568     finally:
569         shutdown(loop)
570         executor.shutdown()
571
572
573 async def schedule_formatting(
574     sources: Set[Path],
575     fast: bool,
576     write_back: WriteBack,
577     mode: Mode,
578     report: "Report",
579     loop: asyncio.AbstractEventLoop,
580     executor: Executor,
581 ) -> None:
582     """Run formatting of `sources` in parallel using the provided `executor`.
583
584     (Use ProcessPoolExecutors for actual parallelism.)
585
586     `write_back`, `fast`, and `mode` options are passed to
587     :func:`format_file_in_place`.
588     """
589     cache: Cache = {}
590     if write_back != WriteBack.DIFF:
591         cache = read_cache(mode)
592         sources, cached = filter_cached(cache, sources)
593         for src in sorted(cached):
594             report.done(src, Changed.CACHED)
595     if not sources:
596         return
597
598     cancelled = []
599     sources_to_cache = []
600     lock = None
601     if write_back == WriteBack.DIFF:
602         # For diff output, we need locks to ensure we don't interleave output
603         # from different processes.
604         manager = Manager()
605         lock = manager.Lock()
606     tasks = {
607         asyncio.ensure_future(
608             loop.run_in_executor(
609                 executor, format_file_in_place, src, fast, mode, write_back, lock
610             )
611         ): src
612         for src in sorted(sources)
613     }
614     pending: Iterable["asyncio.Future[bool]"] = tasks.keys()
615     try:
616         loop.add_signal_handler(signal.SIGINT, cancel, pending)
617         loop.add_signal_handler(signal.SIGTERM, cancel, pending)
618     except NotImplementedError:
619         # There are no good alternatives for these on Windows.
620         pass
621     while pending:
622         done, _ = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
623         for task in done:
624             src = tasks.pop(task)
625             if task.cancelled():
626                 cancelled.append(task)
627             elif task.exception():
628                 report.failed(src, str(task.exception()))
629             else:
630                 changed = Changed.YES if task.result() else Changed.NO
631                 # If the file was written back or was successfully checked as
632                 # well-formatted, store this information in the cache.
633                 if write_back is WriteBack.YES or (
634                     write_back is WriteBack.CHECK and changed is Changed.NO
635                 ):
636                     sources_to_cache.append(src)
637                 report.done(src, changed)
638     if cancelled:
639         await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
640     if sources_to_cache:
641         write_cache(cache, sources_to_cache, mode)
642
643
644 def format_file_in_place(
645     src: Path,
646     fast: bool,
647     mode: Mode,
648     write_back: WriteBack = WriteBack.NO,
649     lock: Any = None,  # multiprocessing.Manager().Lock() is some crazy proxy
650 ) -> bool:
651     """Format file under `src` path. Return True if changed.
652
653     If `write_back` is DIFF, write a diff to stdout. If it is YES, write reformatted
654     code to the file.
655     `mode` and `fast` options are passed to :func:`format_file_contents`.
656     """
657     if src.suffix == ".pyi":
658         mode = replace(mode, is_pyi=True)
659
660     then = datetime.utcfromtimestamp(src.stat().st_mtime)
661     with open(src, "rb") as buf:
662         src_contents, encoding, newline = decode_bytes(buf.read())
663     try:
664         dst_contents = format_file_contents(src_contents, fast=fast, mode=mode)
665     except NothingChanged:
666         return False
667
668     if write_back == WriteBack.YES:
669         with open(src, "w", encoding=encoding, newline=newline) as f:
670             f.write(dst_contents)
671     elif write_back == WriteBack.DIFF:
672         now = datetime.utcnow()
673         src_name = f"{src}\t{then} +0000"
674         dst_name = f"{src}\t{now} +0000"
675         diff_contents = diff(src_contents, dst_contents, src_name, dst_name)
676
677         with lock or nullcontext():
678             f = io.TextIOWrapper(
679                 sys.stdout.buffer,
680                 encoding=encoding,
681                 newline=newline,
682                 write_through=True,
683             )
684             f.write(diff_contents)
685             f.detach()
686
687     return True
688
689
690 def format_stdin_to_stdout(
691     fast: bool, *, write_back: WriteBack = WriteBack.NO, mode: Mode
692 ) -> bool:
693     """Format file on stdin. Return True if changed.
694
695     If `write_back` is YES, write reformatted code back to stdout. If it is DIFF,
696     write a diff to stdout. The `mode` argument is passed to
697     :func:`format_file_contents`.
698     """
699     then = datetime.utcnow()
700     src, encoding, newline = decode_bytes(sys.stdin.buffer.read())
701     dst = src
702     try:
703         dst = format_file_contents(src, fast=fast, mode=mode)
704         return True
705
706     except NothingChanged:
707         return False
708
709     finally:
710         f = io.TextIOWrapper(
711             sys.stdout.buffer, encoding=encoding, newline=newline, write_through=True
712         )
713         if write_back == WriteBack.YES:
714             f.write(dst)
715         elif write_back == WriteBack.DIFF:
716             now = datetime.utcnow()
717             src_name = f"STDIN\t{then} +0000"
718             dst_name = f"STDOUT\t{now} +0000"
719             f.write(diff(src, dst, src_name, dst_name))
720         f.detach()
721
722
723 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
724     """Reformat contents a file and return new contents.
725
726     If `fast` is False, additionally confirm that the reformatted code is
727     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
728     `mode` is passed to :func:`format_str`.
729     """
730     if src_contents.strip() == "":
731         raise NothingChanged
732
733     dst_contents = format_str(src_contents, mode=mode)
734     if src_contents == dst_contents:
735         raise NothingChanged
736
737     if not fast:
738         assert_equivalent(src_contents, dst_contents)
739         assert_stable(src_contents, dst_contents, mode=mode)
740     return dst_contents
741
742
743 def format_str(src_contents: str, *, mode: Mode) -> FileContent:
744     """Reformat a string and return new contents.
745
746     `mode` determines formatting options, such as how many characters per line are
747     allowed.  Example:
748
749     >>> import black
750     >>> print(black.format_str("def f(arg:str='')->None:...", mode=Mode()))
751     def f(arg: str = "") -> None:
752         ...
753
754     A more complex example:
755     >>> print(
756     ...   black.format_str(
757     ...     "def f(arg:str='')->None: hey",
758     ...     mode=black.Mode(
759     ...       target_versions={black.TargetVersion.PY36},
760     ...       line_length=10,
761     ...       string_normalization=False,
762     ...       is_pyi=False,
763     ...     ),
764     ...   ),
765     ... )
766     def f(
767         arg: str = '',
768     ) -> None:
769         hey
770
771     """
772     src_node = lib2to3_parse(src_contents.lstrip(), mode.target_versions)
773     dst_contents = []
774     future_imports = get_future_imports(src_node)
775     if mode.target_versions:
776         versions = mode.target_versions
777     else:
778         versions = detect_target_versions(src_node)
779     normalize_fmt_off(src_node)
780     lines = LineGenerator(
781         remove_u_prefix="unicode_literals" in future_imports
782         or supports_feature(versions, Feature.UNICODE_LITERALS),
783         is_pyi=mode.is_pyi,
784         normalize_strings=mode.string_normalization,
785     )
786     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
787     empty_line = Line()
788     after = 0
789     split_line_features = {
790         feature
791         for feature in {Feature.TRAILING_COMMA_IN_CALL, Feature.TRAILING_COMMA_IN_DEF}
792         if supports_feature(versions, feature)
793     }
794     for current_line in lines.visit(src_node):
795         dst_contents.append(str(empty_line) * after)
796         before, after = elt.maybe_empty_lines(current_line)
797         dst_contents.append(str(empty_line) * before)
798         for line in split_line(
799             current_line, line_length=mode.line_length, features=split_line_features
800         ):
801             dst_contents.append(str(line))
802     return "".join(dst_contents)
803
804
805 def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
806     """Return a tuple of (decoded_contents, encoding, newline).
807
808     `newline` is either CRLF or LF but `decoded_contents` is decoded with
809     universal newlines (i.e. only contains LF).
810     """
811     srcbuf = io.BytesIO(src)
812     encoding, lines = tokenize.detect_encoding(srcbuf.readline)
813     if not lines:
814         return "", encoding, "\n"
815
816     newline = "\r\n" if b"\r\n" == lines[0][-2:] else "\n"
817     srcbuf.seek(0)
818     with io.TextIOWrapper(srcbuf, encoding) as tiow:
819         return tiow.read(), encoding, newline
820
821
822 def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
823     if not target_versions:
824         # No target_version specified, so try all grammars.
825         return [
826             # Python 3.7+
827             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
828             # Python 3.0-3.6
829             pygram.python_grammar_no_print_statement_no_exec_statement,
830             # Python 2.7 with future print_function import
831             pygram.python_grammar_no_print_statement,
832             # Python 2.7
833             pygram.python_grammar,
834         ]
835
836     if all(version.is_python2() for version in target_versions):
837         # Python 2-only code, so try Python 2 grammars.
838         return [
839             # Python 2.7 with future print_function import
840             pygram.python_grammar_no_print_statement,
841             # Python 2.7
842             pygram.python_grammar,
843         ]
844
845     # Python 3-compatible code, so only try Python 3 grammar.
846     grammars = []
847     # If we have to parse both, try to parse async as a keyword first
848     if not supports_feature(target_versions, Feature.ASYNC_IDENTIFIERS):
849         # Python 3.7+
850         grammars.append(
851             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
852         )
853     if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
854         # Python 3.0-3.6
855         grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
856     # At least one of the above branches must have been taken, because every Python
857     # version has exactly one of the two 'ASYNC_*' flags
858     return grammars
859
860
861 def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -> Node:
862     """Given a string with source, return the lib2to3 Node."""
863     if src_txt[-1:] != "\n":
864         src_txt += "\n"
865
866     for grammar in get_grammars(set(target_versions)):
867         drv = driver.Driver(grammar, pytree.convert)
868         try:
869             result = drv.parse_string(src_txt, True)
870             break
871
872         except ParseError as pe:
873             lineno, column = pe.context[1]
874             lines = src_txt.splitlines()
875             try:
876                 faulty_line = lines[lineno - 1]
877             except IndexError:
878                 faulty_line = "<line number missing in source>"
879             exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {faulty_line}")
880     else:
881         raise exc from None
882
883     if isinstance(result, Leaf):
884         result = Node(syms.file_input, [result])
885     return result
886
887
888 def lib2to3_unparse(node: Node) -> str:
889     """Given a lib2to3 node, return its string representation."""
890     code = str(node)
891     return code
892
893
894 T = TypeVar("T")
895
896
897 class Visitor(Generic[T]):
898     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
899
900     def visit(self, node: LN) -> Iterator[T]:
901         """Main method to visit `node` and its children.
902
903         It tries to find a `visit_*()` method for the given `node.type`, like
904         `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
905         If no dedicated `visit_*()` method is found, chooses `visit_default()`
906         instead.
907
908         Then yields objects of type `T` from the selected visitor.
909         """
910         if node.type < 256:
911             name = token.tok_name[node.type]
912         else:
913             name = str(type_repr(node.type))
914         # We explicitly branch on whether a visitor exists (instead of
915         # using self.visit_default as the default arg to getattr) in order
916         # to save needing to create a bound method object and so mypyc can
917         # generate a native call to visit_default.
918         visitf = getattr(self, f"visit_{name}", None)
919         if visitf:
920             yield from visitf(node)
921         else:
922             yield from self.visit_default(node)
923
924     def visit_default(self, node: LN) -> Iterator[T]:
925         """Default `visit_*()` implementation. Recurses to children of `node`."""
926         if isinstance(node, Node):
927             for child in node.children:
928                 yield from self.visit(child)
929
930
931 @dataclass
932 class DebugVisitor(Visitor[T]):
933     tree_depth: int = 0
934
935     def visit_default(self, node: LN) -> Iterator[T]:
936         indent = " " * (2 * self.tree_depth)
937         if isinstance(node, Node):
938             _type = type_repr(node.type)
939             out(f"{indent}{_type}", fg="yellow")
940             self.tree_depth += 1
941             for child in node.children:
942                 yield from self.visit(child)
943
944             self.tree_depth -= 1
945             out(f"{indent}/{_type}", fg="yellow", bold=False)
946         else:
947             _type = token.tok_name.get(node.type, str(node.type))
948             out(f"{indent}{_type}", fg="blue", nl=False)
949             if node.prefix:
950                 # We don't have to handle prefixes for `Node` objects since
951                 # that delegates to the first child anyway.
952                 out(f" {node.prefix!r}", fg="green", bold=False, nl=False)
953             out(f" {node.value!r}", fg="blue", bold=False)
954
955     @classmethod
956     def show(cls, code: Union[str, Leaf, Node]) -> None:
957         """Pretty-print the lib2to3 AST of a given string of `code`.
958
959         Convenience method for debugging.
960         """
961         v: DebugVisitor[None] = DebugVisitor()
962         if isinstance(code, str):
963             code = lib2to3_parse(code)
964         list(v.visit(code))
965
966
967 WHITESPACE: Final = {token.DEDENT, token.INDENT, token.NEWLINE}
968 STATEMENT: Final = {
969     syms.if_stmt,
970     syms.while_stmt,
971     syms.for_stmt,
972     syms.try_stmt,
973     syms.except_clause,
974     syms.with_stmt,
975     syms.funcdef,
976     syms.classdef,
977 }
978 STANDALONE_COMMENT: Final = 153
979 token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
980 LOGIC_OPERATORS: Final = {"and", "or"}
981 COMPARATORS: Final = {
982     token.LESS,
983     token.GREATER,
984     token.EQEQUAL,
985     token.NOTEQUAL,
986     token.LESSEQUAL,
987     token.GREATEREQUAL,
988 }
989 MATH_OPERATORS: Final = {
990     token.VBAR,
991     token.CIRCUMFLEX,
992     token.AMPER,
993     token.LEFTSHIFT,
994     token.RIGHTSHIFT,
995     token.PLUS,
996     token.MINUS,
997     token.STAR,
998     token.SLASH,
999     token.DOUBLESLASH,
1000     token.PERCENT,
1001     token.AT,
1002     token.TILDE,
1003     token.DOUBLESTAR,
1004 }
1005 STARS: Final = {token.STAR, token.DOUBLESTAR}
1006 VARARGS_SPECIALS: Final = STARS | {token.SLASH}
1007 VARARGS_PARENTS: Final = {
1008     syms.arglist,
1009     syms.argument,  # double star in arglist
1010     syms.trailer,  # single argument to call
1011     syms.typedargslist,
1012     syms.varargslist,  # lambdas
1013 }
1014 UNPACKING_PARENTS: Final = {
1015     syms.atom,  # single element of a list or set literal
1016     syms.dictsetmaker,
1017     syms.listmaker,
1018     syms.testlist_gexp,
1019     syms.testlist_star_expr,
1020 }
1021 TEST_DESCENDANTS: Final = {
1022     syms.test,
1023     syms.lambdef,
1024     syms.or_test,
1025     syms.and_test,
1026     syms.not_test,
1027     syms.comparison,
1028     syms.star_expr,
1029     syms.expr,
1030     syms.xor_expr,
1031     syms.and_expr,
1032     syms.shift_expr,
1033     syms.arith_expr,
1034     syms.trailer,
1035     syms.term,
1036     syms.power,
1037 }
1038 ASSIGNMENTS: Final = {
1039     "=",
1040     "+=",
1041     "-=",
1042     "*=",
1043     "@=",
1044     "/=",
1045     "%=",
1046     "&=",
1047     "|=",
1048     "^=",
1049     "<<=",
1050     ">>=",
1051     "**=",
1052     "//=",
1053 }
1054 COMPREHENSION_PRIORITY: Final = 20
1055 COMMA_PRIORITY: Final = 18
1056 TERNARY_PRIORITY: Final = 16
1057 LOGIC_PRIORITY: Final = 14
1058 STRING_PRIORITY: Final = 12
1059 COMPARATOR_PRIORITY: Final = 10
1060 MATH_PRIORITIES: Final = {
1061     token.VBAR: 9,
1062     token.CIRCUMFLEX: 8,
1063     token.AMPER: 7,
1064     token.LEFTSHIFT: 6,
1065     token.RIGHTSHIFT: 6,
1066     token.PLUS: 5,
1067     token.MINUS: 5,
1068     token.STAR: 4,
1069     token.SLASH: 4,
1070     token.DOUBLESLASH: 4,
1071     token.PERCENT: 4,
1072     token.AT: 4,
1073     token.TILDE: 3,
1074     token.DOUBLESTAR: 2,
1075 }
1076 DOT_PRIORITY: Final = 1
1077
1078
1079 @dataclass
1080 class BracketTracker:
1081     """Keeps track of brackets on a line."""
1082
1083     depth: int = 0
1084     bracket_match: Dict[Tuple[Depth, NodeType], Leaf] = field(default_factory=dict)
1085     delimiters: Dict[LeafID, Priority] = field(default_factory=dict)
1086     previous: Optional[Leaf] = None
1087     _for_loop_depths: List[int] = field(default_factory=list)
1088     _lambda_argument_depths: List[int] = field(default_factory=list)
1089
1090     def mark(self, leaf: Leaf) -> None:
1091         """Mark `leaf` with bracket-related metadata. Keep track of delimiters.
1092
1093         All leaves receive an int `bracket_depth` field that stores how deep
1094         within brackets a given leaf is. 0 means there are no enclosing brackets
1095         that started on this line.
1096
1097         If a leaf is itself a closing bracket, it receives an `opening_bracket`
1098         field that it forms a pair with. This is a one-directional link to
1099         avoid reference cycles.
1100
1101         If a leaf is a delimiter (a token on which Black can split the line if
1102         needed) and it's on depth 0, its `id()` is stored in the tracker's
1103         `delimiters` field.
1104         """
1105         if leaf.type == token.COMMENT:
1106             return
1107
1108         self.maybe_decrement_after_for_loop_variable(leaf)
1109         self.maybe_decrement_after_lambda_arguments(leaf)
1110         if leaf.type in CLOSING_BRACKETS:
1111             self.depth -= 1
1112             opening_bracket = self.bracket_match.pop((self.depth, leaf.type))
1113             leaf.opening_bracket = opening_bracket
1114         leaf.bracket_depth = self.depth
1115         if self.depth == 0:
1116             delim = is_split_before_delimiter(leaf, self.previous)
1117             if delim and self.previous is not None:
1118                 self.delimiters[id(self.previous)] = delim
1119             else:
1120                 delim = is_split_after_delimiter(leaf, self.previous)
1121                 if delim:
1122                     self.delimiters[id(leaf)] = delim
1123         if leaf.type in OPENING_BRACKETS:
1124             self.bracket_match[self.depth, BRACKET[leaf.type]] = leaf
1125             self.depth += 1
1126         self.previous = leaf
1127         self.maybe_increment_lambda_arguments(leaf)
1128         self.maybe_increment_for_loop_variable(leaf)
1129
1130     def any_open_brackets(self) -> bool:
1131         """Return True if there is an yet unmatched open bracket on the line."""
1132         return bool(self.bracket_match)
1133
1134     def max_delimiter_priority(self, exclude: Iterable[LeafID] = ()) -> Priority:
1135         """Return the highest priority of a delimiter found on the line.
1136
1137         Values are consistent with what `is_split_*_delimiter()` return.
1138         Raises ValueError on no delimiters.
1139         """
1140         return max(v for k, v in self.delimiters.items() if k not in exclude)
1141
1142     def delimiter_count_with_priority(self, priority: Priority = 0) -> int:
1143         """Return the number of delimiters with the given `priority`.
1144
1145         If no `priority` is passed, defaults to max priority on the line.
1146         """
1147         if not self.delimiters:
1148             return 0
1149
1150         priority = priority or self.max_delimiter_priority()
1151         return sum(1 for p in self.delimiters.values() if p == priority)
1152
1153     def maybe_increment_for_loop_variable(self, leaf: Leaf) -> bool:
1154         """In a for loop, or comprehension, the variables are often unpacks.
1155
1156         To avoid splitting on the comma in this situation, increase the depth of
1157         tokens between `for` and `in`.
1158         """
1159         if leaf.type == token.NAME and leaf.value == "for":
1160             self.depth += 1
1161             self._for_loop_depths.append(self.depth)
1162             return True
1163
1164         return False
1165
1166     def maybe_decrement_after_for_loop_variable(self, leaf: Leaf) -> bool:
1167         """See `maybe_increment_for_loop_variable` above for explanation."""
1168         if (
1169             self._for_loop_depths
1170             and self._for_loop_depths[-1] == self.depth
1171             and leaf.type == token.NAME
1172             and leaf.value == "in"
1173         ):
1174             self.depth -= 1
1175             self._for_loop_depths.pop()
1176             return True
1177
1178         return False
1179
1180     def maybe_increment_lambda_arguments(self, leaf: Leaf) -> bool:
1181         """In a lambda expression, there might be more than one argument.
1182
1183         To avoid splitting on the comma in this situation, increase the depth of
1184         tokens between `lambda` and `:`.
1185         """
1186         if leaf.type == token.NAME and leaf.value == "lambda":
1187             self.depth += 1
1188             self._lambda_argument_depths.append(self.depth)
1189             return True
1190
1191         return False
1192
1193     def maybe_decrement_after_lambda_arguments(self, leaf: Leaf) -> bool:
1194         """See `maybe_increment_lambda_arguments` above for explanation."""
1195         if (
1196             self._lambda_argument_depths
1197             and self._lambda_argument_depths[-1] == self.depth
1198             and leaf.type == token.COLON
1199         ):
1200             self.depth -= 1
1201             self._lambda_argument_depths.pop()
1202             return True
1203
1204         return False
1205
1206     def get_open_lsqb(self) -> Optional[Leaf]:
1207         """Return the most recent opening square bracket (if any)."""
1208         return self.bracket_match.get((self.depth - 1, token.RSQB))
1209
1210
1211 @dataclass
1212 class Line:
1213     """Holds leaves and comments. Can be printed with `str(line)`."""
1214
1215     depth: int = 0
1216     leaves: List[Leaf] = field(default_factory=list)
1217     # keys ordered like `leaves`
1218     comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
1219     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
1220     inside_brackets: bool = False
1221     should_explode: bool = False
1222
1223     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
1224         """Add a new `leaf` to the end of the line.
1225
1226         Unless `preformatted` is True, the `leaf` will receive a new consistent
1227         whitespace prefix and metadata applied by :class:`BracketTracker`.
1228         Trailing commas are maybe removed, unpacked for loop variables are
1229         demoted from being delimiters.
1230
1231         Inline comments are put aside.
1232         """
1233         has_value = leaf.type in BRACKETS or bool(leaf.value.strip())
1234         if not has_value:
1235             return
1236
1237         if token.COLON == leaf.type and self.is_class_paren_empty:
1238             del self.leaves[-2:]
1239         if self.leaves and not preformatted:
1240             # Note: at this point leaf.prefix should be empty except for
1241             # imports, for which we only preserve newlines.
1242             leaf.prefix += whitespace(
1243                 leaf, complex_subscript=self.is_complex_subscript(leaf)
1244             )
1245         if self.inside_brackets or not preformatted:
1246             self.bracket_tracker.mark(leaf)
1247             self.maybe_remove_trailing_comma(leaf)
1248         if not self.append_comment(leaf):
1249             self.leaves.append(leaf)
1250
1251     def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
1252         """Like :func:`append()` but disallow invalid standalone comment structure.
1253
1254         Raises ValueError when any `leaf` is appended after a standalone comment
1255         or when a standalone comment is not the first leaf on the line.
1256         """
1257         if self.bracket_tracker.depth == 0:
1258             if self.is_comment:
1259                 raise ValueError("cannot append to standalone comments")
1260
1261             if self.leaves and leaf.type == STANDALONE_COMMENT:
1262                 raise ValueError(
1263                     "cannot append standalone comments to a populated line"
1264                 )
1265
1266         self.append(leaf, preformatted=preformatted)
1267
1268     @property
1269     def is_comment(self) -> bool:
1270         """Is this line a standalone comment?"""
1271         return len(self.leaves) == 1 and self.leaves[0].type == STANDALONE_COMMENT
1272
1273     @property
1274     def is_decorator(self) -> bool:
1275         """Is this line a decorator?"""
1276         return bool(self) and self.leaves[0].type == token.AT
1277
1278     @property
1279     def is_import(self) -> bool:
1280         """Is this an import line?"""
1281         return bool(self) and is_import(self.leaves[0])
1282
1283     @property
1284     def is_class(self) -> bool:
1285         """Is this line a class definition?"""
1286         return (
1287             bool(self)
1288             and self.leaves[0].type == token.NAME
1289             and self.leaves[0].value == "class"
1290         )
1291
1292     @property
1293     def is_stub_class(self) -> bool:
1294         """Is this line a class definition with a body consisting only of "..."?"""
1295         return self.is_class and self.leaves[-3:] == [
1296             Leaf(token.DOT, ".") for _ in range(3)
1297         ]
1298
1299     @property
1300     def is_collection_with_optional_trailing_comma(self) -> bool:
1301         """Is this line a collection literal with a trailing comma that's optional?
1302
1303         Note that the trailing comma in a 1-tuple is not optional.
1304         """
1305         if not self.leaves or len(self.leaves) < 4:
1306             return False
1307
1308         # Look for and address a trailing colon.
1309         if self.leaves[-1].type == token.COLON:
1310             closer = self.leaves[-2]
1311             close_index = -2
1312         else:
1313             closer = self.leaves[-1]
1314             close_index = -1
1315         if closer.type not in CLOSING_BRACKETS or self.inside_brackets:
1316             return False
1317
1318         if closer.type == token.RPAR:
1319             # Tuples require an extra check, because if there's only
1320             # one element in the tuple removing the comma unmakes the
1321             # tuple.
1322             #
1323             # We also check for parens before looking for the trailing
1324             # comma because in some cases (eg assigning a dict
1325             # literal) the literal gets wrapped in temporary parens
1326             # during parsing. This case is covered by the
1327             # collections.py test data.
1328             opener = closer.opening_bracket
1329             for _open_index, leaf in enumerate(self.leaves):
1330                 if leaf is opener:
1331                     break
1332
1333             else:
1334                 # Couldn't find the matching opening paren, play it safe.
1335                 return False
1336
1337             commas = 0
1338             comma_depth = self.leaves[close_index - 1].bracket_depth
1339             for leaf in self.leaves[_open_index + 1 : close_index]:
1340                 if leaf.bracket_depth == comma_depth and leaf.type == token.COMMA:
1341                     commas += 1
1342             if commas > 1:
1343                 # We haven't looked yet for the trailing comma because
1344                 # we might also have caught noop parens.
1345                 return self.leaves[close_index - 1].type == token.COMMA
1346
1347             elif commas == 1:
1348                 return False  # it's either a one-tuple or didn't have a trailing comma
1349
1350             if self.leaves[close_index - 1].type in CLOSING_BRACKETS:
1351                 close_index -= 1
1352                 closer = self.leaves[close_index]
1353                 if closer.type == token.RPAR:
1354                     # TODO: this is a gut feeling. Will we ever see this?
1355                     return False
1356
1357         if self.leaves[close_index - 1].type != token.COMMA:
1358             return False
1359
1360         return True
1361
1362     @property
1363     def is_def(self) -> bool:
1364         """Is this a function definition? (Also returns True for async defs.)"""
1365         try:
1366             first_leaf = self.leaves[0]
1367         except IndexError:
1368             return False
1369
1370         try:
1371             second_leaf: Optional[Leaf] = self.leaves[1]
1372         except IndexError:
1373             second_leaf = None
1374         return (first_leaf.type == token.NAME and first_leaf.value == "def") or (
1375             first_leaf.type == token.ASYNC
1376             and second_leaf is not None
1377             and second_leaf.type == token.NAME
1378             and second_leaf.value == "def"
1379         )
1380
1381     @property
1382     def is_class_paren_empty(self) -> bool:
1383         """Is this a class with no base classes but using parentheses?
1384
1385         Those are unnecessary and should be removed.
1386         """
1387         return (
1388             bool(self)
1389             and len(self.leaves) == 4
1390             and self.is_class
1391             and self.leaves[2].type == token.LPAR
1392             and self.leaves[2].value == "("
1393             and self.leaves[3].type == token.RPAR
1394             and self.leaves[3].value == ")"
1395         )
1396
1397     @property
1398     def is_triple_quoted_string(self) -> bool:
1399         """Is the line a triple quoted string?"""
1400         return (
1401             bool(self)
1402             and self.leaves[0].type == token.STRING
1403             and self.leaves[0].value.startswith(('"""', "'''"))
1404         )
1405
1406     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
1407         """If so, needs to be split before emitting."""
1408         for leaf in self.leaves:
1409             if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
1410                 return True
1411
1412         return False
1413
1414     def contains_uncollapsable_type_comments(self) -> bool:
1415         ignored_ids = set()
1416         try:
1417             last_leaf = self.leaves[-1]
1418             ignored_ids.add(id(last_leaf))
1419             if last_leaf.type == token.COMMA or (
1420                 last_leaf.type == token.RPAR and not last_leaf.value
1421             ):
1422                 # When trailing commas or optional parens are inserted by Black for
1423                 # consistency, comments after the previous last element are not moved
1424                 # (they don't have to, rendering will still be correct).  So we ignore
1425                 # trailing commas and invisible.
1426                 last_leaf = self.leaves[-2]
1427                 ignored_ids.add(id(last_leaf))
1428         except IndexError:
1429             return False
1430
1431         # A type comment is uncollapsable if it is attached to a leaf
1432         # that isn't at the end of the line (since that could cause it
1433         # to get associated to a different argument) or if there are
1434         # comments before it (since that could cause it to get hidden
1435         # behind a comment.
1436         comment_seen = False
1437         for leaf_id, comments in self.comments.items():
1438             for comment in comments:
1439                 if is_type_comment(comment):
1440                     if comment_seen or (
1441                         not is_type_comment(comment, " ignore")
1442                         and leaf_id not in ignored_ids
1443                     ):
1444                         return True
1445
1446                 comment_seen = True
1447
1448         return False
1449
1450     def contains_unsplittable_type_ignore(self) -> bool:
1451         if not self.leaves:
1452             return False
1453
1454         # If a 'type: ignore' is attached to the end of a line, we
1455         # can't split the line, because we can't know which of the
1456         # subexpressions the ignore was meant to apply to.
1457         #
1458         # We only want this to apply to actual physical lines from the
1459         # original source, though: we don't want the presence of a
1460         # 'type: ignore' at the end of a multiline expression to
1461         # justify pushing it all onto one line. Thus we
1462         # (unfortunately) need to check the actual source lines and
1463         # only report an unsplittable 'type: ignore' if this line was
1464         # one line in the original code.
1465
1466         # Grab the first and last line numbers, skipping generated leaves
1467         first_line = next((l.lineno for l in self.leaves if l.lineno != 0), 0)
1468         last_line = next((l.lineno for l in reversed(self.leaves) if l.lineno != 0), 0)
1469
1470         if first_line == last_line:
1471             # We look at the last two leaves since a comma or an
1472             # invisible paren could have been added at the end of the
1473             # line.
1474             for node in self.leaves[-2:]:
1475                 for comment in self.comments.get(id(node), []):
1476                     if is_type_comment(comment, " ignore"):
1477                         return True
1478
1479         return False
1480
1481     def contains_multiline_strings(self) -> bool:
1482         return any(is_multiline_string(leaf) for leaf in self.leaves)
1483
1484     def maybe_remove_trailing_comma(self, closing: Leaf) -> bool:
1485         """Remove trailing comma if there is one and it's safe."""
1486         if not (self.leaves and self.leaves[-1].type == token.COMMA):
1487             return False
1488
1489         # We remove trailing commas only in the case of importing a
1490         # single name from a module.
1491         if not (
1492             self.leaves
1493             and self.is_import
1494             and len(self.leaves) > 4
1495             and self.leaves[-1].type == token.COMMA
1496             and closing.type in CLOSING_BRACKETS
1497             and self.leaves[-4].type == token.NAME
1498             and (
1499                 # regular `from foo import bar,`
1500                 self.leaves[-4].value == "import"
1501                 # `from foo import (bar as baz,)
1502                 or (
1503                     len(self.leaves) > 6
1504                     and self.leaves[-6].value == "import"
1505                     and self.leaves[-3].value == "as"
1506                 )
1507                 # `from foo import bar as baz,`
1508                 or (
1509                     len(self.leaves) > 5
1510                     and self.leaves[-5].value == "import"
1511                     and self.leaves[-3].value == "as"
1512                 )
1513             )
1514             and closing.type == token.RPAR
1515         ):
1516             return False
1517
1518         self.remove_trailing_comma()
1519         return True
1520
1521     def append_comment(self, comment: Leaf) -> bool:
1522         """Add an inline or standalone comment to the line."""
1523         if (
1524             comment.type == STANDALONE_COMMENT
1525             and self.bracket_tracker.any_open_brackets()
1526         ):
1527             comment.prefix = ""
1528             return False
1529
1530         if comment.type != token.COMMENT:
1531             return False
1532
1533         if not self.leaves:
1534             comment.type = STANDALONE_COMMENT
1535             comment.prefix = ""
1536             return False
1537
1538         last_leaf = self.leaves[-1]
1539         if (
1540             last_leaf.type == token.RPAR
1541             and not last_leaf.value
1542             and last_leaf.parent
1543             and len(list(last_leaf.parent.leaves())) <= 3
1544             and not is_type_comment(comment)
1545         ):
1546             # Comments on an optional parens wrapping a single leaf should belong to
1547             # the wrapped node except if it's a type comment. Pinning the comment like
1548             # this avoids unstable formatting caused by comment migration.
1549             if len(self.leaves) < 2:
1550                 comment.type = STANDALONE_COMMENT
1551                 comment.prefix = ""
1552                 return False
1553
1554             last_leaf = self.leaves[-2]
1555         self.comments.setdefault(id(last_leaf), []).append(comment)
1556         return True
1557
1558     def comments_after(self, leaf: Leaf) -> List[Leaf]:
1559         """Generate comments that should appear directly after `leaf`."""
1560         return self.comments.get(id(leaf), [])
1561
1562     def remove_trailing_comma(self) -> None:
1563         """Remove the trailing comma and moves the comments attached to it."""
1564         trailing_comma = self.leaves.pop()
1565         trailing_comma_comments = self.comments.pop(id(trailing_comma), [])
1566         self.comments.setdefault(id(self.leaves[-1]), []).extend(
1567             trailing_comma_comments
1568         )
1569
1570     def is_complex_subscript(self, leaf: Leaf) -> bool:
1571         """Return True iff `leaf` is part of a slice with non-trivial exprs."""
1572         open_lsqb = self.bracket_tracker.get_open_lsqb()
1573         if open_lsqb is None:
1574             return False
1575
1576         subscript_start = open_lsqb.next_sibling
1577
1578         if isinstance(subscript_start, Node):
1579             if subscript_start.type == syms.listmaker:
1580                 return False
1581
1582             if subscript_start.type == syms.subscriptlist:
1583                 subscript_start = child_towards(subscript_start, leaf)
1584         return subscript_start is not None and any(
1585             n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
1586         )
1587
1588     def __str__(self) -> str:
1589         """Render the line."""
1590         if not self:
1591             return "\n"
1592
1593         indent = "    " * self.depth
1594         leaves = iter(self.leaves)
1595         first = next(leaves)
1596         res = f"{first.prefix}{indent}{first.value}"
1597         for leaf in leaves:
1598             res += str(leaf)
1599         for comment in itertools.chain.from_iterable(self.comments.values()):
1600             res += str(comment)
1601         return res + "\n"
1602
1603     def __bool__(self) -> bool:
1604         """Return True if the line has leaves or comments."""
1605         return bool(self.leaves or self.comments)
1606
1607
1608 @dataclass
1609 class EmptyLineTracker:
1610     """Provides a stateful method that returns the number of potential extra
1611     empty lines needed before and after the currently processed line.
1612
1613     Note: this tracker works on lines that haven't been split yet.  It assumes
1614     the prefix of the first leaf consists of optional newlines.  Those newlines
1615     are consumed by `maybe_empty_lines()` and included in the computation.
1616     """
1617
1618     is_pyi: bool = False
1619     previous_line: Optional[Line] = None
1620     previous_after: int = 0
1621     previous_defs: List[int] = field(default_factory=list)
1622
1623     def maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
1624         """Return the number of extra empty lines before and after the `current_line`.
1625
1626         This is for separating `def`, `async def` and `class` with extra empty
1627         lines (two on module-level).
1628         """
1629         before, after = self._maybe_empty_lines(current_line)
1630         before = (
1631             # Black should not insert empty lines at the beginning
1632             # of the file
1633             0
1634             if self.previous_line is None
1635             else before - self.previous_after
1636         )
1637         self.previous_after = after
1638         self.previous_line = current_line
1639         return before, after
1640
1641     def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
1642         max_allowed = 1
1643         if current_line.depth == 0:
1644             max_allowed = 1 if self.is_pyi else 2
1645         if current_line.leaves:
1646             # Consume the first leaf's extra newlines.
1647             first_leaf = current_line.leaves[0]
1648             before = first_leaf.prefix.count("\n")
1649             before = min(before, max_allowed)
1650             first_leaf.prefix = ""
1651         else:
1652             before = 0
1653         depth = current_line.depth
1654         while self.previous_defs and self.previous_defs[-1] >= depth:
1655             self.previous_defs.pop()
1656             if self.is_pyi:
1657                 before = 0 if depth else 1
1658             else:
1659                 before = 1 if depth else 2
1660         if current_line.is_decorator or current_line.is_def or current_line.is_class:
1661             return self._maybe_empty_lines_for_class_or_def(current_line, before)
1662
1663         if (
1664             self.previous_line
1665             and self.previous_line.is_import
1666             and not current_line.is_import
1667             and depth == self.previous_line.depth
1668         ):
1669             return (before or 1), 0
1670
1671         if (
1672             self.previous_line
1673             and self.previous_line.is_class
1674             and current_line.is_triple_quoted_string
1675         ):
1676             return before, 1
1677
1678         return before, 0
1679
1680     def _maybe_empty_lines_for_class_or_def(
1681         self, current_line: Line, before: int
1682     ) -> Tuple[int, int]:
1683         if not current_line.is_decorator:
1684             self.previous_defs.append(current_line.depth)
1685         if self.previous_line is None:
1686             # Don't insert empty lines before the first line in the file.
1687             return 0, 0
1688
1689         if self.previous_line.is_decorator:
1690             return 0, 0
1691
1692         if self.previous_line.depth < current_line.depth and (
1693             self.previous_line.is_class or self.previous_line.is_def
1694         ):
1695             return 0, 0
1696
1697         if (
1698             self.previous_line.is_comment
1699             and self.previous_line.depth == current_line.depth
1700             and before == 0
1701         ):
1702             return 0, 0
1703
1704         if self.is_pyi:
1705             if self.previous_line.depth > current_line.depth:
1706                 newlines = 1
1707             elif current_line.is_class or self.previous_line.is_class:
1708                 if current_line.is_stub_class and self.previous_line.is_stub_class:
1709                     # No blank line between classes with an empty body
1710                     newlines = 0
1711                 else:
1712                     newlines = 1
1713             elif current_line.is_def and not self.previous_line.is_def:
1714                 # Blank line between a block of functions and a block of non-functions
1715                 newlines = 1
1716             else:
1717                 newlines = 0
1718         else:
1719             newlines = 2
1720         if current_line.depth and newlines:
1721             newlines -= 1
1722         return newlines, 0
1723
1724
1725 @dataclass
1726 class LineGenerator(Visitor[Line]):
1727     """Generates reformatted Line objects.  Empty lines are not emitted.
1728
1729     Note: destroys the tree it's visiting by mutating prefixes of its leaves
1730     in ways that will no longer stringify to valid Python code on the tree.
1731     """
1732
1733     is_pyi: bool = False
1734     normalize_strings: bool = True
1735     current_line: Line = field(default_factory=Line)
1736     remove_u_prefix: bool = False
1737
1738     def line(self, indent: int = 0) -> Iterator[Line]:
1739         """Generate a line.
1740
1741         If the line is empty, only emit if it makes sense.
1742         If the line is too long, split it first and then generate.
1743
1744         If any lines were generated, set up a new current_line.
1745         """
1746         if not self.current_line:
1747             self.current_line.depth += indent
1748             return  # Line is empty, don't emit. Creating a new one unnecessary.
1749
1750         complete_line = self.current_line
1751         self.current_line = Line(depth=complete_line.depth + indent)
1752         yield complete_line
1753
1754     def visit_default(self, node: LN) -> Iterator[Line]:
1755         """Default `visit_*()` implementation. Recurses to children of `node`."""
1756         if isinstance(node, Leaf):
1757             any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
1758             for comment in generate_comments(node):
1759                 if any_open_brackets:
1760                     # any comment within brackets is subject to splitting
1761                     self.current_line.append(comment)
1762                 elif comment.type == token.COMMENT:
1763                     # regular trailing comment
1764                     self.current_line.append(comment)
1765                     yield from self.line()
1766
1767                 else:
1768                     # regular standalone comment
1769                     yield from self.line()
1770
1771                     self.current_line.append(comment)
1772                     yield from self.line()
1773
1774             normalize_prefix(node, inside_brackets=any_open_brackets)
1775             if self.normalize_strings and node.type == token.STRING:
1776                 normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
1777                 normalize_string_quotes(node)
1778             if node.type == token.NUMBER:
1779                 normalize_numeric_literal(node)
1780             if node.type not in WHITESPACE:
1781                 self.current_line.append(node)
1782         yield from super().visit_default(node)
1783
1784     def visit_INDENT(self, node: Leaf) -> Iterator[Line]:
1785         """Increase indentation level, maybe yield a line."""
1786         # In blib2to3 INDENT never holds comments.
1787         yield from self.line(+1)
1788         yield from self.visit_default(node)
1789
1790     def visit_DEDENT(self, node: Leaf) -> Iterator[Line]:
1791         """Decrease indentation level, maybe yield a line."""
1792         # The current line might still wait for trailing comments.  At DEDENT time
1793         # there won't be any (they would be prefixes on the preceding NEWLINE).
1794         # Emit the line then.
1795         yield from self.line()
1796
1797         # While DEDENT has no value, its prefix may contain standalone comments
1798         # that belong to the current indentation level.  Get 'em.
1799         yield from self.visit_default(node)
1800
1801         # Finally, emit the dedent.
1802         yield from self.line(-1)
1803
1804     def visit_stmt(
1805         self, node: Node, keywords: Set[str], parens: Set[str]
1806     ) -> Iterator[Line]:
1807         """Visit a statement.
1808
1809         This implementation is shared for `if`, `while`, `for`, `try`, `except`,
1810         `def`, `with`, `class`, `assert` and assignments.
1811
1812         The relevant Python language `keywords` for a given statement will be
1813         NAME leaves within it. This methods puts those on a separate line.
1814
1815         `parens` holds a set of string leaf values immediately after which
1816         invisible parens should be put.
1817         """
1818         normalize_invisible_parens(node, parens_after=parens)
1819         for child in node.children:
1820             if child.type == token.NAME and child.value in keywords:  # type: ignore
1821                 yield from self.line()
1822
1823             yield from self.visit(child)
1824
1825     def visit_suite(self, node: Node) -> Iterator[Line]:
1826         """Visit a suite."""
1827         if self.is_pyi and is_stub_suite(node):
1828             yield from self.visit(node.children[2])
1829         else:
1830             yield from self.visit_default(node)
1831
1832     def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
1833         """Visit a statement without nested statements."""
1834         is_suite_like = node.parent and node.parent.type in STATEMENT
1835         if is_suite_like:
1836             if self.is_pyi and is_stub_body(node):
1837                 yield from self.visit_default(node)
1838             else:
1839                 yield from self.line(+1)
1840                 yield from self.visit_default(node)
1841                 yield from self.line(-1)
1842
1843         else:
1844             if not self.is_pyi or not node.parent or not is_stub_suite(node.parent):
1845                 yield from self.line()
1846             yield from self.visit_default(node)
1847
1848     def visit_async_stmt(self, node: Node) -> Iterator[Line]:
1849         """Visit `async def`, `async for`, `async with`."""
1850         yield from self.line()
1851
1852         children = iter(node.children)
1853         for child in children:
1854             yield from self.visit(child)
1855
1856             if child.type == token.ASYNC:
1857                 break
1858
1859         internal_stmt = next(children)
1860         for child in internal_stmt.children:
1861             yield from self.visit(child)
1862
1863     def visit_decorators(self, node: Node) -> Iterator[Line]:
1864         """Visit decorators."""
1865         for child in node.children:
1866             yield from self.line()
1867             yield from self.visit(child)
1868
1869     def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
1870         """Remove a semicolon and put the other statement on a separate line."""
1871         yield from self.line()
1872
1873     def visit_ENDMARKER(self, leaf: Leaf) -> Iterator[Line]:
1874         """End of file. Process outstanding comments and end with a newline."""
1875         yield from self.visit_default(leaf)
1876         yield from self.line()
1877
1878     def visit_STANDALONE_COMMENT(self, leaf: Leaf) -> Iterator[Line]:
1879         if not self.current_line.bracket_tracker.any_open_brackets():
1880             yield from self.line()
1881         yield from self.visit_default(leaf)
1882
1883     def visit_factor(self, node: Node) -> Iterator[Line]:
1884         """Force parentheses between a unary op and a binary power:
1885
1886         -2 ** 8 -> -(2 ** 8)
1887         """
1888         _operator, operand = node.children
1889         if (
1890             operand.type == syms.power
1891             and len(operand.children) == 3
1892             and operand.children[1].type == token.DOUBLESTAR
1893         ):
1894             lpar = Leaf(token.LPAR, "(")
1895             rpar = Leaf(token.RPAR, ")")
1896             index = operand.remove() or 0
1897             node.insert_child(index, Node(syms.atom, [lpar, operand, rpar]))
1898         yield from self.visit_default(node)
1899
1900     def __post_init__(self) -> None:
1901         """You are in a twisty little maze of passages."""
1902         v = self.visit_stmt
1903         Ø: Set[str] = set()
1904         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
1905         self.visit_if_stmt = partial(
1906             v, keywords={"if", "else", "elif"}, parens={"if", "elif"}
1907         )
1908         self.visit_while_stmt = partial(v, keywords={"while", "else"}, parens={"while"})
1909         self.visit_for_stmt = partial(v, keywords={"for", "else"}, parens={"for", "in"})
1910         self.visit_try_stmt = partial(
1911             v, keywords={"try", "except", "else", "finally"}, parens=Ø
1912         )
1913         self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
1914         self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
1915         self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
1916         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
1917         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
1918         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
1919         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
1920         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
1921         self.visit_async_funcdef = self.visit_async_stmt
1922         self.visit_decorated = self.visit_decorators
1923
1924
1925 IMPLICIT_TUPLE = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
1926 BRACKET = {token.LPAR: token.RPAR, token.LSQB: token.RSQB, token.LBRACE: token.RBRACE}
1927 OPENING_BRACKETS = set(BRACKET.keys())
1928 CLOSING_BRACKETS = set(BRACKET.values())
1929 BRACKETS = OPENING_BRACKETS | CLOSING_BRACKETS
1930 ALWAYS_NO_SPACE = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
1931
1932
1933 def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
1934     """Return whitespace prefix if needed for the given `leaf`.
1935
1936     `complex_subscript` signals whether the given leaf is part of a subscription
1937     which has non-trivial arguments, like arithmetic expressions or function calls.
1938     """
1939     NO = ""
1940     SPACE = " "
1941     DOUBLESPACE = "  "
1942     t = leaf.type
1943     p = leaf.parent
1944     v = leaf.value
1945     if t in ALWAYS_NO_SPACE:
1946         return NO
1947
1948     if t == token.COMMENT:
1949         return DOUBLESPACE
1950
1951     assert p is not None, f"INTERNAL ERROR: hand-made leaf without parent: {leaf!r}"
1952     if t == token.COLON and p.type not in {
1953         syms.subscript,
1954         syms.subscriptlist,
1955         syms.sliceop,
1956     }:
1957         return NO
1958
1959     prev = leaf.prev_sibling
1960     if not prev:
1961         prevp = preceding_leaf(p)
1962         if not prevp or prevp.type in OPENING_BRACKETS:
1963             return NO
1964
1965         if t == token.COLON:
1966             if prevp.type == token.COLON:
1967                 return NO
1968
1969             elif prevp.type != token.COMMA and not complex_subscript:
1970                 return NO
1971
1972             return SPACE
1973
1974         if prevp.type == token.EQUAL:
1975             if prevp.parent:
1976                 if prevp.parent.type in {
1977                     syms.arglist,
1978                     syms.argument,
1979                     syms.parameters,
1980                     syms.varargslist,
1981                 }:
1982                     return NO
1983
1984                 elif prevp.parent.type == syms.typedargslist:
1985                     # A bit hacky: if the equal sign has whitespace, it means we
1986                     # previously found it's a typed argument.  So, we're using
1987                     # that, too.
1988                     return prevp.prefix
1989
1990         elif prevp.type in VARARGS_SPECIALS:
1991             if is_vararg(prevp, within=VARARGS_PARENTS | UNPACKING_PARENTS):
1992                 return NO
1993
1994         elif prevp.type == token.COLON:
1995             if prevp.parent and prevp.parent.type in {syms.subscript, syms.sliceop}:
1996                 return SPACE if complex_subscript else NO
1997
1998         elif (
1999             prevp.parent
2000             and prevp.parent.type == syms.factor
2001             and prevp.type in MATH_OPERATORS
2002         ):
2003             return NO
2004
2005         elif (
2006             prevp.type == token.RIGHTSHIFT
2007             and prevp.parent
2008             and prevp.parent.type == syms.shift_expr
2009             and prevp.prev_sibling
2010             and prevp.prev_sibling.type == token.NAME
2011             and prevp.prev_sibling.value == "print"  # type: ignore
2012         ):
2013             # Python 2 print chevron
2014             return NO
2015
2016     elif prev.type in OPENING_BRACKETS:
2017         return NO
2018
2019     if p.type in {syms.parameters, syms.arglist}:
2020         # untyped function signatures or calls
2021         if not prev or prev.type != token.COMMA:
2022             return NO
2023
2024     elif p.type == syms.varargslist:
2025         # lambdas
2026         if prev and prev.type != token.COMMA:
2027             return NO
2028
2029     elif p.type == syms.typedargslist:
2030         # typed function signatures
2031         if not prev:
2032             return NO
2033
2034         if t == token.EQUAL:
2035             if prev.type != syms.tname:
2036                 return NO
2037
2038         elif prev.type == token.EQUAL:
2039             # A bit hacky: if the equal sign has whitespace, it means we
2040             # previously found it's a typed argument.  So, we're using that, too.
2041             return prev.prefix
2042
2043         elif prev.type != token.COMMA:
2044             return NO
2045
2046     elif p.type == syms.tname:
2047         # type names
2048         if not prev:
2049             prevp = preceding_leaf(p)
2050             if not prevp or prevp.type != token.COMMA:
2051                 return NO
2052
2053     elif p.type == syms.trailer:
2054         # attributes and calls
2055         if t == token.LPAR or t == token.RPAR:
2056             return NO
2057
2058         if not prev:
2059             if t == token.DOT:
2060                 prevp = preceding_leaf(p)
2061                 if not prevp or prevp.type != token.NUMBER:
2062                     return NO
2063
2064             elif t == token.LSQB:
2065                 return NO
2066
2067         elif prev.type != token.COMMA:
2068             return NO
2069
2070     elif p.type == syms.argument:
2071         # single argument
2072         if t == token.EQUAL:
2073             return NO
2074
2075         if not prev:
2076             prevp = preceding_leaf(p)
2077             if not prevp or prevp.type == token.LPAR:
2078                 return NO
2079
2080         elif prev.type in {token.EQUAL} | VARARGS_SPECIALS:
2081             return NO
2082
2083     elif p.type == syms.decorator:
2084         # decorators
2085         return NO
2086
2087     elif p.type == syms.dotted_name:
2088         if prev:
2089             return NO
2090
2091         prevp = preceding_leaf(p)
2092         if not prevp or prevp.type == token.AT or prevp.type == token.DOT:
2093             return NO
2094
2095     elif p.type == syms.classdef:
2096         if t == token.LPAR:
2097             return NO
2098
2099         if prev and prev.type == token.LPAR:
2100             return NO
2101
2102     elif p.type in {syms.subscript, syms.sliceop}:
2103         # indexing
2104         if not prev:
2105             assert p.parent is not None, "subscripts are always parented"
2106             if p.parent.type == syms.subscriptlist:
2107                 return SPACE
2108
2109             return NO
2110
2111         elif not complex_subscript:
2112             return NO
2113
2114     elif p.type == syms.atom:
2115         if prev and t == token.DOT:
2116             # dots, but not the first one.
2117             return NO
2118
2119     elif p.type == syms.dictsetmaker:
2120         # dict unpacking
2121         if prev and prev.type == token.DOUBLESTAR:
2122             return NO
2123
2124     elif p.type in {syms.factor, syms.star_expr}:
2125         # unary ops
2126         if not prev:
2127             prevp = preceding_leaf(p)
2128             if not prevp or prevp.type in OPENING_BRACKETS:
2129                 return NO
2130
2131             prevp_parent = prevp.parent
2132             assert prevp_parent is not None
2133             if prevp.type == token.COLON and prevp_parent.type in {
2134                 syms.subscript,
2135                 syms.sliceop,
2136             }:
2137                 return NO
2138
2139             elif prevp.type == token.EQUAL and prevp_parent.type == syms.argument:
2140                 return NO
2141
2142         elif t in {token.NAME, token.NUMBER, token.STRING}:
2143             return NO
2144
2145     elif p.type == syms.import_from:
2146         if t == token.DOT:
2147             if prev and prev.type == token.DOT:
2148                 return NO
2149
2150         elif t == token.NAME:
2151             if v == "import":
2152                 return SPACE
2153
2154             if prev and prev.type == token.DOT:
2155                 return NO
2156
2157     elif p.type == syms.sliceop:
2158         return NO
2159
2160     return SPACE
2161
2162
2163 def preceding_leaf(node: Optional[LN]) -> Optional[Leaf]:
2164     """Return the first leaf that precedes `node`, if any."""
2165     while node:
2166         res = node.prev_sibling
2167         if res:
2168             if isinstance(res, Leaf):
2169                 return res
2170
2171             try:
2172                 return list(res.leaves())[-1]
2173
2174             except IndexError:
2175                 return None
2176
2177         node = node.parent
2178     return None
2179
2180
2181 def child_towards(ancestor: Node, descendant: LN) -> Optional[LN]:
2182     """Return the child of `ancestor` that contains `descendant`."""
2183     node: Optional[LN] = descendant
2184     while node and node.parent != ancestor:
2185         node = node.parent
2186     return node
2187
2188
2189 def container_of(leaf: Leaf) -> LN:
2190     """Return `leaf` or one of its ancestors that is the topmost container of it.
2191
2192     By "container" we mean a node where `leaf` is the very first child.
2193     """
2194     same_prefix = leaf.prefix
2195     container: LN = leaf
2196     while container:
2197         parent = container.parent
2198         if parent is None:
2199             break
2200
2201         if parent.children[0].prefix != same_prefix:
2202             break
2203
2204         if parent.type == syms.file_input:
2205             break
2206
2207         if parent.prev_sibling is not None and parent.prev_sibling.type in BRACKETS:
2208             break
2209
2210         container = parent
2211     return container
2212
2213
2214 def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
2215     """Return the priority of the `leaf` delimiter, given a line break after it.
2216
2217     The delimiter priorities returned here are from those delimiters that would
2218     cause a line break after themselves.
2219
2220     Higher numbers are higher priority.
2221     """
2222     if leaf.type == token.COMMA:
2223         return COMMA_PRIORITY
2224
2225     return 0
2226
2227
2228 def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
2229     """Return the priority of the `leaf` delimiter, given a line break before it.
2230
2231     The delimiter priorities returned here are from those delimiters that would
2232     cause a line break before themselves.
2233
2234     Higher numbers are higher priority.
2235     """
2236     if is_vararg(leaf, within=VARARGS_PARENTS | UNPACKING_PARENTS):
2237         # * and ** might also be MATH_OPERATORS but in this case they are not.
2238         # Don't treat them as a delimiter.
2239         return 0
2240
2241     if (
2242         leaf.type == token.DOT
2243         and leaf.parent
2244         and leaf.parent.type not in {syms.import_from, syms.dotted_name}
2245         and (previous is None or previous.type in CLOSING_BRACKETS)
2246     ):
2247         return DOT_PRIORITY
2248
2249     if (
2250         leaf.type in MATH_OPERATORS
2251         and leaf.parent
2252         and leaf.parent.type not in {syms.factor, syms.star_expr}
2253     ):
2254         return MATH_PRIORITIES[leaf.type]
2255
2256     if leaf.type in COMPARATORS:
2257         return COMPARATOR_PRIORITY
2258
2259     if (
2260         leaf.type == token.STRING
2261         and previous is not None
2262         and previous.type == token.STRING
2263     ):
2264         return STRING_PRIORITY
2265
2266     if leaf.type not in {token.NAME, token.ASYNC}:
2267         return 0
2268
2269     if (
2270         leaf.value == "for"
2271         and leaf.parent
2272         and leaf.parent.type in {syms.comp_for, syms.old_comp_for}
2273         or leaf.type == token.ASYNC
2274     ):
2275         if (
2276             not isinstance(leaf.prev_sibling, Leaf)
2277             or leaf.prev_sibling.value != "async"
2278         ):
2279             return COMPREHENSION_PRIORITY
2280
2281     if (
2282         leaf.value == "if"
2283         and leaf.parent
2284         and leaf.parent.type in {syms.comp_if, syms.old_comp_if}
2285     ):
2286         return COMPREHENSION_PRIORITY
2287
2288     if leaf.value in {"if", "else"} and leaf.parent and leaf.parent.type == syms.test:
2289         return TERNARY_PRIORITY
2290
2291     if leaf.value == "is":
2292         return COMPARATOR_PRIORITY
2293
2294     if (
2295         leaf.value == "in"
2296         and leaf.parent
2297         and leaf.parent.type in {syms.comp_op, syms.comparison}
2298         and not (
2299             previous is not None
2300             and previous.type == token.NAME
2301             and previous.value == "not"
2302         )
2303     ):
2304         return COMPARATOR_PRIORITY
2305
2306     if (
2307         leaf.value == "not"
2308         and leaf.parent
2309         and leaf.parent.type == syms.comp_op
2310         and not (
2311             previous is not None
2312             and previous.type == token.NAME
2313             and previous.value == "is"
2314         )
2315     ):
2316         return COMPARATOR_PRIORITY
2317
2318     if leaf.value in LOGIC_OPERATORS and leaf.parent:
2319         return LOGIC_PRIORITY
2320
2321     return 0
2322
2323
2324 FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
2325 FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
2326
2327
2328 def generate_comments(leaf: LN) -> Iterator[Leaf]:
2329     """Clean the prefix of the `leaf` and generate comments from it, if any.
2330
2331     Comments in lib2to3 are shoved into the whitespace prefix.  This happens
2332     in `pgen2/driver.py:Driver.parse_tokens()`.  This was a brilliant implementation
2333     move because it does away with modifying the grammar to include all the
2334     possible places in which comments can be placed.
2335
2336     The sad consequence for us though is that comments don't "belong" anywhere.
2337     This is why this function generates simple parentless Leaf objects for
2338     comments.  We simply don't know what the correct parent should be.
2339
2340     No matter though, we can live without this.  We really only need to
2341     differentiate between inline and standalone comments.  The latter don't
2342     share the line with any code.
2343
2344     Inline comments are emitted as regular token.COMMENT leaves.  Standalone
2345     are emitted with a fake STANDALONE_COMMENT token identifier.
2346     """
2347     for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
2348         yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
2349
2350
2351 @dataclass
2352 class ProtoComment:
2353     """Describes a piece of syntax that is a comment.
2354
2355     It's not a :class:`blib2to3.pytree.Leaf` so that:
2356
2357     * it can be cached (`Leaf` objects should not be reused more than once as
2358       they store their lineno, column, prefix, and parent information);
2359     * `newlines` and `consumed` fields are kept separate from the `value`. This
2360       simplifies handling of special marker comments like ``# fmt: off/on``.
2361     """
2362
2363     type: int  # token.COMMENT or STANDALONE_COMMENT
2364     value: str  # content of the comment
2365     newlines: int  # how many newlines before the comment
2366     consumed: int  # how many characters of the original leaf's prefix did we consume
2367
2368
2369 @lru_cache(maxsize=4096)
2370 def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
2371     """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
2372     result: List[ProtoComment] = []
2373     if not prefix or "#" not in prefix:
2374         return result
2375
2376     consumed = 0
2377     nlines = 0
2378     ignored_lines = 0
2379     for index, line in enumerate(prefix.split("\n")):
2380         consumed += len(line) + 1  # adding the length of the split '\n'
2381         line = line.lstrip()
2382         if not line:
2383             nlines += 1
2384         if not line.startswith("#"):
2385             # Escaped newlines outside of a comment are not really newlines at
2386             # all. We treat a single-line comment following an escaped newline
2387             # as a simple trailing comment.
2388             if line.endswith("\\"):
2389                 ignored_lines += 1
2390             continue
2391
2392         if index == ignored_lines and not is_endmarker:
2393             comment_type = token.COMMENT  # simple trailing comment
2394         else:
2395             comment_type = STANDALONE_COMMENT
2396         comment = make_comment(line)
2397         result.append(
2398             ProtoComment(
2399                 type=comment_type, value=comment, newlines=nlines, consumed=consumed
2400             )
2401         )
2402         nlines = 0
2403     return result
2404
2405
2406 def make_comment(content: str) -> str:
2407     """Return a consistently formatted comment from the given `content` string.
2408
2409     All comments (except for "##", "#!", "#:", '#'", "#%%") should have a single
2410     space between the hash sign and the content.
2411
2412     If `content` didn't start with a hash sign, one is provided.
2413     """
2414     content = content.rstrip()
2415     if not content:
2416         return "#"
2417
2418     if content[0] == "#":
2419         content = content[1:]
2420     if content and content[0] not in " !:#'%":
2421         content = " " + content
2422     return "#" + content
2423
2424
2425 def split_line(
2426     line: Line,
2427     line_length: int,
2428     inner: bool = False,
2429     features: Collection[Feature] = (),
2430 ) -> Iterator[Line]:
2431     """Split a `line` into potentially many lines.
2432
2433     They should fit in the allotted `line_length` but might not be able to.
2434     `inner` signifies that there were a pair of brackets somewhere around the
2435     current `line`, possibly transitively. This means we can fallback to splitting
2436     by delimiters if the LHS/RHS don't yield any results.
2437
2438     `features` are syntactical features that may be used in the output.
2439     """
2440     if line.is_comment:
2441         yield line
2442         return
2443
2444     line_str = str(line).strip("\n")
2445
2446     if (
2447         not line.contains_uncollapsable_type_comments()
2448         and not line.should_explode
2449         and not line.is_collection_with_optional_trailing_comma
2450         and (
2451             is_line_short_enough(line, line_length=line_length, line_str=line_str)
2452             or line.contains_unsplittable_type_ignore()
2453         )
2454     ):
2455         yield line
2456         return
2457
2458     split_funcs: List[SplitFunc]
2459     if line.is_def:
2460         split_funcs = [left_hand_split]
2461     else:
2462
2463         def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
2464             for omit in generate_trailers_to_omit(line, line_length):
2465                 lines = list(right_hand_split(line, line_length, features, omit=omit))
2466                 if is_line_short_enough(lines[0], line_length=line_length):
2467                     yield from lines
2468                     return
2469
2470             # All splits failed, best effort split with no omits.
2471             # This mostly happens to multiline strings that are by definition
2472             # reported as not fitting a single line.
2473             # line_length=1 here was historically a bug that somehow became a feature.
2474             # See #762 and #781 for the full story.
2475             yield from right_hand_split(line, line_length=1, features=features)
2476
2477         if line.inside_brackets:
2478             split_funcs = [delimiter_split, standalone_comment_split, rhs]
2479         else:
2480             split_funcs = [rhs]
2481     for split_func in split_funcs:
2482         # We are accumulating lines in `result` because we might want to abort
2483         # mission and return the original line in the end, or attempt a different
2484         # split altogether.
2485         result: List[Line] = []
2486         try:
2487             for l in split_func(line, features):
2488                 if str(l).strip("\n") == line_str:
2489                     raise CannotSplit("Split function returned an unchanged result")
2490
2491                 result.extend(
2492                     split_line(
2493                         l, line_length=line_length, inner=True, features=features
2494                     )
2495                 )
2496         except CannotSplit:
2497             continue
2498
2499         else:
2500             yield from result
2501             break
2502
2503     else:
2504         yield line
2505
2506
2507 def left_hand_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
2508     """Split line into many lines, starting with the first matching bracket pair.
2509
2510     Note: this usually looks weird, only use this for function definitions.
2511     Prefer RHS otherwise.  This is why this function is not symmetrical with
2512     :func:`right_hand_split` which also handles optional parentheses.
2513     """
2514     tail_leaves: List[Leaf] = []
2515     body_leaves: List[Leaf] = []
2516     head_leaves: List[Leaf] = []
2517     current_leaves = head_leaves
2518     matching_bracket: Optional[Leaf] = None
2519     for leaf in line.leaves:
2520         if (
2521             current_leaves is body_leaves
2522             and leaf.type in CLOSING_BRACKETS
2523             and leaf.opening_bracket is matching_bracket
2524         ):
2525             current_leaves = tail_leaves if body_leaves else head_leaves
2526         current_leaves.append(leaf)
2527         if current_leaves is head_leaves:
2528             if leaf.type in OPENING_BRACKETS:
2529                 matching_bracket = leaf
2530                 current_leaves = body_leaves
2531     if not matching_bracket:
2532         raise CannotSplit("No brackets found")
2533
2534     head = bracket_split_build_line(head_leaves, line, matching_bracket)
2535     body = bracket_split_build_line(body_leaves, line, matching_bracket, is_body=True)
2536     tail = bracket_split_build_line(tail_leaves, line, matching_bracket)
2537     bracket_split_succeeded_or_raise(head, body, tail)
2538     for result in (head, body, tail):
2539         if result:
2540             yield result
2541
2542
2543 def right_hand_split(
2544     line: Line,
2545     line_length: int,
2546     features: Collection[Feature] = (),
2547     omit: Collection[LeafID] = (),
2548 ) -> Iterator[Line]:
2549     """Split line into many lines, starting with the last matching bracket pair.
2550
2551     If the split was by optional parentheses, attempt splitting without them, too.
2552     `omit` is a collection of closing bracket IDs that shouldn't be considered for
2553     this split.
2554
2555     Note: running this function modifies `bracket_depth` on the leaves of `line`.
2556     """
2557     tail_leaves: List[Leaf] = []
2558     body_leaves: List[Leaf] = []
2559     head_leaves: List[Leaf] = []
2560     current_leaves = tail_leaves
2561     opening_bracket: Optional[Leaf] = None
2562     closing_bracket: Optional[Leaf] = None
2563     for leaf in reversed(line.leaves):
2564         if current_leaves is body_leaves:
2565             if leaf is opening_bracket:
2566                 current_leaves = head_leaves if body_leaves else tail_leaves
2567         current_leaves.append(leaf)
2568         if current_leaves is tail_leaves:
2569             if leaf.type in CLOSING_BRACKETS and id(leaf) not in omit:
2570                 opening_bracket = leaf.opening_bracket
2571                 closing_bracket = leaf
2572                 current_leaves = body_leaves
2573     if not (opening_bracket and closing_bracket and head_leaves):
2574         # If there is no opening or closing_bracket that means the split failed and
2575         # all content is in the tail.  Otherwise, if `head_leaves` are empty, it means
2576         # the matching `opening_bracket` wasn't available on `line` anymore.
2577         raise CannotSplit("No brackets found")
2578
2579     tail_leaves.reverse()
2580     body_leaves.reverse()
2581     head_leaves.reverse()
2582     head = bracket_split_build_line(head_leaves, line, opening_bracket)
2583     body = bracket_split_build_line(body_leaves, line, opening_bracket, is_body=True)
2584     tail = bracket_split_build_line(tail_leaves, line, opening_bracket)
2585     bracket_split_succeeded_or_raise(head, body, tail)
2586     if (
2587         # the body shouldn't be exploded
2588         not body.should_explode
2589         # the opening bracket is an optional paren
2590         and opening_bracket.type == token.LPAR
2591         and not opening_bracket.value
2592         # the closing bracket is an optional paren
2593         and closing_bracket.type == token.RPAR
2594         and not closing_bracket.value
2595         # it's not an import (optional parens are the only thing we can split on
2596         # in this case; attempting a split without them is a waste of time)
2597         and not line.is_import
2598         # there are no standalone comments in the body
2599         and not body.contains_standalone_comments(0)
2600         # and we can actually remove the parens
2601         and can_omit_invisible_parens(body, line_length)
2602     ):
2603         omit = {id(closing_bracket), *omit}
2604         try:
2605             yield from right_hand_split(line, line_length, features=features, omit=omit)
2606             return
2607
2608         except CannotSplit:
2609             if not (
2610                 can_be_split(body)
2611                 or is_line_short_enough(body, line_length=line_length)
2612             ):
2613                 raise CannotSplit(
2614                     "Splitting failed, body is still too long and can't be split."
2615                 )
2616
2617             elif head.contains_multiline_strings() or tail.contains_multiline_strings():
2618                 raise CannotSplit(
2619                     "The current optional pair of parentheses is bound to fail to "
2620                     "satisfy the splitting algorithm because the head or the tail "
2621                     "contains multiline strings which by definition never fit one "
2622                     "line."
2623                 )
2624
2625     ensure_visible(opening_bracket)
2626     ensure_visible(closing_bracket)
2627     for result in (head, body, tail):
2628         if result:
2629             yield result
2630
2631
2632 def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
2633     """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
2634
2635     Do nothing otherwise.
2636
2637     A left- or right-hand split is based on a pair of brackets. Content before
2638     (and including) the opening bracket is left on one line, content inside the
2639     brackets is put on a separate line, and finally content starting with and
2640     following the closing bracket is put on a separate line.
2641
2642     Those are called `head`, `body`, and `tail`, respectively. If the split
2643     produced the same line (all content in `head`) or ended up with an empty `body`
2644     and the `tail` is just the closing bracket, then it's considered failed.
2645     """
2646     tail_len = len(str(tail).strip())
2647     if not body:
2648         if tail_len == 0:
2649             raise CannotSplit("Splitting brackets produced the same line")
2650
2651         elif tail_len < 3:
2652             raise CannotSplit(
2653                 f"Splitting brackets on an empty body to save "
2654                 f"{tail_len} characters is not worth it"
2655             )
2656
2657
2658 def bracket_split_build_line(
2659     leaves: List[Leaf], original: Line, opening_bracket: Leaf, *, is_body: bool = False
2660 ) -> Line:
2661     """Return a new line with given `leaves` and respective comments from `original`.
2662
2663     If `is_body` is True, the result line is one-indented inside brackets and as such
2664     has its first leaf's prefix normalized and a trailing comma added when expected.
2665     """
2666     result = Line(depth=original.depth)
2667     if is_body:
2668         result.inside_brackets = True
2669         result.depth += 1
2670         if leaves:
2671             # Since body is a new indent level, remove spurious leading whitespace.
2672             normalize_prefix(leaves[0], inside_brackets=True)
2673             # Ensure a trailing comma for imports and standalone function arguments, but
2674             # be careful not to add one after any comments or within type annotations.
2675             no_commas = (
2676                 original.is_def
2677                 and opening_bracket.value == "("
2678                 and not any(l.type == token.COMMA for l in leaves)
2679             )
2680
2681             if original.is_import or no_commas:
2682                 for i in range(len(leaves) - 1, -1, -1):
2683                     if leaves[i].type == STANDALONE_COMMENT:
2684                         continue
2685
2686                     if leaves[i].type != token.COMMA:
2687                         leaves.insert(i + 1, Leaf(token.COMMA, ","))
2688                     break
2689
2690     # Populate the line
2691     for leaf in leaves:
2692         result.append(leaf, preformatted=True)
2693         for comment_after in original.comments_after(leaf):
2694             result.append(comment_after, preformatted=True)
2695     if is_body:
2696         result.should_explode = should_explode(result, opening_bracket)
2697     return result
2698
2699
2700 def dont_increase_indentation(split_func: SplitFunc) -> SplitFunc:
2701     """Normalize prefix of the first leaf in every line returned by `split_func`.
2702
2703     This is a decorator over relevant split functions.
2704     """
2705
2706     @wraps(split_func)
2707     def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
2708         for l in split_func(line, features):
2709             normalize_prefix(l.leaves[0], inside_brackets=True)
2710             yield l
2711
2712     return split_wrapper
2713
2714
2715 @dont_increase_indentation
2716 def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
2717     """Split according to delimiters of the highest priority.
2718
2719     If the appropriate Features are given, the split will add trailing commas
2720     also in function signatures and calls that contain `*` and `**`.
2721     """
2722     try:
2723         last_leaf = line.leaves[-1]
2724     except IndexError:
2725         raise CannotSplit("Line empty")
2726
2727     bt = line.bracket_tracker
2728     try:
2729         delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
2730     except ValueError:
2731         raise CannotSplit("No delimiters found")
2732
2733     if delimiter_priority == DOT_PRIORITY:
2734         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
2735             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
2736
2737     current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
2738     lowest_depth = sys.maxsize
2739     trailing_comma_safe = True
2740
2741     def append_to_line(leaf: Leaf) -> Iterator[Line]:
2742         """Append `leaf` to current line or to new line if appending impossible."""
2743         nonlocal current_line
2744         try:
2745             current_line.append_safe(leaf, preformatted=True)
2746         except ValueError:
2747             yield current_line
2748
2749             current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
2750             current_line.append(leaf)
2751
2752     for leaf in line.leaves:
2753         yield from append_to_line(leaf)
2754
2755         for comment_after in line.comments_after(leaf):
2756             yield from append_to_line(comment_after)
2757
2758         lowest_depth = min(lowest_depth, leaf.bracket_depth)
2759         if leaf.bracket_depth == lowest_depth:
2760             if is_vararg(leaf, within={syms.typedargslist}):
2761                 trailing_comma_safe = (
2762                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
2763                 )
2764             elif is_vararg(leaf, within={syms.arglist, syms.argument}):
2765                 trailing_comma_safe = (
2766                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
2767                 )
2768
2769         leaf_priority = bt.delimiters.get(id(leaf))
2770         if leaf_priority == delimiter_priority:
2771             yield current_line
2772
2773             current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
2774     if current_line:
2775         if (
2776             trailing_comma_safe
2777             and delimiter_priority == COMMA_PRIORITY
2778             and current_line.leaves[-1].type != token.COMMA
2779             and current_line.leaves[-1].type != STANDALONE_COMMENT
2780         ):
2781             current_line.append(Leaf(token.COMMA, ","))
2782         yield current_line
2783
2784
2785 @dont_increase_indentation
2786 def standalone_comment_split(
2787     line: Line, features: Collection[Feature] = ()
2788 ) -> Iterator[Line]:
2789     """Split standalone comments from the rest of the line."""
2790     if not line.contains_standalone_comments(0):
2791         raise CannotSplit("Line does not have any standalone comments")
2792
2793     current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
2794
2795     def append_to_line(leaf: Leaf) -> Iterator[Line]:
2796         """Append `leaf` to current line or to new line if appending impossible."""
2797         nonlocal current_line
2798         try:
2799             current_line.append_safe(leaf, preformatted=True)
2800         except ValueError:
2801             yield current_line
2802
2803             current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
2804             current_line.append(leaf)
2805
2806     for leaf in line.leaves:
2807         yield from append_to_line(leaf)
2808
2809         for comment_after in line.comments_after(leaf):
2810             yield from append_to_line(comment_after)
2811
2812     if current_line:
2813         yield current_line
2814
2815
2816 def is_import(leaf: Leaf) -> bool:
2817     """Return True if the given leaf starts an import statement."""
2818     p = leaf.parent
2819     t = leaf.type
2820     v = leaf.value
2821     return bool(
2822         t == token.NAME
2823         and (
2824             (v == "import" and p and p.type == syms.import_name)
2825             or (v == "from" and p and p.type == syms.import_from)
2826         )
2827     )
2828
2829
2830 def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
2831     """Return True if the given leaf is a special comment.
2832     Only returns true for type comments for now."""
2833     t = leaf.type
2834     v = leaf.value
2835     return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:" + suffix)
2836
2837
2838 def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
2839     """Leave existing extra newlines if not `inside_brackets`. Remove everything
2840     else.
2841
2842     Note: don't use backslashes for formatting or you'll lose your voting rights.
2843     """
2844     if not inside_brackets:
2845         spl = leaf.prefix.split("#")
2846         if "\\" not in spl[0]:
2847             nl_count = spl[-1].count("\n")
2848             if len(spl) > 1:
2849                 nl_count -= 1
2850             leaf.prefix = "\n" * nl_count
2851             return
2852
2853     leaf.prefix = ""
2854
2855
2856 def normalize_string_prefix(leaf: Leaf, remove_u_prefix: bool = False) -> None:
2857     """Make all string prefixes lowercase.
2858
2859     If remove_u_prefix is given, also removes any u prefix from the string.
2860
2861     Note: Mutates its argument.
2862     """
2863     match = re.match(r"^([furbFURB]*)(.*)$", leaf.value, re.DOTALL)
2864     assert match is not None, f"failed to match string {leaf.value!r}"
2865     orig_prefix = match.group(1)
2866     new_prefix = orig_prefix.replace("F", "f").replace("B", "b").replace("U", "u")
2867     if remove_u_prefix:
2868         new_prefix = new_prefix.replace("u", "")
2869     leaf.value = f"{new_prefix}{match.group(2)}"
2870
2871
2872 def normalize_string_quotes(leaf: Leaf) -> None:
2873     """Prefer double quotes but only if it doesn't cause more escaping.
2874
2875     Adds or removes backslashes as appropriate. Doesn't parse and fix
2876     strings nested in f-strings (yet).
2877
2878     Note: Mutates its argument.
2879     """
2880     value = leaf.value.lstrip("furbFURB")
2881     if value[:3] == '"""':
2882         return
2883
2884     elif value[:3] == "'''":
2885         orig_quote = "'''"
2886         new_quote = '"""'
2887     elif value[0] == '"':
2888         orig_quote = '"'
2889         new_quote = "'"
2890     else:
2891         orig_quote = "'"
2892         new_quote = '"'
2893     first_quote_pos = leaf.value.find(orig_quote)
2894     if first_quote_pos == -1:
2895         return  # There's an internal error
2896
2897     prefix = leaf.value[:first_quote_pos]
2898     unescaped_new_quote = re.compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
2899     escaped_new_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
2900     escaped_orig_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
2901     body = leaf.value[first_quote_pos + len(orig_quote) : -len(orig_quote)]
2902     if "r" in prefix.casefold():
2903         if unescaped_new_quote.search(body):
2904             # There's at least one unescaped new_quote in this raw string
2905             # so converting is impossible
2906             return
2907
2908         # Do not introduce or remove backslashes in raw strings
2909         new_body = body
2910     else:
2911         # remove unnecessary escapes
2912         new_body = sub_twice(escaped_new_quote, rf"\1\2{new_quote}", body)
2913         if body != new_body:
2914             # Consider the string without unnecessary escapes as the original
2915             body = new_body
2916             leaf.value = f"{prefix}{orig_quote}{body}{orig_quote}"
2917         new_body = sub_twice(escaped_orig_quote, rf"\1\2{orig_quote}", new_body)
2918         new_body = sub_twice(unescaped_new_quote, rf"\1\\{new_quote}", new_body)
2919     if "f" in prefix.casefold():
2920         matches = re.findall(
2921             r"""
2922             (?:[^{]|^)\{  # start of the string or a non-{ followed by a single {
2923                 ([^{].*?)  # contents of the brackets except if begins with {{
2924             \}(?:[^}]|$)  # A } followed by end of the string or a non-}
2925             """,
2926             new_body,
2927             re.VERBOSE,
2928         )
2929         for m in matches:
2930             if "\\" in str(m):
2931                 # Do not introduce backslashes in interpolated expressions
2932                 return
2933
2934     if new_quote == '"""' and new_body[-1:] == '"':
2935         # edge case:
2936         new_body = new_body[:-1] + '\\"'
2937     orig_escape_count = body.count("\\")
2938     new_escape_count = new_body.count("\\")
2939     if new_escape_count > orig_escape_count:
2940         return  # Do not introduce more escaping
2941
2942     if new_escape_count == orig_escape_count and orig_quote == '"':
2943         return  # Prefer double quotes
2944
2945     leaf.value = f"{prefix}{new_quote}{new_body}{new_quote}"
2946
2947
2948 def normalize_numeric_literal(leaf: Leaf) -> None:
2949     """Normalizes numeric (float, int, and complex) literals.
2950
2951     All letters used in the representation are normalized to lowercase (except
2952     in Python 2 long literals).
2953     """
2954     text = leaf.value.lower()
2955     if text.startswith(("0o", "0b")):
2956         # Leave octal and binary literals alone.
2957         pass
2958     elif text.startswith("0x"):
2959         # Change hex literals to upper case.
2960         before, after = text[:2], text[2:]
2961         text = f"{before}{after.upper()}"
2962     elif "e" in text:
2963         before, after = text.split("e")
2964         sign = ""
2965         if after.startswith("-"):
2966             after = after[1:]
2967             sign = "-"
2968         elif after.startswith("+"):
2969             after = after[1:]
2970         before = format_float_or_int_string(before)
2971         text = f"{before}e{sign}{after}"
2972     elif text.endswith(("j", "l")):
2973         number = text[:-1]
2974         suffix = text[-1]
2975         # Capitalize in "2L" because "l" looks too similar to "1".
2976         if suffix == "l":
2977             suffix = "L"
2978         text = f"{format_float_or_int_string(number)}{suffix}"
2979     else:
2980         text = format_float_or_int_string(text)
2981     leaf.value = text
2982
2983
2984 def format_float_or_int_string(text: str) -> str:
2985     """Formats a float string like "1.0"."""
2986     if "." not in text:
2987         return text
2988
2989     before, after = text.split(".")
2990     return f"{before or 0}.{after or 0}"
2991
2992
2993 def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
2994     """Make existing optional parentheses invisible or create new ones.
2995
2996     `parens_after` is a set of string leaf values immediately after which parens
2997     should be put.
2998
2999     Standardizes on visible parentheses for single-element tuples, and keeps
3000     existing visible parentheses for other tuples and generator expressions.
3001     """
3002     for pc in list_comments(node.prefix, is_endmarker=False):
3003         if pc.value in FMT_OFF:
3004             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
3005             return
3006     check_lpar = False
3007     for index, child in enumerate(list(node.children)):
3008         # Add parentheses around long tuple unpacking in assignments.
3009         if (
3010             index == 0
3011             and isinstance(child, Node)
3012             and child.type == syms.testlist_star_expr
3013         ):
3014             check_lpar = True
3015
3016         if check_lpar:
3017             if is_walrus_assignment(child):
3018                 continue
3019
3020             if child.type == syms.atom:
3021                 if maybe_make_parens_invisible_in_atom(child, parent=node):
3022                     wrap_in_parentheses(node, child, visible=False)
3023             elif is_one_tuple(child):
3024                 wrap_in_parentheses(node, child, visible=True)
3025             elif node.type == syms.import_from:
3026                 # "import from" nodes store parentheses directly as part of
3027                 # the statement
3028                 if child.type == token.LPAR:
3029                     # make parentheses invisible
3030                     child.value = ""  # type: ignore
3031                     node.children[-1].value = ""  # type: ignore
3032                 elif child.type != token.STAR:
3033                     # insert invisible parentheses
3034                     node.insert_child(index, Leaf(token.LPAR, ""))
3035                     node.append_child(Leaf(token.RPAR, ""))
3036                 break
3037
3038             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
3039                 wrap_in_parentheses(node, child, visible=False)
3040
3041         check_lpar = isinstance(child, Leaf) and child.value in parens_after
3042
3043
3044 def normalize_fmt_off(node: Node) -> None:
3045     """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
3046     try_again = True
3047     while try_again:
3048         try_again = convert_one_fmt_off_pair(node)
3049
3050
3051 def convert_one_fmt_off_pair(node: Node) -> bool:
3052     """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
3053
3054     Returns True if a pair was converted.
3055     """
3056     for leaf in node.leaves():
3057         previous_consumed = 0
3058         for comment in list_comments(leaf.prefix, is_endmarker=False):
3059             if comment.value in FMT_OFF:
3060                 # We only want standalone comments. If there's no previous leaf or
3061                 # the previous leaf is indentation, it's a standalone comment in
3062                 # disguise.
3063                 if comment.type != STANDALONE_COMMENT:
3064                     prev = preceding_leaf(leaf)
3065                     if prev and prev.type not in WHITESPACE:
3066                         continue
3067
3068                 ignored_nodes = list(generate_ignored_nodes(leaf))
3069                 if not ignored_nodes:
3070                     continue
3071
3072                 first = ignored_nodes[0]  # Can be a container node with the `leaf`.
3073                 parent = first.parent
3074                 prefix = first.prefix
3075                 first.prefix = prefix[comment.consumed :]
3076                 hidden_value = (
3077                     comment.value + "\n" + "".join(str(n) for n in ignored_nodes)
3078                 )
3079                 if hidden_value.endswith("\n"):
3080                     # That happens when one of the `ignored_nodes` ended with a NEWLINE
3081                     # leaf (possibly followed by a DEDENT).
3082                     hidden_value = hidden_value[:-1]
3083                 first_idx: Optional[int] = None
3084                 for ignored in ignored_nodes:
3085                     index = ignored.remove()
3086                     if first_idx is None:
3087                         first_idx = index
3088                 assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
3089                 assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
3090                 parent.insert_child(
3091                     first_idx,
3092                     Leaf(
3093                         STANDALONE_COMMENT,
3094                         hidden_value,
3095                         prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
3096                     ),
3097                 )
3098                 return True
3099
3100             previous_consumed = comment.consumed
3101
3102     return False
3103
3104
3105 def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
3106     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
3107
3108     Stops at the end of the block.
3109     """
3110     container: Optional[LN] = container_of(leaf)
3111     while container is not None and container.type != token.ENDMARKER:
3112         is_fmt_on = False
3113         for comment in list_comments(container.prefix, is_endmarker=False):
3114             if comment.value in FMT_ON:
3115                 is_fmt_on = True
3116             elif comment.value in FMT_OFF:
3117                 is_fmt_on = False
3118         if is_fmt_on:
3119             return
3120
3121         yield container
3122
3123         container = container.next_sibling
3124
3125
3126 def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
3127     """If it's safe, make the parens in the atom `node` invisible, recursively.
3128     Additionally, remove repeated, adjacent invisible parens from the atom `node`
3129     as they are redundant.
3130
3131     Returns whether the node should itself be wrapped in invisible parentheses.
3132
3133     """
3134     if (
3135         node.type != syms.atom
3136         or is_empty_tuple(node)
3137         or is_one_tuple(node)
3138         or (is_yield(node) and parent.type != syms.expr_stmt)
3139         or max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
3140     ):
3141         return False
3142
3143     first = node.children[0]
3144     last = node.children[-1]
3145     if first.type == token.LPAR and last.type == token.RPAR:
3146         middle = node.children[1]
3147         # make parentheses invisible
3148         first.value = ""  # type: ignore
3149         last.value = ""  # type: ignore
3150         maybe_make_parens_invisible_in_atom(middle, parent=parent)
3151
3152         if is_atom_with_invisible_parens(middle):
3153             # Strip the invisible parens from `middle` by replacing
3154             # it with the child in-between the invisible parens
3155             middle.replace(middle.children[1])
3156
3157         return False
3158
3159     return True
3160
3161
3162 def is_atom_with_invisible_parens(node: LN) -> bool:
3163     """Given a `LN`, determines whether it's an atom `node` with invisible
3164     parens. Useful in dedupe-ing and normalizing parens.
3165     """
3166     if isinstance(node, Leaf) or node.type != syms.atom:
3167         return False
3168
3169     first, last = node.children[0], node.children[-1]
3170     return (
3171         isinstance(first, Leaf)
3172         and first.type == token.LPAR
3173         and first.value == ""
3174         and isinstance(last, Leaf)
3175         and last.type == token.RPAR
3176         and last.value == ""
3177     )
3178
3179
3180 def is_empty_tuple(node: LN) -> bool:
3181     """Return True if `node` holds an empty tuple."""
3182     return (
3183         node.type == syms.atom
3184         and len(node.children) == 2
3185         and node.children[0].type == token.LPAR
3186         and node.children[1].type == token.RPAR
3187     )
3188
3189
3190 def unwrap_singleton_parenthesis(node: LN) -> Optional[LN]:
3191     """Returns `wrapped` if `node` is of the shape ( wrapped ).
3192
3193     Parenthesis can be optional. Returns None otherwise"""
3194     if len(node.children) != 3:
3195         return None
3196
3197     lpar, wrapped, rpar = node.children
3198     if not (lpar.type == token.LPAR and rpar.type == token.RPAR):
3199         return None
3200
3201     return wrapped
3202
3203
3204 def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
3205     """Wrap `child` in parentheses.
3206
3207     This replaces `child` with an atom holding the parentheses and the old
3208     child.  That requires moving the prefix.
3209
3210     If `visible` is False, the leaves will be valueless (and thus invisible).
3211     """
3212     lpar = Leaf(token.LPAR, "(" if visible else "")
3213     rpar = Leaf(token.RPAR, ")" if visible else "")
3214     prefix = child.prefix
3215     child.prefix = ""
3216     index = child.remove() or 0
3217     new_child = Node(syms.atom, [lpar, child, rpar])
3218     new_child.prefix = prefix
3219     parent.insert_child(index, new_child)
3220
3221
3222 def is_one_tuple(node: LN) -> bool:
3223     """Return True if `node` holds a tuple with one element, with or without parens."""
3224     if node.type == syms.atom:
3225         gexp = unwrap_singleton_parenthesis(node)
3226         if gexp is None or gexp.type != syms.testlist_gexp:
3227             return False
3228
3229         return len(gexp.children) == 2 and gexp.children[1].type == token.COMMA
3230
3231     return (
3232         node.type in IMPLICIT_TUPLE
3233         and len(node.children) == 2
3234         and node.children[1].type == token.COMMA
3235     )
3236
3237
3238 def is_walrus_assignment(node: LN) -> bool:
3239     """Return True iff `node` is of the shape ( test := test )"""
3240     inner = unwrap_singleton_parenthesis(node)
3241     return inner is not None and inner.type == syms.namedexpr_test
3242
3243
3244 def is_yield(node: LN) -> bool:
3245     """Return True if `node` holds a `yield` or `yield from` expression."""
3246     if node.type == syms.yield_expr:
3247         return True
3248
3249     if node.type == token.NAME and node.value == "yield":  # type: ignore
3250         return True
3251
3252     if node.type != syms.atom:
3253         return False
3254
3255     if len(node.children) != 3:
3256         return False
3257
3258     lpar, expr, rpar = node.children
3259     if lpar.type == token.LPAR and rpar.type == token.RPAR:
3260         return is_yield(expr)
3261
3262     return False
3263
3264
3265 def is_vararg(leaf: Leaf, within: Set[NodeType]) -> bool:
3266     """Return True if `leaf` is a star or double star in a vararg or kwarg.
3267
3268     If `within` includes VARARGS_PARENTS, this applies to function signatures.
3269     If `within` includes UNPACKING_PARENTS, it applies to right hand-side
3270     extended iterable unpacking (PEP 3132) and additional unpacking
3271     generalizations (PEP 448).
3272     """
3273     if leaf.type not in VARARGS_SPECIALS or not leaf.parent:
3274         return False
3275
3276     p = leaf.parent
3277     if p.type == syms.star_expr:
3278         # Star expressions are also used as assignment targets in extended
3279         # iterable unpacking (PEP 3132).  See what its parent is instead.
3280         if not p.parent:
3281             return False
3282
3283         p = p.parent
3284
3285     return p.type in within
3286
3287
3288 def is_multiline_string(leaf: Leaf) -> bool:
3289     """Return True if `leaf` is a multiline string that actually spans many lines."""
3290     value = leaf.value.lstrip("furbFURB")
3291     return value[:3] in {'"""', "'''"} and "\n" in value
3292
3293
3294 def is_stub_suite(node: Node) -> bool:
3295     """Return True if `node` is a suite with a stub body."""
3296     if (
3297         len(node.children) != 4
3298         or node.children[0].type != token.NEWLINE
3299         or node.children[1].type != token.INDENT
3300         or node.children[3].type != token.DEDENT
3301     ):
3302         return False
3303
3304     return is_stub_body(node.children[2])
3305
3306
3307 def is_stub_body(node: LN) -> bool:
3308     """Return True if `node` is a simple statement containing an ellipsis."""
3309     if not isinstance(node, Node) or node.type != syms.simple_stmt:
3310         return False
3311
3312     if len(node.children) != 2:
3313         return False
3314
3315     child = node.children[0]
3316     return (
3317         child.type == syms.atom
3318         and len(child.children) == 3
3319         and all(leaf == Leaf(token.DOT, ".") for leaf in child.children)
3320     )
3321
3322
3323 def max_delimiter_priority_in_atom(node: LN) -> Priority:
3324     """Return maximum delimiter priority inside `node`.
3325
3326     This is specific to atoms with contents contained in a pair of parentheses.
3327     If `node` isn't an atom or there are no enclosing parentheses, returns 0.
3328     """
3329     if node.type != syms.atom:
3330         return 0
3331
3332     first = node.children[0]
3333     last = node.children[-1]
3334     if not (first.type == token.LPAR and last.type == token.RPAR):
3335         return 0
3336
3337     bt = BracketTracker()
3338     for c in node.children[1:-1]:
3339         if isinstance(c, Leaf):
3340             bt.mark(c)
3341         else:
3342             for leaf in c.leaves():
3343                 bt.mark(leaf)
3344     try:
3345         return bt.max_delimiter_priority()
3346
3347     except ValueError:
3348         return 0
3349
3350
3351 def ensure_visible(leaf: Leaf) -> None:
3352     """Make sure parentheses are visible.
3353
3354     They could be invisible as part of some statements (see
3355     :func:`normalize_invisible_parens` and :func:`visit_import_from`).
3356     """
3357     if leaf.type == token.LPAR:
3358         leaf.value = "("
3359     elif leaf.type == token.RPAR:
3360         leaf.value = ")"
3361
3362
3363 def should_explode(line: Line, opening_bracket: Leaf) -> bool:
3364     """Should `line` immediately be split with `delimiter_split()` after RHS?"""
3365
3366     if not (
3367         opening_bracket.parent
3368         and opening_bracket.parent.type in {syms.atom, syms.import_from}
3369         and opening_bracket.value in "[{("
3370     ):
3371         return False
3372
3373     try:
3374         last_leaf = line.leaves[-1]
3375         exclude = {id(last_leaf)} if last_leaf.type == token.COMMA else set()
3376         max_priority = line.bracket_tracker.max_delimiter_priority(exclude=exclude)
3377     except (IndexError, ValueError):
3378         return False
3379
3380     return max_priority == COMMA_PRIORITY
3381
3382
3383 def get_features_used(node: Node) -> Set[Feature]:
3384     """Return a set of (relatively) new Python features used in this file.
3385
3386     Currently looking for:
3387     - f-strings;
3388     - underscores in numeric literals;
3389     - trailing commas after * or ** in function signatures and calls;
3390     - positional only arguments in function signatures and lambdas;
3391     """
3392     features: Set[Feature] = set()
3393     for n in node.pre_order():
3394         if n.type == token.STRING:
3395             value_head = n.value[:2]  # type: ignore
3396             if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
3397                 features.add(Feature.F_STRINGS)
3398
3399         elif n.type == token.NUMBER:
3400             if "_" in n.value:  # type: ignore
3401                 features.add(Feature.NUMERIC_UNDERSCORES)
3402
3403         elif n.type == token.SLASH:
3404             if n.parent and n.parent.type in {syms.typedargslist, syms.arglist}:
3405                 features.add(Feature.POS_ONLY_ARGUMENTS)
3406
3407         elif n.type == token.COLONEQUAL:
3408             features.add(Feature.ASSIGNMENT_EXPRESSIONS)
3409
3410         elif (
3411             n.type in {syms.typedargslist, syms.arglist}
3412             and n.children
3413             and n.children[-1].type == token.COMMA
3414         ):
3415             if n.type == syms.typedargslist:
3416                 feature = Feature.TRAILING_COMMA_IN_DEF
3417             else:
3418                 feature = Feature.TRAILING_COMMA_IN_CALL
3419
3420             for ch in n.children:
3421                 if ch.type in STARS:
3422                     features.add(feature)
3423
3424                 if ch.type == syms.argument:
3425                     for argch in ch.children:
3426                         if argch.type in STARS:
3427                             features.add(feature)
3428
3429     return features
3430
3431
3432 def detect_target_versions(node: Node) -> Set[TargetVersion]:
3433     """Detect the version to target based on the nodes used."""
3434     features = get_features_used(node)
3435     return {
3436         version for version in TargetVersion if features <= VERSION_TO_FEATURES[version]
3437     }
3438
3439
3440 def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[LeafID]]:
3441     """Generate sets of closing bracket IDs that should be omitted in a RHS.
3442
3443     Brackets can be omitted if the entire trailer up to and including
3444     a preceding closing bracket fits in one line.
3445
3446     Yielded sets are cumulative (contain results of previous yields, too).  First
3447     set is empty.
3448     """
3449
3450     omit: Set[LeafID] = set()
3451     yield omit
3452
3453     length = 4 * line.depth
3454     opening_bracket: Optional[Leaf] = None
3455     closing_bracket: Optional[Leaf] = None
3456     inner_brackets: Set[LeafID] = set()
3457     for index, leaf, leaf_length in enumerate_with_length(line, reversed=True):
3458         length += leaf_length
3459         if length > line_length:
3460             break
3461
3462         has_inline_comment = leaf_length > len(leaf.value) + len(leaf.prefix)
3463         if leaf.type == STANDALONE_COMMENT or has_inline_comment:
3464             break
3465
3466         if opening_bracket:
3467             if leaf is opening_bracket:
3468                 opening_bracket = None
3469             elif leaf.type in CLOSING_BRACKETS:
3470                 inner_brackets.add(id(leaf))
3471         elif leaf.type in CLOSING_BRACKETS:
3472             if index > 0 and line.leaves[index - 1].type in OPENING_BRACKETS:
3473                 # Empty brackets would fail a split so treat them as "inner"
3474                 # brackets (e.g. only add them to the `omit` set if another
3475                 # pair of brackets was good enough.
3476                 inner_brackets.add(id(leaf))
3477                 continue
3478
3479             if closing_bracket:
3480                 omit.add(id(closing_bracket))
3481                 omit.update(inner_brackets)
3482                 inner_brackets.clear()
3483                 yield omit
3484
3485             if leaf.value:
3486                 opening_bracket = leaf.opening_bracket
3487                 closing_bracket = leaf
3488
3489
3490 def get_future_imports(node: Node) -> Set[str]:
3491     """Return a set of __future__ imports in the file."""
3492     imports: Set[str] = set()
3493
3494     def get_imports_from_children(children: List[LN]) -> Generator[str, None, None]:
3495         for child in children:
3496             if isinstance(child, Leaf):
3497                 if child.type == token.NAME:
3498                     yield child.value
3499
3500             elif child.type == syms.import_as_name:
3501                 orig_name = child.children[0]
3502                 assert isinstance(orig_name, Leaf), "Invalid syntax parsing imports"
3503                 assert orig_name.type == token.NAME, "Invalid syntax parsing imports"
3504                 yield orig_name.value
3505
3506             elif child.type == syms.import_as_names:
3507                 yield from get_imports_from_children(child.children)
3508
3509             else:
3510                 raise AssertionError("Invalid syntax parsing imports")
3511
3512     for child in node.children:
3513         if child.type != syms.simple_stmt:
3514             break
3515
3516         first_child = child.children[0]
3517         if isinstance(first_child, Leaf):
3518             # Continue looking if we see a docstring; otherwise stop.
3519             if (
3520                 len(child.children) == 2
3521                 and first_child.type == token.STRING
3522                 and child.children[1].type == token.NEWLINE
3523             ):
3524                 continue
3525
3526             break
3527
3528         elif first_child.type == syms.import_from:
3529             module_name = first_child.children[1]
3530             if not isinstance(module_name, Leaf) or module_name.value != "__future__":
3531                 break
3532
3533             imports |= set(get_imports_from_children(first_child.children[3:]))
3534         else:
3535             break
3536
3537     return imports
3538
3539
3540 @lru_cache()
3541 def get_gitignore(root: Path) -> PathSpec:
3542     """ Return a PathSpec matching gitignore content if present."""
3543     gitignore = root / ".gitignore"
3544     lines: List[str] = []
3545     if gitignore.is_file():
3546         with gitignore.open() as gf:
3547             lines = gf.readlines()
3548     return PathSpec.from_lines("gitwildmatch", lines)
3549
3550
3551 def gen_python_files_in_dir(
3552     path: Path,
3553     root: Path,
3554     include: Pattern[str],
3555     exclude: Pattern[str],
3556     report: "Report",
3557     gitignore: PathSpec,
3558 ) -> Iterator[Path]:
3559     """Generate all files under `path` whose paths are not excluded by the
3560     `exclude` regex, but are included by the `include` regex.
3561
3562     Symbolic links pointing outside of the `root` directory are ignored.
3563
3564     `report` is where output about exclusions goes.
3565     """
3566     assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
3567     for child in path.iterdir():
3568         # First ignore files matching .gitignore
3569         if gitignore.match_file(child.as_posix()):
3570             report.path_ignored(child, "matches the .gitignore file content")
3571             continue
3572
3573         # Then ignore with `exclude` option.
3574         try:
3575             normalized_path = "/" + child.resolve().relative_to(root).as_posix()
3576         except OSError as e:
3577             report.path_ignored(child, f"cannot be read because {e}")
3578             continue
3579
3580         except ValueError:
3581             if child.is_symlink():
3582                 report.path_ignored(
3583                     child, f"is a symbolic link that points outside {root}"
3584                 )
3585                 continue
3586
3587             raise
3588
3589         if child.is_dir():
3590             normalized_path += "/"
3591
3592         exclude_match = exclude.search(normalized_path)
3593         if exclude_match and exclude_match.group(0):
3594             report.path_ignored(child, "matches the --exclude regular expression")
3595             continue
3596
3597         if child.is_dir():
3598             yield from gen_python_files_in_dir(
3599                 child, root, include, exclude, report, gitignore
3600             )
3601
3602         elif child.is_file():
3603             include_match = include.search(normalized_path)
3604             if include_match:
3605                 yield child
3606
3607
3608 @lru_cache()
3609 def find_project_root(srcs: Iterable[str]) -> Path:
3610     """Return a directory containing .git, .hg, or pyproject.toml.
3611
3612     That directory can be one of the directories passed in `srcs` or their
3613     common parent.
3614
3615     If no directory in the tree contains a marker that would specify it's the
3616     project root, the root of the file system is returned.
3617     """
3618     if not srcs:
3619         return Path("/").resolve()
3620
3621     common_base = min(Path(src).resolve() for src in srcs)
3622     if common_base.is_dir():
3623         # Append a fake file so `parents` below returns `common_base_dir`, too.
3624         common_base /= "fake-file"
3625     for directory in common_base.parents:
3626         if (directory / ".git").exists():
3627             return directory
3628
3629         if (directory / ".hg").is_dir():
3630             return directory
3631
3632         if (directory / "pyproject.toml").is_file():
3633             return directory
3634
3635     return directory
3636
3637
3638 @dataclass
3639 class Report:
3640     """Provides a reformatting counter. Can be rendered with `str(report)`."""
3641
3642     check: bool = False
3643     diff: bool = False
3644     quiet: bool = False
3645     verbose: bool = False
3646     change_count: int = 0
3647     same_count: int = 0
3648     failure_count: int = 0
3649
3650     def done(self, src: Path, changed: Changed) -> None:
3651         """Increment the counter for successful reformatting. Write out a message."""
3652         if changed is Changed.YES:
3653             reformatted = "would reformat" if self.check or self.diff else "reformatted"
3654             if self.verbose or not self.quiet:
3655                 out(f"{reformatted} {src}")
3656             self.change_count += 1
3657         else:
3658             if self.verbose:
3659                 if changed is Changed.NO:
3660                     msg = f"{src} already well formatted, good job."
3661                 else:
3662                     msg = f"{src} wasn't modified on disk since last run."
3663                 out(msg, bold=False)
3664             self.same_count += 1
3665
3666     def failed(self, src: Path, message: str) -> None:
3667         """Increment the counter for failed reformatting. Write out a message."""
3668         err(f"error: cannot format {src}: {message}")
3669         self.failure_count += 1
3670
3671     def path_ignored(self, path: Path, message: str) -> None:
3672         if self.verbose:
3673             out(f"{path} ignored: {message}", bold=False)
3674
3675     @property
3676     def return_code(self) -> int:
3677         """Return the exit code that the app should use.
3678
3679         This considers the current state of changed files and failures:
3680         - if there were any failures, return 123;
3681         - if any files were changed and --check is being used, return 1;
3682         - otherwise return 0.
3683         """
3684         # According to http://tldp.org/LDP/abs/html/exitcodes.html starting with
3685         # 126 we have special return codes reserved by the shell.
3686         if self.failure_count:
3687             return 123
3688
3689         elif self.change_count and self.check:
3690             return 1
3691
3692         return 0
3693
3694     def __str__(self) -> str:
3695         """Render a color report of the current state.
3696
3697         Use `click.unstyle` to remove colors.
3698         """
3699         if self.check or self.diff:
3700             reformatted = "would be reformatted"
3701             unchanged = "would be left unchanged"
3702             failed = "would fail to reformat"
3703         else:
3704             reformatted = "reformatted"
3705             unchanged = "left unchanged"
3706             failed = "failed to reformat"
3707         report = []
3708         if self.change_count:
3709             s = "s" if self.change_count > 1 else ""
3710             report.append(
3711                 click.style(f"{self.change_count} file{s} {reformatted}", bold=True)
3712             )
3713         if self.same_count:
3714             s = "s" if self.same_count > 1 else ""
3715             report.append(f"{self.same_count} file{s} {unchanged}")
3716         if self.failure_count:
3717             s = "s" if self.failure_count > 1 else ""
3718             report.append(
3719                 click.style(f"{self.failure_count} file{s} {failed}", fg="red")
3720             )
3721         return ", ".join(report) + "."
3722
3723
3724 def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
3725     filename = "<unknown>"
3726     if sys.version_info >= (3, 8):
3727         # TODO: support Python 4+ ;)
3728         for minor_version in range(sys.version_info[1], 4, -1):
3729             try:
3730                 return ast.parse(src, filename, feature_version=(3, minor_version))
3731             except SyntaxError:
3732                 continue
3733     else:
3734         for feature_version in (7, 6):
3735             try:
3736                 return ast3.parse(src, filename, feature_version=feature_version)
3737             except SyntaxError:
3738                 continue
3739
3740     return ast27.parse(src)
3741
3742
3743 def _fixup_ast_constants(
3744     node: Union[ast.AST, ast3.AST, ast27.AST]
3745 ) -> Union[ast.AST, ast3.AST, ast27.AST]:
3746     """Map ast nodes deprecated in 3.8 to Constant."""
3747     if isinstance(node, (ast.Str, ast3.Str, ast27.Str, ast.Bytes, ast3.Bytes)):
3748         return ast.Constant(value=node.s)
3749
3750     if isinstance(node, (ast.Num, ast3.Num, ast27.Num)):
3751         return ast.Constant(value=node.n)
3752
3753     if isinstance(node, (ast.NameConstant, ast3.NameConstant)):
3754         return ast.Constant(value=node.value)
3755
3756     return node
3757
3758
3759 def assert_equivalent(src: str, dst: str) -> None:
3760     """Raise AssertionError if `src` and `dst` aren't equivalent."""
3761
3762     def _v(node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0) -> Iterator[str]:
3763         """Simple visitor generating strings to compare ASTs by content."""
3764
3765         node = _fixup_ast_constants(node)
3766
3767         yield f"{'  ' * depth}{node.__class__.__name__}("
3768
3769         for field in sorted(node._fields):  # noqa: F402
3770             # TypeIgnore has only one field 'lineno' which breaks this comparison
3771             type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
3772             if sys.version_info >= (3, 8):
3773                 type_ignore_classes += (ast.TypeIgnore,)
3774             if isinstance(node, type_ignore_classes):
3775                 break
3776
3777             try:
3778                 value = getattr(node, field)
3779             except AttributeError:
3780                 continue
3781
3782             yield f"{'  ' * (depth+1)}{field}="
3783
3784             if isinstance(value, list):
3785                 for item in value:
3786                     # Ignore nested tuples within del statements, because we may insert
3787                     # parentheses and they change the AST.
3788                     if (
3789                         field == "targets"
3790                         and isinstance(node, (ast.Delete, ast3.Delete, ast27.Delete))
3791                         and isinstance(item, (ast.Tuple, ast3.Tuple, ast27.Tuple))
3792                     ):
3793                         for item in item.elts:
3794                             yield from _v(item, depth + 2)
3795
3796                     elif isinstance(item, (ast.AST, ast3.AST, ast27.AST)):
3797                         yield from _v(item, depth + 2)
3798
3799             elif isinstance(value, (ast.AST, ast3.AST, ast27.AST)):
3800                 yield from _v(value, depth + 2)
3801
3802             else:
3803                 yield f"{'  ' * (depth+2)}{value!r},  # {value.__class__.__name__}"
3804
3805         yield f"{'  ' * depth})  # /{node.__class__.__name__}"
3806
3807     try:
3808         src_ast = parse_ast(src)
3809     except Exception as exc:
3810         raise AssertionError(
3811             f"cannot use --safe with this file; failed to parse source file.  "
3812             f"AST error message: {exc}"
3813         )
3814
3815     try:
3816         dst_ast = parse_ast(dst)
3817     except Exception as exc:
3818         log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
3819         raise AssertionError(
3820             f"INTERNAL ERROR: Black produced invalid code: {exc}. "
3821             f"Please report a bug on https://github.com/psf/black/issues.  "
3822             f"This invalid output might be helpful: {log}"
3823         ) from None
3824
3825     src_ast_str = "\n".join(_v(src_ast))
3826     dst_ast_str = "\n".join(_v(dst_ast))
3827     if src_ast_str != dst_ast_str:
3828         log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
3829         raise AssertionError(
3830             f"INTERNAL ERROR: Black produced code that is not equivalent to "
3831             f"the source.  "
3832             f"Please report a bug on https://github.com/psf/black/issues.  "
3833             f"This diff might be helpful: {log}"
3834         ) from None
3835
3836
3837 def assert_stable(src: str, dst: str, mode: Mode) -> None:
3838     """Raise AssertionError if `dst` reformats differently the second time."""
3839     newdst = format_str(dst, mode=mode)
3840     if dst != newdst:
3841         log = dump_to_file(
3842             diff(src, dst, "source", "first pass"),
3843             diff(dst, newdst, "first pass", "second pass"),
3844         )
3845         raise AssertionError(
3846             f"INTERNAL ERROR: Black produced different code on the second pass "
3847             f"of the formatter.  "
3848             f"Please report a bug on https://github.com/psf/black/issues.  "
3849             f"This diff might be helpful: {log}"
3850         ) from None
3851
3852
3853 @mypyc_attr(patchable=True)
3854 def dump_to_file(*output: str) -> str:
3855     """Dump `output` to a temporary file. Return path to the file."""
3856     with tempfile.NamedTemporaryFile(
3857         mode="w", prefix="blk_", suffix=".log", delete=False, encoding="utf8"
3858     ) as f:
3859         for lines in output:
3860             f.write(lines)
3861             if lines and lines[-1] != "\n":
3862                 f.write("\n")
3863     return f.name
3864
3865
3866 @contextmanager
3867 def nullcontext() -> Iterator[None]:
3868     """Return an empty context manager.
3869
3870     To be used like `nullcontext` in Python 3.7.
3871     """
3872     yield
3873
3874
3875 def diff(a: str, b: str, a_name: str, b_name: str) -> str:
3876     """Return a unified diff string between strings `a` and `b`."""
3877     import difflib
3878
3879     a_lines = [line + "\n" for line in a.splitlines()]
3880     b_lines = [line + "\n" for line in b.splitlines()]
3881     return "".join(
3882         difflib.unified_diff(a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5)
3883     )
3884
3885
3886 def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
3887     """asyncio signal handler that cancels all `tasks` and reports to stderr."""
3888     err("Aborted!")
3889     for task in tasks:
3890         task.cancel()
3891
3892
3893 def shutdown(loop: asyncio.AbstractEventLoop) -> None:
3894     """Cancel all pending tasks on `loop`, wait for them, and close the loop."""
3895     try:
3896         if sys.version_info[:2] >= (3, 7):
3897             all_tasks = asyncio.all_tasks
3898         else:
3899             all_tasks = asyncio.Task.all_tasks
3900         # This part is borrowed from asyncio/runners.py in Python 3.7b2.
3901         to_cancel = [task for task in all_tasks(loop) if not task.done()]
3902         if not to_cancel:
3903             return
3904
3905         for task in to_cancel:
3906             task.cancel()
3907         loop.run_until_complete(
3908             asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
3909         )
3910     finally:
3911         # `concurrent.futures.Future` objects cannot be cancelled once they
3912         # are already running. There might be some when the `shutdown()` happened.
3913         # Silence their logger's spew about the event loop being closed.
3914         cf_logger = logging.getLogger("concurrent.futures")
3915         cf_logger.setLevel(logging.CRITICAL)
3916         loop.close()
3917
3918
3919 def sub_twice(regex: Pattern[str], replacement: str, original: str) -> str:
3920     """Replace `regex` with `replacement` twice on `original`.
3921
3922     This is used by string normalization to perform replaces on
3923     overlapping matches.
3924     """
3925     return regex.sub(replacement, regex.sub(replacement, original))
3926
3927
3928 def re_compile_maybe_verbose(regex: str) -> Pattern[str]:
3929     """Compile a regular expression string in `regex`.
3930
3931     If it contains newlines, use verbose mode.
3932     """
3933     if "\n" in regex:
3934         regex = "(?x)" + regex
3935     compiled: Pattern[str] = re.compile(regex)
3936     return compiled
3937
3938
3939 def enumerate_reversed(sequence: Sequence[T]) -> Iterator[Tuple[Index, T]]:
3940     """Like `reversed(enumerate(sequence))` if that were possible."""
3941     index = len(sequence) - 1
3942     for element in reversed(sequence):
3943         yield (index, element)
3944         index -= 1
3945
3946
3947 def enumerate_with_length(
3948     line: Line, reversed: bool = False
3949 ) -> Iterator[Tuple[Index, Leaf, int]]:
3950     """Return an enumeration of leaves with their length.
3951
3952     Stops prematurely on multiline strings and standalone comments.
3953     """
3954     op = cast(
3955         Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
3956         enumerate_reversed if reversed else enumerate,
3957     )
3958     for index, leaf in op(line.leaves):
3959         length = len(leaf.prefix) + len(leaf.value)
3960         if "\n" in leaf.value:
3961             return  # Multiline strings, we can't continue.
3962
3963         for comment in line.comments_after(leaf):
3964             length += len(comment.value)
3965
3966         yield index, leaf, length
3967
3968
3969 def is_line_short_enough(line: Line, *, line_length: int, line_str: str = "") -> bool:
3970     """Return True if `line` is no longer than `line_length`.
3971
3972     Uses the provided `line_str` rendering, if any, otherwise computes a new one.
3973     """
3974     if not line_str:
3975         line_str = str(line).strip("\n")
3976     return (
3977         len(line_str) <= line_length
3978         and "\n" not in line_str  # multiline strings
3979         and not line.contains_standalone_comments()
3980     )
3981
3982
3983 def can_be_split(line: Line) -> bool:
3984     """Return False if the line cannot be split *for sure*.
3985
3986     This is not an exhaustive search but a cheap heuristic that we can use to
3987     avoid some unfortunate formattings (mostly around wrapping unsplittable code
3988     in unnecessary parentheses).
3989     """
3990     leaves = line.leaves
3991     if len(leaves) < 2:
3992         return False
3993
3994     if leaves[0].type == token.STRING and leaves[1].type == token.DOT:
3995         call_count = 0
3996         dot_count = 0
3997         next = leaves[-1]
3998         for leaf in leaves[-2::-1]:
3999             if leaf.type in OPENING_BRACKETS:
4000                 if next.type not in CLOSING_BRACKETS:
4001                     return False
4002
4003                 call_count += 1
4004             elif leaf.type == token.DOT:
4005                 dot_count += 1
4006             elif leaf.type == token.NAME:
4007                 if not (next.type == token.DOT or next.type in OPENING_BRACKETS):
4008                     return False
4009
4010             elif leaf.type not in CLOSING_BRACKETS:
4011                 return False
4012
4013             if dot_count > 1 and call_count > 1:
4014                 return False
4015
4016     return True
4017
4018
4019 def can_omit_invisible_parens(line: Line, line_length: int) -> bool:
4020     """Does `line` have a shape safe to reformat without optional parens around it?
4021
4022     Returns True for only a subset of potentially nice looking formattings but
4023     the point is to not return false positives that end up producing lines that
4024     are too long.
4025     """
4026     bt = line.bracket_tracker
4027     if not bt.delimiters:
4028         # Without delimiters the optional parentheses are useless.
4029         return True
4030
4031     max_priority = bt.max_delimiter_priority()
4032     if bt.delimiter_count_with_priority(max_priority) > 1:
4033         # With more than one delimiter of a kind the optional parentheses read better.
4034         return False
4035
4036     if max_priority == DOT_PRIORITY:
4037         # A single stranded method call doesn't require optional parentheses.
4038         return True
4039
4040     assert len(line.leaves) >= 2, "Stranded delimiter"
4041
4042     first = line.leaves[0]
4043     second = line.leaves[1]
4044     penultimate = line.leaves[-2]
4045     last = line.leaves[-1]
4046
4047     # With a single delimiter, omit if the expression starts or ends with
4048     # a bracket.
4049     if first.type in OPENING_BRACKETS and second.type not in CLOSING_BRACKETS:
4050         remainder = False
4051         length = 4 * line.depth
4052         for _index, leaf, leaf_length in enumerate_with_length(line):
4053             if leaf.type in CLOSING_BRACKETS and leaf.opening_bracket is first:
4054                 remainder = True
4055             if remainder:
4056                 length += leaf_length
4057                 if length > line_length:
4058                     break
4059
4060                 if leaf.type in OPENING_BRACKETS:
4061                     # There are brackets we can further split on.
4062                     remainder = False
4063
4064         else:
4065             # checked the entire string and line length wasn't exceeded
4066             if len(line.leaves) == _index + 1:
4067                 return True
4068
4069         # Note: we are not returning False here because a line might have *both*
4070         # a leading opening bracket and a trailing closing bracket.  If the
4071         # opening bracket doesn't match our rule, maybe the closing will.
4072
4073     if (
4074         last.type == token.RPAR
4075         or last.type == token.RBRACE
4076         or (
4077             # don't use indexing for omitting optional parentheses;
4078             # it looks weird
4079             last.type == token.RSQB
4080             and last.parent
4081             and last.parent.type != syms.trailer
4082         )
4083     ):
4084         if penultimate.type in OPENING_BRACKETS:
4085             # Empty brackets don't help.
4086             return False
4087
4088         if is_multiline_string(first):
4089             # Additional wrapping of a multiline string in this situation is
4090             # unnecessary.
4091             return True
4092
4093         length = 4 * line.depth
4094         seen_other_brackets = False
4095         for _index, leaf, leaf_length in enumerate_with_length(line):
4096             length += leaf_length
4097             if leaf is last.opening_bracket:
4098                 if seen_other_brackets or length <= line_length:
4099                     return True
4100
4101             elif leaf.type in OPENING_BRACKETS:
4102                 # There are brackets we can further split on.
4103                 seen_other_brackets = True
4104
4105     return False
4106
4107
4108 def get_cache_file(mode: Mode) -> Path:
4109     return CACHE_DIR / f"cache.{mode.get_cache_key()}.pickle"
4110
4111
4112 def read_cache(mode: Mode) -> Cache:
4113     """Read the cache if it exists and is well formed.
4114
4115     If it is not well formed, the call to write_cache later should resolve the issue.
4116     """
4117     cache_file = get_cache_file(mode)
4118     if not cache_file.exists():
4119         return {}
4120
4121     with cache_file.open("rb") as fobj:
4122         try:
4123             cache: Cache = pickle.load(fobj)
4124         except (pickle.UnpicklingError, ValueError):
4125             return {}
4126
4127     return cache
4128
4129
4130 def get_cache_info(path: Path) -> CacheInfo:
4131     """Return the information used to check if a file is already formatted or not."""
4132     stat = path.stat()
4133     return stat.st_mtime, stat.st_size
4134
4135
4136 def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
4137     """Split an iterable of paths in `sources` into two sets.
4138
4139     The first contains paths of files that modified on disk or are not in the
4140     cache. The other contains paths to non-modified files.
4141     """
4142     todo, done = set(), set()
4143     for src in sources:
4144         src = src.resolve()
4145         if cache.get(src) != get_cache_info(src):
4146             todo.add(src)
4147         else:
4148             done.add(src)
4149     return todo, done
4150
4151
4152 def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
4153     """Update the cache file."""
4154     cache_file = get_cache_file(mode)
4155     try:
4156         CACHE_DIR.mkdir(parents=True, exist_ok=True)
4157         new_cache = {**cache, **{src.resolve(): get_cache_info(src) for src in sources}}
4158         with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
4159             pickle.dump(new_cache, f, protocol=4)
4160         os.replace(f.name, cache_file)
4161     except OSError:
4162         pass
4163
4164
4165 def patch_click() -> None:
4166     """Make Click not crash.
4167
4168     On certain misconfigured environments, Python 3 selects the ASCII encoding as the
4169     default which restricts paths that it can access during the lifetime of the
4170     application.  Click refuses to work in this scenario by raising a RuntimeError.
4171
4172     In case of Black the likelihood that non-ASCII characters are going to be used in
4173     file paths is minimal since it's Python source code.  Moreover, this crash was
4174     spurious on Python 3.7 thanks to PEP 538 and PEP 540.
4175     """
4176     try:
4177         from click import core
4178         from click import _unicodefun  # type: ignore
4179     except ModuleNotFoundError:
4180         return
4181
4182     for module in (core, _unicodefun):
4183         if hasattr(module, "_verify_python3_env"):
4184             module._verify_python3_env = lambda: None
4185
4186
4187 def patched_main() -> None:
4188     freeze_support()
4189     patch_click()
4190     main()
4191
4192
4193 if __name__ == "__main__":
4194     patched_main()