]> 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:

7b905eed350967424c6205b674c0e63677cc8c4f
[etc/vim.git] / black.py
1 import ast
2 import asyncio
3 from abc import ABC, abstractmethod
4 from collections import defaultdict
5 from concurrent.futures import Executor, ProcessPoolExecutor
6 from contextlib import contextmanager
7 from datetime import datetime
8 from enum import Enum
9 from functools import lru_cache, partial, wraps
10 import io
11 import itertools
12 import logging
13 from multiprocessing import Manager, freeze_support
14 import os
15 from pathlib import Path
16 import pickle
17 import regex as re
18 import signal
19 import sys
20 import tempfile
21 import tokenize
22 import traceback
23 from typing import (
24     Any,
25     Callable,
26     Collection,
27     Dict,
28     Generator,
29     Generic,
30     Iterable,
31     Iterator,
32     List,
33     Optional,
34     Pattern,
35     Sequence,
36     Set,
37     Tuple,
38     Type,
39     TypeVar,
40     Union,
41     cast,
42 )
43 from typing_extensions import Final
44 from mypy_extensions import mypyc_attr
45
46 from appdirs import user_cache_dir
47 from dataclasses import dataclass, field, replace
48 import click
49 import toml
50 from typed_ast import ast3, ast27
51 from pathspec import PathSpec
52
53 # lib2to3 fork
54 from blib2to3.pytree import Node, Leaf, type_repr
55 from blib2to3 import pygram, pytree
56 from blib2to3.pgen2 import driver, token
57 from blib2to3.pgen2.grammar import Grammar
58 from blib2to3.pgen2.parse import ParseError
59
60 from _black_version import version as __version__
61
62 DEFAULT_LINE_LENGTH = 88
63 DEFAULT_EXCLUDES = r"/(\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|\.svn|_build|buck-out|build|dist)/"  # noqa: B950
64 DEFAULT_INCLUDES = r"\.pyi?$"
65 CACHE_DIR = Path(user_cache_dir("black", version=__version__))
66
67 STRING_PREFIX_CHARS: Final = "furbFURB"  # All possible string prefix characters.
68
69
70 # types
71 FileContent = str
72 Encoding = str
73 NewLine = str
74 Depth = int
75 NodeType = int
76 ParserState = int
77 LeafID = int
78 StringID = int
79 Priority = int
80 Index = int
81 LN = Union[Leaf, Node]
82 Transformer = Callable[["Line", Collection["Feature"]], Iterator["Line"]]
83 Timestamp = float
84 FileSize = int
85 CacheInfo = Tuple[Timestamp, FileSize]
86 Cache = Dict[Path, CacheInfo]
87 out = partial(click.secho, bold=True, err=True)
88 err = partial(click.secho, fg="red", err=True)
89
90 pygram.initialize(CACHE_DIR)
91 syms = pygram.python_symbols
92
93
94 class NothingChanged(UserWarning):
95     """Raised when reformatted code is the same as source."""
96
97
98 class CannotTransform(Exception):
99     """Base class for errors raised by Transformers."""
100
101
102 class CannotSplit(CannotTransform):
103     """A readable split that fits the allotted line length is impossible."""
104
105
106 class InvalidInput(ValueError):
107     """Raised when input source code fails all parse attempts."""
108
109
110 T = TypeVar("T")
111 E = TypeVar("E", bound=Exception)
112
113
114 class Ok(Generic[T]):
115     def __init__(self, value: T) -> None:
116         self._value = value
117
118     def ok(self) -> T:
119         return self._value
120
121
122 class Err(Generic[E]):
123     def __init__(self, e: E) -> None:
124         self._e = e
125
126     def err(self) -> E:
127         return self._e
128
129
130 # The 'Result' return type is used to implement an error-handling model heavily
131 # influenced by that used by the Rust programming language
132 # (see https://doc.rust-lang.org/book/ch09-00-error-handling.html).
133 Result = Union[Ok[T], Err[E]]
134 TResult = Result[T, CannotTransform]  # (T)ransform Result
135 TMatchResult = TResult[Index]
136
137
138 class WriteBack(Enum):
139     NO = 0
140     YES = 1
141     DIFF = 2
142     CHECK = 3
143
144     @classmethod
145     def from_configuration(cls, *, check: bool, diff: bool) -> "WriteBack":
146         if check and not diff:
147             return cls.CHECK
148
149         return cls.DIFF if diff else cls.YES
150
151
152 class Changed(Enum):
153     NO = 0
154     CACHED = 1
155     YES = 2
156
157
158 class TargetVersion(Enum):
159     PY27 = 2
160     PY33 = 3
161     PY34 = 4
162     PY35 = 5
163     PY36 = 6
164     PY37 = 7
165     PY38 = 8
166
167     def is_python2(self) -> bool:
168         return self is TargetVersion.PY27
169
170
171 PY36_VERSIONS = {TargetVersion.PY36, TargetVersion.PY37, TargetVersion.PY38}
172
173
174 class Feature(Enum):
175     # All string literals are unicode
176     UNICODE_LITERALS = 1
177     F_STRINGS = 2
178     NUMERIC_UNDERSCORES = 3
179     TRAILING_COMMA_IN_CALL = 4
180     TRAILING_COMMA_IN_DEF = 5
181     # The following two feature-flags are mutually exclusive, and exactly one should be
182     # set for every version of python.
183     ASYNC_IDENTIFIERS = 6
184     ASYNC_KEYWORDS = 7
185     ASSIGNMENT_EXPRESSIONS = 8
186     POS_ONLY_ARGUMENTS = 9
187
188
189 VERSION_TO_FEATURES: Dict[TargetVersion, Set[Feature]] = {
190     TargetVersion.PY27: {Feature.ASYNC_IDENTIFIERS},
191     TargetVersion.PY33: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
192     TargetVersion.PY34: {Feature.UNICODE_LITERALS, Feature.ASYNC_IDENTIFIERS},
193     TargetVersion.PY35: {
194         Feature.UNICODE_LITERALS,
195         Feature.TRAILING_COMMA_IN_CALL,
196         Feature.ASYNC_IDENTIFIERS,
197     },
198     TargetVersion.PY36: {
199         Feature.UNICODE_LITERALS,
200         Feature.F_STRINGS,
201         Feature.NUMERIC_UNDERSCORES,
202         Feature.TRAILING_COMMA_IN_CALL,
203         Feature.TRAILING_COMMA_IN_DEF,
204         Feature.ASYNC_IDENTIFIERS,
205     },
206     TargetVersion.PY37: {
207         Feature.UNICODE_LITERALS,
208         Feature.F_STRINGS,
209         Feature.NUMERIC_UNDERSCORES,
210         Feature.TRAILING_COMMA_IN_CALL,
211         Feature.TRAILING_COMMA_IN_DEF,
212         Feature.ASYNC_KEYWORDS,
213     },
214     TargetVersion.PY38: {
215         Feature.UNICODE_LITERALS,
216         Feature.F_STRINGS,
217         Feature.NUMERIC_UNDERSCORES,
218         Feature.TRAILING_COMMA_IN_CALL,
219         Feature.TRAILING_COMMA_IN_DEF,
220         Feature.ASYNC_KEYWORDS,
221         Feature.ASSIGNMENT_EXPRESSIONS,
222         Feature.POS_ONLY_ARGUMENTS,
223     },
224 }
225
226
227 @dataclass
228 class Mode:
229     target_versions: Set[TargetVersion] = field(default_factory=set)
230     line_length: int = DEFAULT_LINE_LENGTH
231     string_normalization: bool = True
232     is_pyi: bool = False
233
234     def get_cache_key(self) -> str:
235         if self.target_versions:
236             version_str = ",".join(
237                 str(version.value)
238                 for version in sorted(self.target_versions, key=lambda v: v.value)
239             )
240         else:
241             version_str = "-"
242         parts = [
243             version_str,
244             str(self.line_length),
245             str(int(self.string_normalization)),
246             str(int(self.is_pyi)),
247         ]
248         return ".".join(parts)
249
250
251 # Legacy name, left for integrations.
252 FileMode = Mode
253
254
255 def supports_feature(target_versions: Set[TargetVersion], feature: Feature) -> bool:
256     return all(feature in VERSION_TO_FEATURES[version] for version in target_versions)
257
258
259 def find_pyproject_toml(path_search_start: str) -> Optional[str]:
260     """Find the absolute filepath to a pyproject.toml if it exists"""
261     path_project_root = find_project_root(path_search_start)
262     path_pyproject_toml = path_project_root / "pyproject.toml"
263     return str(path_pyproject_toml) if path_pyproject_toml.is_file() else None
264
265
266 def parse_pyproject_toml(path_config: str) -> Dict[str, Any]:
267     """Parse a pyproject toml file, pulling out relevant parts for Black
268
269     If parsing fails, will raise a toml.TomlDecodeError
270     """
271     pyproject_toml = toml.load(path_config)
272     config = pyproject_toml.get("tool", {}).get("black", {})
273     return {k.replace("--", "").replace("-", "_"): v for k, v in config.items()}
274
275
276 def read_pyproject_toml(
277     ctx: click.Context, param: click.Parameter, value: Optional[str]
278 ) -> Optional[str]:
279     """Inject Black configuration from "pyproject.toml" into defaults in `ctx`.
280
281     Returns the path to a successfully found and read configuration file, None
282     otherwise.
283     """
284     if not value:
285         value = find_pyproject_toml(ctx.params.get("src", ()))
286         if value is None:
287             return None
288
289     try:
290         config = parse_pyproject_toml(value)
291     except (toml.TomlDecodeError, OSError) as e:
292         raise click.FileError(
293             filename=value, hint=f"Error reading configuration file: {e}"
294         )
295
296     if not config:
297         return None
298
299     target_version = config.get("target_version")
300     if target_version is not None and not isinstance(target_version, list):
301         raise click.BadOptionUsage(
302             "target-version", f"Config key target-version must be a list"
303         )
304
305     default_map: Dict[str, Any] = {}
306     if ctx.default_map:
307         default_map.update(ctx.default_map)
308     default_map.update(config)
309
310     ctx.default_map = default_map
311     return value
312
313
314 def target_version_option_callback(
315     c: click.Context, p: Union[click.Option, click.Parameter], v: Tuple[str, ...]
316 ) -> List[TargetVersion]:
317     """Compute the target versions from a --target-version flag.
318
319     This is its own function because mypy couldn't infer the type correctly
320     when it was a lambda, causing mypyc trouble.
321     """
322     return [TargetVersion[val.upper()] for val in v]
323
324
325 @click.command(context_settings=dict(help_option_names=["-h", "--help"]))
326 @click.option("-c", "--code", type=str, help="Format the code passed in as a string.")
327 @click.option(
328     "-l",
329     "--line-length",
330     type=int,
331     default=DEFAULT_LINE_LENGTH,
332     help="How many characters per line to allow.",
333     show_default=True,
334 )
335 @click.option(
336     "-t",
337     "--target-version",
338     type=click.Choice([v.name.lower() for v in TargetVersion]),
339     callback=target_version_option_callback,
340     multiple=True,
341     help=(
342         "Python versions that should be supported by Black's output. [default: per-file"
343         " auto-detection]"
344     ),
345 )
346 @click.option(
347     "--py36",
348     is_flag=True,
349     help=(
350         "Allow using Python 3.6-only syntax on all input files.  This will put trailing"
351         " commas in function signatures and calls also after *args and **kwargs."
352         " Deprecated; use --target-version instead. [default: per-file auto-detection]"
353     ),
354 )
355 @click.option(
356     "--pyi",
357     is_flag=True,
358     help=(
359         "Format all input files like typing stubs regardless of file extension (useful"
360         " when piping source on standard input)."
361     ),
362 )
363 @click.option(
364     "-S",
365     "--skip-string-normalization",
366     is_flag=True,
367     help="Don't normalize string quotes or prefixes.",
368 )
369 @click.option(
370     "--check",
371     is_flag=True,
372     help=(
373         "Don't write the files back, just return the status.  Return code 0 means"
374         " nothing would change.  Return code 1 means some files would be reformatted."
375         " Return code 123 means there was an internal error."
376     ),
377 )
378 @click.option(
379     "--diff",
380     is_flag=True,
381     help="Don't write the files back, just output a diff for each file on stdout.",
382 )
383 @click.option(
384     "--fast/--safe",
385     is_flag=True,
386     help="If --fast given, skip temporary sanity checks. [default: --safe]",
387 )
388 @click.option(
389     "--include",
390     type=str,
391     default=DEFAULT_INCLUDES,
392     help=(
393         "A regular expression that matches files and directories that should be"
394         " included on recursive searches.  An empty value means all files are included"
395         " regardless of the name.  Use forward slashes for directories on all platforms"
396         " (Windows, too).  Exclusions are calculated first, inclusions later."
397     ),
398     show_default=True,
399 )
400 @click.option(
401     "--exclude",
402     type=str,
403     default=DEFAULT_EXCLUDES,
404     help=(
405         "A regular expression that matches files and directories that should be"
406         " excluded on recursive searches.  An empty value means no paths are excluded."
407         " Use forward slashes for directories on all platforms (Windows, too). "
408         " Exclusions are calculated first, inclusions later."
409     ),
410     show_default=True,
411 )
412 @click.option(
413     "-q",
414     "--quiet",
415     is_flag=True,
416     help=(
417         "Don't emit non-error messages to stderr. Errors are still emitted; silence"
418         " those with 2>/dev/null."
419     ),
420 )
421 @click.option(
422     "-v",
423     "--verbose",
424     is_flag=True,
425     help=(
426         "Also emit messages to stderr about files that were not changed or were ignored"
427         " due to --exclude=."
428     ),
429 )
430 @click.version_option(version=__version__)
431 @click.argument(
432     "src",
433     nargs=-1,
434     type=click.Path(
435         exists=True, file_okay=True, dir_okay=True, readable=True, allow_dash=True
436     ),
437     is_eager=True,
438 )
439 @click.option(
440     "--config",
441     type=click.Path(
442         exists=True,
443         file_okay=True,
444         dir_okay=False,
445         readable=True,
446         allow_dash=False,
447         path_type=str,
448     ),
449     is_eager=True,
450     callback=read_pyproject_toml,
451     help="Read configuration from PATH.",
452 )
453 @click.pass_context
454 def main(
455     ctx: click.Context,
456     code: Optional[str],
457     line_length: int,
458     target_version: List[TargetVersion],
459     check: bool,
460     diff: bool,
461     fast: bool,
462     pyi: bool,
463     py36: bool,
464     skip_string_normalization: bool,
465     quiet: bool,
466     verbose: bool,
467     include: str,
468     exclude: str,
469     src: Tuple[str, ...],
470     config: Optional[str],
471 ) -> None:
472     """The uncompromising code formatter."""
473     write_back = WriteBack.from_configuration(check=check, diff=diff)
474     if target_version:
475         if py36:
476             err("Cannot use both --target-version and --py36")
477             ctx.exit(2)
478         else:
479             versions = set(target_version)
480     elif py36:
481         err(
482             "--py36 is deprecated and will be removed in a future version. Use"
483             " --target-version py36 instead."
484         )
485         versions = PY36_VERSIONS
486     else:
487         # We'll autodetect later.
488         versions = set()
489     mode = Mode(
490         target_versions=versions,
491         line_length=line_length,
492         is_pyi=pyi,
493         string_normalization=not skip_string_normalization,
494     )
495     if config and verbose:
496         out(f"Using configuration from {config}.", bold=False, fg="blue")
497     if code is not None:
498         print(format_str(code, mode=mode))
499         ctx.exit(0)
500     try:
501         include_regex = re_compile_maybe_verbose(include)
502     except re.error:
503         err(f"Invalid regular expression for include given: {include!r}")
504         ctx.exit(2)
505     try:
506         exclude_regex = re_compile_maybe_verbose(exclude)
507     except re.error:
508         err(f"Invalid regular expression for exclude given: {exclude!r}")
509         ctx.exit(2)
510     report = Report(check=check, diff=diff, quiet=quiet, verbose=verbose)
511     root = find_project_root(src)
512     sources: Set[Path] = set()
513     path_empty(src, quiet, verbose, ctx)
514     for s in src:
515         p = Path(s)
516         if p.is_dir():
517             sources.update(
518                 gen_python_files_in_dir(
519                     p, root, include_regex, exclude_regex, report, get_gitignore(root)
520                 )
521             )
522         elif p.is_file() or s == "-":
523             # if a file was explicitly given, we don't care about its extension
524             sources.add(p)
525         else:
526             err(f"invalid path: {s}")
527     if len(sources) == 0:
528         if verbose or not quiet:
529             out("No Python files are present to be formatted. Nothing to do 😴")
530         ctx.exit(0)
531
532     if len(sources) == 1:
533         reformat_one(
534             src=sources.pop(),
535             fast=fast,
536             write_back=write_back,
537             mode=mode,
538             report=report,
539         )
540     else:
541         reformat_many(
542             sources=sources, fast=fast, write_back=write_back, mode=mode, report=report
543         )
544
545     if verbose or not quiet:
546         out("Oh no! 💥 💔 💥" if report.return_code else "All done! ✨ 🍰 ✨")
547         click.secho(str(report), err=True)
548     ctx.exit(report.return_code)
549
550
551 def path_empty(
552     src: Tuple[str, ...], quiet: bool, verbose: bool, ctx: click.Context
553 ) -> None:
554     """
555     Exit if there is no `src` provided for formatting
556     """
557     if not src:
558         if verbose or not quiet:
559             out("No Path provided. Nothing to do 😴")
560             ctx.exit(0)
561
562
563 def reformat_one(
564     src: Path, fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
565 ) -> None:
566     """Reformat a single file under `src` without spawning child processes.
567
568     `fast`, `write_back`, and `mode` options are passed to
569     :func:`format_file_in_place` or :func:`format_stdin_to_stdout`.
570     """
571     try:
572         changed = Changed.NO
573         if not src.is_file() and str(src) == "-":
574             if format_stdin_to_stdout(fast=fast, write_back=write_back, mode=mode):
575                 changed = Changed.YES
576         else:
577             cache: Cache = {}
578             if write_back != WriteBack.DIFF:
579                 cache = read_cache(mode)
580                 res_src = src.resolve()
581                 if res_src in cache and cache[res_src] == get_cache_info(res_src):
582                     changed = Changed.CACHED
583             if changed is not Changed.CACHED and format_file_in_place(
584                 src, fast=fast, write_back=write_back, mode=mode
585             ):
586                 changed = Changed.YES
587             if (write_back is WriteBack.YES and changed is not Changed.CACHED) or (
588                 write_back is WriteBack.CHECK and changed is Changed.NO
589             ):
590                 write_cache(cache, [src], mode)
591         report.done(src, changed)
592     except Exception as exc:
593         report.failed(src, str(exc))
594
595
596 def reformat_many(
597     sources: Set[Path], fast: bool, write_back: WriteBack, mode: Mode, report: "Report"
598 ) -> None:
599     """Reformat multiple files using a ProcessPoolExecutor."""
600     loop = asyncio.get_event_loop()
601     worker_count = os.cpu_count()
602     if sys.platform == "win32":
603         # Work around https://bugs.python.org/issue26903
604         worker_count = min(worker_count, 61)
605     executor = ProcessPoolExecutor(max_workers=worker_count)
606     try:
607         loop.run_until_complete(
608             schedule_formatting(
609                 sources=sources,
610                 fast=fast,
611                 write_back=write_back,
612                 mode=mode,
613                 report=report,
614                 loop=loop,
615                 executor=executor,
616             )
617         )
618     finally:
619         shutdown(loop)
620         executor.shutdown()
621
622
623 async def schedule_formatting(
624     sources: Set[Path],
625     fast: bool,
626     write_back: WriteBack,
627     mode: Mode,
628     report: "Report",
629     loop: asyncio.AbstractEventLoop,
630     executor: Executor,
631 ) -> None:
632     """Run formatting of `sources` in parallel using the provided `executor`.
633
634     (Use ProcessPoolExecutors for actual parallelism.)
635
636     `write_back`, `fast`, and `mode` options are passed to
637     :func:`format_file_in_place`.
638     """
639     cache: Cache = {}
640     if write_back != WriteBack.DIFF:
641         cache = read_cache(mode)
642         sources, cached = filter_cached(cache, sources)
643         for src in sorted(cached):
644             report.done(src, Changed.CACHED)
645     if not sources:
646         return
647
648     cancelled = []
649     sources_to_cache = []
650     lock = None
651     if write_back == WriteBack.DIFF:
652         # For diff output, we need locks to ensure we don't interleave output
653         # from different processes.
654         manager = Manager()
655         lock = manager.Lock()
656     tasks = {
657         asyncio.ensure_future(
658             loop.run_in_executor(
659                 executor, format_file_in_place, src, fast, mode, write_back, lock
660             )
661         ): src
662         for src in sorted(sources)
663     }
664     pending: Iterable["asyncio.Future[bool]"] = tasks.keys()
665     try:
666         loop.add_signal_handler(signal.SIGINT, cancel, pending)
667         loop.add_signal_handler(signal.SIGTERM, cancel, pending)
668     except NotImplementedError:
669         # There are no good alternatives for these on Windows.
670         pass
671     while pending:
672         done, _ = await asyncio.wait(pending, return_when=asyncio.FIRST_COMPLETED)
673         for task in done:
674             src = tasks.pop(task)
675             if task.cancelled():
676                 cancelled.append(task)
677             elif task.exception():
678                 report.failed(src, str(task.exception()))
679             else:
680                 changed = Changed.YES if task.result() else Changed.NO
681                 # If the file was written back or was successfully checked as
682                 # well-formatted, store this information in the cache.
683                 if write_back is WriteBack.YES or (
684                     write_back is WriteBack.CHECK and changed is Changed.NO
685                 ):
686                     sources_to_cache.append(src)
687                 report.done(src, changed)
688     if cancelled:
689         await asyncio.gather(*cancelled, loop=loop, return_exceptions=True)
690     if sources_to_cache:
691         write_cache(cache, sources_to_cache, mode)
692
693
694 def format_file_in_place(
695     src: Path,
696     fast: bool,
697     mode: Mode,
698     write_back: WriteBack = WriteBack.NO,
699     lock: Any = None,  # multiprocessing.Manager().Lock() is some crazy proxy
700 ) -> bool:
701     """Format file under `src` path. Return True if changed.
702
703     If `write_back` is DIFF, write a diff to stdout. If it is YES, write reformatted
704     code to the file.
705     `mode` and `fast` options are passed to :func:`format_file_contents`.
706     """
707     if src.suffix == ".pyi":
708         mode = replace(mode, is_pyi=True)
709
710     then = datetime.utcfromtimestamp(src.stat().st_mtime)
711     with open(src, "rb") as buf:
712         src_contents, encoding, newline = decode_bytes(buf.read())
713     try:
714         dst_contents = format_file_contents(src_contents, fast=fast, mode=mode)
715     except NothingChanged:
716         return False
717
718     if write_back == WriteBack.YES:
719         with open(src, "w", encoding=encoding, newline=newline) as f:
720             f.write(dst_contents)
721     elif write_back == WriteBack.DIFF:
722         now = datetime.utcnow()
723         src_name = f"{src}\t{then} +0000"
724         dst_name = f"{src}\t{now} +0000"
725         diff_contents = diff(src_contents, dst_contents, src_name, dst_name)
726
727         with lock or nullcontext():
728             f = io.TextIOWrapper(
729                 sys.stdout.buffer,
730                 encoding=encoding,
731                 newline=newline,
732                 write_through=True,
733             )
734             f.write(diff_contents)
735             f.detach()
736
737     return True
738
739
740 def format_stdin_to_stdout(
741     fast: bool, *, write_back: WriteBack = WriteBack.NO, mode: Mode
742 ) -> bool:
743     """Format file on stdin. Return True if changed.
744
745     If `write_back` is YES, write reformatted code back to stdout. If it is DIFF,
746     write a diff to stdout. The `mode` argument is passed to
747     :func:`format_file_contents`.
748     """
749     then = datetime.utcnow()
750     src, encoding, newline = decode_bytes(sys.stdin.buffer.read())
751     dst = src
752     try:
753         dst = format_file_contents(src, fast=fast, mode=mode)
754         return True
755
756     except NothingChanged:
757         return False
758
759     finally:
760         f = io.TextIOWrapper(
761             sys.stdout.buffer, encoding=encoding, newline=newline, write_through=True
762         )
763         if write_back == WriteBack.YES:
764             f.write(dst)
765         elif write_back == WriteBack.DIFF:
766             now = datetime.utcnow()
767             src_name = f"STDIN\t{then} +0000"
768             dst_name = f"STDOUT\t{now} +0000"
769             f.write(diff(src, dst, src_name, dst_name))
770         f.detach()
771
772
773 def format_file_contents(src_contents: str, *, fast: bool, mode: Mode) -> FileContent:
774     """Reformat contents a file and return new contents.
775
776     If `fast` is False, additionally confirm that the reformatted code is
777     valid by calling :func:`assert_equivalent` and :func:`assert_stable` on it.
778     `mode` is passed to :func:`format_str`.
779     """
780     if src_contents.strip() == "":
781         raise NothingChanged
782
783     dst_contents = format_str(src_contents, mode=mode)
784     if src_contents == dst_contents:
785         raise NothingChanged
786
787     if not fast:
788         assert_equivalent(src_contents, dst_contents)
789         assert_stable(src_contents, dst_contents, mode=mode)
790     return dst_contents
791
792
793 def format_str(src_contents: str, *, mode: Mode) -> FileContent:
794     """Reformat a string and return new contents.
795
796     `mode` determines formatting options, such as how many characters per line are
797     allowed.  Example:
798
799     >>> import black
800     >>> print(black.format_str("def f(arg:str='')->None:...", mode=Mode()))
801     def f(arg: str = "") -> None:
802         ...
803
804     A more complex example:
805     >>> print(
806     ...   black.format_str(
807     ...     "def f(arg:str='')->None: hey",
808     ...     mode=black.Mode(
809     ...       target_versions={black.TargetVersion.PY36},
810     ...       line_length=10,
811     ...       string_normalization=False,
812     ...       is_pyi=False,
813     ...     ),
814     ...   ),
815     ... )
816     def f(
817         arg: str = '',
818     ) -> None:
819         hey
820
821     """
822     src_node = lib2to3_parse(src_contents.lstrip(), mode.target_versions)
823     dst_contents = []
824     future_imports = get_future_imports(src_node)
825     if mode.target_versions:
826         versions = mode.target_versions
827     else:
828         versions = detect_target_versions(src_node)
829     normalize_fmt_off(src_node)
830     lines = LineGenerator(
831         remove_u_prefix="unicode_literals" in future_imports
832         or supports_feature(versions, Feature.UNICODE_LITERALS),
833         is_pyi=mode.is_pyi,
834         normalize_strings=mode.string_normalization,
835     )
836     elt = EmptyLineTracker(is_pyi=mode.is_pyi)
837     empty_line = Line()
838     after = 0
839     split_line_features = {
840         feature
841         for feature in {Feature.TRAILING_COMMA_IN_CALL, Feature.TRAILING_COMMA_IN_DEF}
842         if supports_feature(versions, feature)
843     }
844     for current_line in lines.visit(src_node):
845         dst_contents.append(str(empty_line) * after)
846         before, after = elt.maybe_empty_lines(current_line)
847         dst_contents.append(str(empty_line) * before)
848         for line in transform_line(
849             current_line,
850             line_length=mode.line_length,
851             normalize_strings=mode.string_normalization,
852             features=split_line_features,
853         ):
854             dst_contents.append(str(line))
855     return "".join(dst_contents)
856
857
858 def decode_bytes(src: bytes) -> Tuple[FileContent, Encoding, NewLine]:
859     """Return a tuple of (decoded_contents, encoding, newline).
860
861     `newline` is either CRLF or LF but `decoded_contents` is decoded with
862     universal newlines (i.e. only contains LF).
863     """
864     srcbuf = io.BytesIO(src)
865     encoding, lines = tokenize.detect_encoding(srcbuf.readline)
866     if not lines:
867         return "", encoding, "\n"
868
869     newline = "\r\n" if b"\r\n" == lines[0][-2:] else "\n"
870     srcbuf.seek(0)
871     with io.TextIOWrapper(srcbuf, encoding) as tiow:
872         return tiow.read(), encoding, newline
873
874
875 def get_grammars(target_versions: Set[TargetVersion]) -> List[Grammar]:
876     if not target_versions:
877         # No target_version specified, so try all grammars.
878         return [
879             # Python 3.7+
880             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords,
881             # Python 3.0-3.6
882             pygram.python_grammar_no_print_statement_no_exec_statement,
883             # Python 2.7 with future print_function import
884             pygram.python_grammar_no_print_statement,
885             # Python 2.7
886             pygram.python_grammar,
887         ]
888
889     if all(version.is_python2() for version in target_versions):
890         # Python 2-only code, so try Python 2 grammars.
891         return [
892             # Python 2.7 with future print_function import
893             pygram.python_grammar_no_print_statement,
894             # Python 2.7
895             pygram.python_grammar,
896         ]
897
898     # Python 3-compatible code, so only try Python 3 grammar.
899     grammars = []
900     # If we have to parse both, try to parse async as a keyword first
901     if not supports_feature(target_versions, Feature.ASYNC_IDENTIFIERS):
902         # Python 3.7+
903         grammars.append(
904             pygram.python_grammar_no_print_statement_no_exec_statement_async_keywords
905         )
906     if not supports_feature(target_versions, Feature.ASYNC_KEYWORDS):
907         # Python 3.0-3.6
908         grammars.append(pygram.python_grammar_no_print_statement_no_exec_statement)
909     # At least one of the above branches must have been taken, because every Python
910     # version has exactly one of the two 'ASYNC_*' flags
911     return grammars
912
913
914 def lib2to3_parse(src_txt: str, target_versions: Iterable[TargetVersion] = ()) -> Node:
915     """Given a string with source, return the lib2to3 Node."""
916     if src_txt[-1:] != "\n":
917         src_txt += "\n"
918
919     for grammar in get_grammars(set(target_versions)):
920         drv = driver.Driver(grammar, pytree.convert)
921         try:
922             result = drv.parse_string(src_txt, True)
923             break
924
925         except ParseError as pe:
926             lineno, column = pe.context[1]
927             lines = src_txt.splitlines()
928             try:
929                 faulty_line = lines[lineno - 1]
930             except IndexError:
931                 faulty_line = "<line number missing in source>"
932             exc = InvalidInput(f"Cannot parse: {lineno}:{column}: {faulty_line}")
933     else:
934         raise exc from None
935
936     if isinstance(result, Leaf):
937         result = Node(syms.file_input, [result])
938     return result
939
940
941 def lib2to3_unparse(node: Node) -> str:
942     """Given a lib2to3 node, return its string representation."""
943     code = str(node)
944     return code
945
946
947 class Visitor(Generic[T]):
948     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
949
950     def visit(self, node: LN) -> Iterator[T]:
951         """Main method to visit `node` and its children.
952
953         It tries to find a `visit_*()` method for the given `node.type`, like
954         `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
955         If no dedicated `visit_*()` method is found, chooses `visit_default()`
956         instead.
957
958         Then yields objects of type `T` from the selected visitor.
959         """
960         if node.type < 256:
961             name = token.tok_name[node.type]
962         else:
963             name = str(type_repr(node.type))
964         # We explicitly branch on whether a visitor exists (instead of
965         # using self.visit_default as the default arg to getattr) in order
966         # to save needing to create a bound method object and so mypyc can
967         # generate a native call to visit_default.
968         visitf = getattr(self, f"visit_{name}", None)
969         if visitf:
970             yield from visitf(node)
971         else:
972             yield from self.visit_default(node)
973
974     def visit_default(self, node: LN) -> Iterator[T]:
975         """Default `visit_*()` implementation. Recurses to children of `node`."""
976         if isinstance(node, Node):
977             for child in node.children:
978                 yield from self.visit(child)
979
980
981 @dataclass
982 class DebugVisitor(Visitor[T]):
983     tree_depth: int = 0
984
985     def visit_default(self, node: LN) -> Iterator[T]:
986         indent = " " * (2 * self.tree_depth)
987         if isinstance(node, Node):
988             _type = type_repr(node.type)
989             out(f"{indent}{_type}", fg="yellow")
990             self.tree_depth += 1
991             for child in node.children:
992                 yield from self.visit(child)
993
994             self.tree_depth -= 1
995             out(f"{indent}/{_type}", fg="yellow", bold=False)
996         else:
997             _type = token.tok_name.get(node.type, str(node.type))
998             out(f"{indent}{_type}", fg="blue", nl=False)
999             if node.prefix:
1000                 # We don't have to handle prefixes for `Node` objects since
1001                 # that delegates to the first child anyway.
1002                 out(f" {node.prefix!r}", fg="green", bold=False, nl=False)
1003             out(f" {node.value!r}", fg="blue", bold=False)
1004
1005     @classmethod
1006     def show(cls, code: Union[str, Leaf, Node]) -> None:
1007         """Pretty-print the lib2to3 AST of a given string of `code`.
1008
1009         Convenience method for debugging.
1010         """
1011         v: DebugVisitor[None] = DebugVisitor()
1012         if isinstance(code, str):
1013             code = lib2to3_parse(code)
1014         list(v.visit(code))
1015
1016
1017 WHITESPACE: Final = {token.DEDENT, token.INDENT, token.NEWLINE}
1018 STATEMENT: Final = {
1019     syms.if_stmt,
1020     syms.while_stmt,
1021     syms.for_stmt,
1022     syms.try_stmt,
1023     syms.except_clause,
1024     syms.with_stmt,
1025     syms.funcdef,
1026     syms.classdef,
1027 }
1028 STANDALONE_COMMENT: Final = 153
1029 token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
1030 LOGIC_OPERATORS: Final = {"and", "or"}
1031 COMPARATORS: Final = {
1032     token.LESS,
1033     token.GREATER,
1034     token.EQEQUAL,
1035     token.NOTEQUAL,
1036     token.LESSEQUAL,
1037     token.GREATEREQUAL,
1038 }
1039 MATH_OPERATORS: Final = {
1040     token.VBAR,
1041     token.CIRCUMFLEX,
1042     token.AMPER,
1043     token.LEFTSHIFT,
1044     token.RIGHTSHIFT,
1045     token.PLUS,
1046     token.MINUS,
1047     token.STAR,
1048     token.SLASH,
1049     token.DOUBLESLASH,
1050     token.PERCENT,
1051     token.AT,
1052     token.TILDE,
1053     token.DOUBLESTAR,
1054 }
1055 STARS: Final = {token.STAR, token.DOUBLESTAR}
1056 VARARGS_SPECIALS: Final = STARS | {token.SLASH}
1057 VARARGS_PARENTS: Final = {
1058     syms.arglist,
1059     syms.argument,  # double star in arglist
1060     syms.trailer,  # single argument to call
1061     syms.typedargslist,
1062     syms.varargslist,  # lambdas
1063 }
1064 UNPACKING_PARENTS: Final = {
1065     syms.atom,  # single element of a list or set literal
1066     syms.dictsetmaker,
1067     syms.listmaker,
1068     syms.testlist_gexp,
1069     syms.testlist_star_expr,
1070 }
1071 TEST_DESCENDANTS: Final = {
1072     syms.test,
1073     syms.lambdef,
1074     syms.or_test,
1075     syms.and_test,
1076     syms.not_test,
1077     syms.comparison,
1078     syms.star_expr,
1079     syms.expr,
1080     syms.xor_expr,
1081     syms.and_expr,
1082     syms.shift_expr,
1083     syms.arith_expr,
1084     syms.trailer,
1085     syms.term,
1086     syms.power,
1087 }
1088 ASSIGNMENTS: Final = {
1089     "=",
1090     "+=",
1091     "-=",
1092     "*=",
1093     "@=",
1094     "/=",
1095     "%=",
1096     "&=",
1097     "|=",
1098     "^=",
1099     "<<=",
1100     ">>=",
1101     "**=",
1102     "//=",
1103 }
1104 COMPREHENSION_PRIORITY: Final = 20
1105 COMMA_PRIORITY: Final = 18
1106 TERNARY_PRIORITY: Final = 16
1107 LOGIC_PRIORITY: Final = 14
1108 STRING_PRIORITY: Final = 12
1109 COMPARATOR_PRIORITY: Final = 10
1110 MATH_PRIORITIES: Final = {
1111     token.VBAR: 9,
1112     token.CIRCUMFLEX: 8,
1113     token.AMPER: 7,
1114     token.LEFTSHIFT: 6,
1115     token.RIGHTSHIFT: 6,
1116     token.PLUS: 5,
1117     token.MINUS: 5,
1118     token.STAR: 4,
1119     token.SLASH: 4,
1120     token.DOUBLESLASH: 4,
1121     token.PERCENT: 4,
1122     token.AT: 4,
1123     token.TILDE: 3,
1124     token.DOUBLESTAR: 2,
1125 }
1126 DOT_PRIORITY: Final = 1
1127
1128
1129 @dataclass
1130 class BracketTracker:
1131     """Keeps track of brackets on a line."""
1132
1133     depth: int = 0
1134     bracket_match: Dict[Tuple[Depth, NodeType], Leaf] = field(default_factory=dict)
1135     delimiters: Dict[LeafID, Priority] = field(default_factory=dict)
1136     previous: Optional[Leaf] = None
1137     _for_loop_depths: List[int] = field(default_factory=list)
1138     _lambda_argument_depths: List[int] = field(default_factory=list)
1139
1140     def mark(self, leaf: Leaf) -> None:
1141         """Mark `leaf` with bracket-related metadata. Keep track of delimiters.
1142
1143         All leaves receive an int `bracket_depth` field that stores how deep
1144         within brackets a given leaf is. 0 means there are no enclosing brackets
1145         that started on this line.
1146
1147         If a leaf is itself a closing bracket, it receives an `opening_bracket`
1148         field that it forms a pair with. This is a one-directional link to
1149         avoid reference cycles.
1150
1151         If a leaf is a delimiter (a token on which Black can split the line if
1152         needed) and it's on depth 0, its `id()` is stored in the tracker's
1153         `delimiters` field.
1154         """
1155         if leaf.type == token.COMMENT:
1156             return
1157
1158         self.maybe_decrement_after_for_loop_variable(leaf)
1159         self.maybe_decrement_after_lambda_arguments(leaf)
1160         if leaf.type in CLOSING_BRACKETS:
1161             self.depth -= 1
1162             opening_bracket = self.bracket_match.pop((self.depth, leaf.type))
1163             leaf.opening_bracket = opening_bracket
1164         leaf.bracket_depth = self.depth
1165         if self.depth == 0:
1166             delim = is_split_before_delimiter(leaf, self.previous)
1167             if delim and self.previous is not None:
1168                 self.delimiters[id(self.previous)] = delim
1169             else:
1170                 delim = is_split_after_delimiter(leaf, self.previous)
1171                 if delim:
1172                     self.delimiters[id(leaf)] = delim
1173         if leaf.type in OPENING_BRACKETS:
1174             self.bracket_match[self.depth, BRACKET[leaf.type]] = leaf
1175             self.depth += 1
1176         self.previous = leaf
1177         self.maybe_increment_lambda_arguments(leaf)
1178         self.maybe_increment_for_loop_variable(leaf)
1179
1180     def any_open_brackets(self) -> bool:
1181         """Return True if there is an yet unmatched open bracket on the line."""
1182         return bool(self.bracket_match)
1183
1184     def max_delimiter_priority(self, exclude: Iterable[LeafID] = ()) -> Priority:
1185         """Return the highest priority of a delimiter found on the line.
1186
1187         Values are consistent with what `is_split_*_delimiter()` return.
1188         Raises ValueError on no delimiters.
1189         """
1190         return max(v for k, v in self.delimiters.items() if k not in exclude)
1191
1192     def delimiter_count_with_priority(self, priority: Priority = 0) -> int:
1193         """Return the number of delimiters with the given `priority`.
1194
1195         If no `priority` is passed, defaults to max priority on the line.
1196         """
1197         if not self.delimiters:
1198             return 0
1199
1200         priority = priority or self.max_delimiter_priority()
1201         return sum(1 for p in self.delimiters.values() if p == priority)
1202
1203     def maybe_increment_for_loop_variable(self, leaf: Leaf) -> bool:
1204         """In a for loop, or comprehension, the variables are often unpacks.
1205
1206         To avoid splitting on the comma in this situation, increase the depth of
1207         tokens between `for` and `in`.
1208         """
1209         if leaf.type == token.NAME and leaf.value == "for":
1210             self.depth += 1
1211             self._for_loop_depths.append(self.depth)
1212             return True
1213
1214         return False
1215
1216     def maybe_decrement_after_for_loop_variable(self, leaf: Leaf) -> bool:
1217         """See `maybe_increment_for_loop_variable` above for explanation."""
1218         if (
1219             self._for_loop_depths
1220             and self._for_loop_depths[-1] == self.depth
1221             and leaf.type == token.NAME
1222             and leaf.value == "in"
1223         ):
1224             self.depth -= 1
1225             self._for_loop_depths.pop()
1226             return True
1227
1228         return False
1229
1230     def maybe_increment_lambda_arguments(self, leaf: Leaf) -> bool:
1231         """In a lambda expression, there might be more than one argument.
1232
1233         To avoid splitting on the comma in this situation, increase the depth of
1234         tokens between `lambda` and `:`.
1235         """
1236         if leaf.type == token.NAME and leaf.value == "lambda":
1237             self.depth += 1
1238             self._lambda_argument_depths.append(self.depth)
1239             return True
1240
1241         return False
1242
1243     def maybe_decrement_after_lambda_arguments(self, leaf: Leaf) -> bool:
1244         """See `maybe_increment_lambda_arguments` above for explanation."""
1245         if (
1246             self._lambda_argument_depths
1247             and self._lambda_argument_depths[-1] == self.depth
1248             and leaf.type == token.COLON
1249         ):
1250             self.depth -= 1
1251             self._lambda_argument_depths.pop()
1252             return True
1253
1254         return False
1255
1256     def get_open_lsqb(self) -> Optional[Leaf]:
1257         """Return the most recent opening square bracket (if any)."""
1258         return self.bracket_match.get((self.depth - 1, token.RSQB))
1259
1260
1261 @dataclass
1262 class Line:
1263     """Holds leaves and comments. Can be printed with `str(line)`."""
1264
1265     depth: int = 0
1266     leaves: List[Leaf] = field(default_factory=list)
1267     # keys ordered like `leaves`
1268     comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
1269     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
1270     inside_brackets: bool = False
1271     should_explode: bool = False
1272
1273     def append(self, leaf: Leaf, preformatted: bool = False) -> None:
1274         """Add a new `leaf` to the end of the line.
1275
1276         Unless `preformatted` is True, the `leaf` will receive a new consistent
1277         whitespace prefix and metadata applied by :class:`BracketTracker`.
1278         Trailing commas are maybe removed, unpacked for loop variables are
1279         demoted from being delimiters.
1280
1281         Inline comments are put aside.
1282         """
1283         has_value = leaf.type in BRACKETS or bool(leaf.value.strip())
1284         if not has_value:
1285             return
1286
1287         if token.COLON == leaf.type and self.is_class_paren_empty:
1288             del self.leaves[-2:]
1289         if self.leaves and not preformatted:
1290             # Note: at this point leaf.prefix should be empty except for
1291             # imports, for which we only preserve newlines.
1292             leaf.prefix += whitespace(
1293                 leaf, complex_subscript=self.is_complex_subscript(leaf)
1294             )
1295         if self.inside_brackets or not preformatted:
1296             self.bracket_tracker.mark(leaf)
1297             self.maybe_remove_trailing_comma(leaf)
1298         if not self.append_comment(leaf):
1299             self.leaves.append(leaf)
1300
1301     def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
1302         """Like :func:`append()` but disallow invalid standalone comment structure.
1303
1304         Raises ValueError when any `leaf` is appended after a standalone comment
1305         or when a standalone comment is not the first leaf on the line.
1306         """
1307         if self.bracket_tracker.depth == 0:
1308             if self.is_comment:
1309                 raise ValueError("cannot append to standalone comments")
1310
1311             if self.leaves and leaf.type == STANDALONE_COMMENT:
1312                 raise ValueError(
1313                     "cannot append standalone comments to a populated line"
1314                 )
1315
1316         self.append(leaf, preformatted=preformatted)
1317
1318     @property
1319     def is_comment(self) -> bool:
1320         """Is this line a standalone comment?"""
1321         return len(self.leaves) == 1 and self.leaves[0].type == STANDALONE_COMMENT
1322
1323     @property
1324     def is_decorator(self) -> bool:
1325         """Is this line a decorator?"""
1326         return bool(self) and self.leaves[0].type == token.AT
1327
1328     @property
1329     def is_import(self) -> bool:
1330         """Is this an import line?"""
1331         return bool(self) and is_import(self.leaves[0])
1332
1333     @property
1334     def is_class(self) -> bool:
1335         """Is this line a class definition?"""
1336         return (
1337             bool(self)
1338             and self.leaves[0].type == token.NAME
1339             and self.leaves[0].value == "class"
1340         )
1341
1342     @property
1343     def is_stub_class(self) -> bool:
1344         """Is this line a class definition with a body consisting only of "..."?"""
1345         return self.is_class and self.leaves[-3:] == [
1346             Leaf(token.DOT, ".") for _ in range(3)
1347         ]
1348
1349     @property
1350     def is_collection_with_optional_trailing_comma(self) -> bool:
1351         """Is this line a collection literal with a trailing comma that's optional?
1352
1353         Note that the trailing comma in a 1-tuple is not optional.
1354         """
1355         if not self.leaves or len(self.leaves) < 4:
1356             return False
1357
1358         # Look for and address a trailing colon.
1359         if self.leaves[-1].type == token.COLON:
1360             closer = self.leaves[-2]
1361             close_index = -2
1362         else:
1363             closer = self.leaves[-1]
1364             close_index = -1
1365         if closer.type not in CLOSING_BRACKETS or self.inside_brackets:
1366             return False
1367
1368         if closer.type == token.RPAR:
1369             # Tuples require an extra check, because if there's only
1370             # one element in the tuple removing the comma unmakes the
1371             # tuple.
1372             #
1373             # We also check for parens before looking for the trailing
1374             # comma because in some cases (eg assigning a dict
1375             # literal) the literal gets wrapped in temporary parens
1376             # during parsing. This case is covered by the
1377             # collections.py test data.
1378             opener = closer.opening_bracket
1379             for _open_index, leaf in enumerate(self.leaves):
1380                 if leaf is opener:
1381                     break
1382
1383             else:
1384                 # Couldn't find the matching opening paren, play it safe.
1385                 return False
1386
1387             commas = 0
1388             comma_depth = self.leaves[close_index - 1].bracket_depth
1389             for leaf in self.leaves[_open_index + 1 : close_index]:
1390                 if leaf.bracket_depth == comma_depth and leaf.type == token.COMMA:
1391                     commas += 1
1392             if commas > 1:
1393                 # We haven't looked yet for the trailing comma because
1394                 # we might also have caught noop parens.
1395                 return self.leaves[close_index - 1].type == token.COMMA
1396
1397             elif commas == 1:
1398                 return False  # it's either a one-tuple or didn't have a trailing comma
1399
1400             if self.leaves[close_index - 1].type in CLOSING_BRACKETS:
1401                 close_index -= 1
1402                 closer = self.leaves[close_index]
1403                 if closer.type == token.RPAR:
1404                     # TODO: this is a gut feeling. Will we ever see this?
1405                     return False
1406
1407         if self.leaves[close_index - 1].type != token.COMMA:
1408             return False
1409
1410         return True
1411
1412     @property
1413     def is_def(self) -> bool:
1414         """Is this a function definition? (Also returns True for async defs.)"""
1415         try:
1416             first_leaf = self.leaves[0]
1417         except IndexError:
1418             return False
1419
1420         try:
1421             second_leaf: Optional[Leaf] = self.leaves[1]
1422         except IndexError:
1423             second_leaf = None
1424         return (first_leaf.type == token.NAME and first_leaf.value == "def") or (
1425             first_leaf.type == token.ASYNC
1426             and second_leaf is not None
1427             and second_leaf.type == token.NAME
1428             and second_leaf.value == "def"
1429         )
1430
1431     @property
1432     def is_class_paren_empty(self) -> bool:
1433         """Is this a class with no base classes but using parentheses?
1434
1435         Those are unnecessary and should be removed.
1436         """
1437         return (
1438             bool(self)
1439             and len(self.leaves) == 4
1440             and self.is_class
1441             and self.leaves[2].type == token.LPAR
1442             and self.leaves[2].value == "("
1443             and self.leaves[3].type == token.RPAR
1444             and self.leaves[3].value == ")"
1445         )
1446
1447     @property
1448     def is_triple_quoted_string(self) -> bool:
1449         """Is the line a triple quoted string?"""
1450         return (
1451             bool(self)
1452             and self.leaves[0].type == token.STRING
1453             and self.leaves[0].value.startswith(('"""', "'''"))
1454         )
1455
1456     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
1457         """If so, needs to be split before emitting."""
1458         for leaf in self.leaves:
1459             if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
1460                 return True
1461
1462         return False
1463
1464     def contains_uncollapsable_type_comments(self) -> bool:
1465         ignored_ids = set()
1466         try:
1467             last_leaf = self.leaves[-1]
1468             ignored_ids.add(id(last_leaf))
1469             if last_leaf.type == token.COMMA or (
1470                 last_leaf.type == token.RPAR and not last_leaf.value
1471             ):
1472                 # When trailing commas or optional parens are inserted by Black for
1473                 # consistency, comments after the previous last element are not moved
1474                 # (they don't have to, rendering will still be correct).  So we ignore
1475                 # trailing commas and invisible.
1476                 last_leaf = self.leaves[-2]
1477                 ignored_ids.add(id(last_leaf))
1478         except IndexError:
1479             return False
1480
1481         # A type comment is uncollapsable if it is attached to a leaf
1482         # that isn't at the end of the line (since that could cause it
1483         # to get associated to a different argument) or if there are
1484         # comments before it (since that could cause it to get hidden
1485         # behind a comment.
1486         comment_seen = False
1487         for leaf_id, comments in self.comments.items():
1488             for comment in comments:
1489                 if is_type_comment(comment):
1490                     if comment_seen or (
1491                         not is_type_comment(comment, " ignore")
1492                         and leaf_id not in ignored_ids
1493                     ):
1494                         return True
1495
1496                 comment_seen = True
1497
1498         return False
1499
1500     def contains_unsplittable_type_ignore(self) -> bool:
1501         if not self.leaves:
1502             return False
1503
1504         # If a 'type: ignore' is attached to the end of a line, we
1505         # can't split the line, because we can't know which of the
1506         # subexpressions the ignore was meant to apply to.
1507         #
1508         # We only want this to apply to actual physical lines from the
1509         # original source, though: we don't want the presence of a
1510         # 'type: ignore' at the end of a multiline expression to
1511         # justify pushing it all onto one line. Thus we
1512         # (unfortunately) need to check the actual source lines and
1513         # only report an unsplittable 'type: ignore' if this line was
1514         # one line in the original code.
1515
1516         # Grab the first and last line numbers, skipping generated leaves
1517         first_line = next((l.lineno for l in self.leaves if l.lineno != 0), 0)
1518         last_line = next((l.lineno for l in reversed(self.leaves) if l.lineno != 0), 0)
1519
1520         if first_line == last_line:
1521             # We look at the last two leaves since a comma or an
1522             # invisible paren could have been added at the end of the
1523             # line.
1524             for node in self.leaves[-2:]:
1525                 for comment in self.comments.get(id(node), []):
1526                     if is_type_comment(comment, " ignore"):
1527                         return True
1528
1529         return False
1530
1531     def contains_multiline_strings(self) -> bool:
1532         return any(is_multiline_string(leaf) for leaf in self.leaves)
1533
1534     def maybe_remove_trailing_comma(self, closing: Leaf) -> bool:
1535         """Remove trailing comma if there is one and it's safe."""
1536         if not (self.leaves and self.leaves[-1].type == token.COMMA):
1537             return False
1538
1539         # We remove trailing commas only in the case of importing a
1540         # single name from a module.
1541         if not (
1542             self.leaves
1543             and self.is_import
1544             and len(self.leaves) > 4
1545             and self.leaves[-1].type == token.COMMA
1546             and closing.type in CLOSING_BRACKETS
1547             and self.leaves[-4].type == token.NAME
1548             and (
1549                 # regular `from foo import bar,`
1550                 self.leaves[-4].value == "import"
1551                 # `from foo import (bar as baz,)
1552                 or (
1553                     len(self.leaves) > 6
1554                     and self.leaves[-6].value == "import"
1555                     and self.leaves[-3].value == "as"
1556                 )
1557                 # `from foo import bar as baz,`
1558                 or (
1559                     len(self.leaves) > 5
1560                     and self.leaves[-5].value == "import"
1561                     and self.leaves[-3].value == "as"
1562                 )
1563             )
1564             and closing.type == token.RPAR
1565         ):
1566             return False
1567
1568         self.remove_trailing_comma()
1569         return True
1570
1571     def append_comment(self, comment: Leaf) -> bool:
1572         """Add an inline or standalone comment to the line."""
1573         if (
1574             comment.type == STANDALONE_COMMENT
1575             and self.bracket_tracker.any_open_brackets()
1576         ):
1577             comment.prefix = ""
1578             return False
1579
1580         if comment.type != token.COMMENT:
1581             return False
1582
1583         if not self.leaves:
1584             comment.type = STANDALONE_COMMENT
1585             comment.prefix = ""
1586             return False
1587
1588         last_leaf = self.leaves[-1]
1589         if (
1590             last_leaf.type == token.RPAR
1591             and not last_leaf.value
1592             and last_leaf.parent
1593             and len(list(last_leaf.parent.leaves())) <= 3
1594             and not is_type_comment(comment)
1595         ):
1596             # Comments on an optional parens wrapping a single leaf should belong to
1597             # the wrapped node except if it's a type comment. Pinning the comment like
1598             # this avoids unstable formatting caused by comment migration.
1599             if len(self.leaves) < 2:
1600                 comment.type = STANDALONE_COMMENT
1601                 comment.prefix = ""
1602                 return False
1603
1604             last_leaf = self.leaves[-2]
1605         self.comments.setdefault(id(last_leaf), []).append(comment)
1606         return True
1607
1608     def comments_after(self, leaf: Leaf) -> List[Leaf]:
1609         """Generate comments that should appear directly after `leaf`."""
1610         return self.comments.get(id(leaf), [])
1611
1612     def remove_trailing_comma(self) -> None:
1613         """Remove the trailing comma and moves the comments attached to it."""
1614         trailing_comma = self.leaves.pop()
1615         trailing_comma_comments = self.comments.pop(id(trailing_comma), [])
1616         self.comments.setdefault(id(self.leaves[-1]), []).extend(
1617             trailing_comma_comments
1618         )
1619
1620     def is_complex_subscript(self, leaf: Leaf) -> bool:
1621         """Return True iff `leaf` is part of a slice with non-trivial exprs."""
1622         open_lsqb = self.bracket_tracker.get_open_lsqb()
1623         if open_lsqb is None:
1624             return False
1625
1626         subscript_start = open_lsqb.next_sibling
1627
1628         if isinstance(subscript_start, Node):
1629             if subscript_start.type == syms.listmaker:
1630                 return False
1631
1632             if subscript_start.type == syms.subscriptlist:
1633                 subscript_start = child_towards(subscript_start, leaf)
1634         return subscript_start is not None and any(
1635             n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
1636         )
1637
1638     def clone(self) -> "Line":
1639         return Line(
1640             depth=self.depth,
1641             inside_brackets=self.inside_brackets,
1642             should_explode=self.should_explode,
1643         )
1644
1645     def __str__(self) -> str:
1646         """Render the line."""
1647         if not self:
1648             return "\n"
1649
1650         indent = "    " * self.depth
1651         leaves = iter(self.leaves)
1652         first = next(leaves)
1653         res = f"{first.prefix}{indent}{first.value}"
1654         for leaf in leaves:
1655             res += str(leaf)
1656         for comment in itertools.chain.from_iterable(self.comments.values()):
1657             res += str(comment)
1658
1659         return res + "\n"
1660
1661     def __bool__(self) -> bool:
1662         """Return True if the line has leaves or comments."""
1663         return bool(self.leaves or self.comments)
1664
1665
1666 @dataclass
1667 class EmptyLineTracker:
1668     """Provides a stateful method that returns the number of potential extra
1669     empty lines needed before and after the currently processed line.
1670
1671     Note: this tracker works on lines that haven't been split yet.  It assumes
1672     the prefix of the first leaf consists of optional newlines.  Those newlines
1673     are consumed by `maybe_empty_lines()` and included in the computation.
1674     """
1675
1676     is_pyi: bool = False
1677     previous_line: Optional[Line] = None
1678     previous_after: int = 0
1679     previous_defs: List[int] = field(default_factory=list)
1680
1681     def maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
1682         """Return the number of extra empty lines before and after the `current_line`.
1683
1684         This is for separating `def`, `async def` and `class` with extra empty
1685         lines (two on module-level).
1686         """
1687         before, after = self._maybe_empty_lines(current_line)
1688         before = (
1689             # Black should not insert empty lines at the beginning
1690             # of the file
1691             0
1692             if self.previous_line is None
1693             else before - self.previous_after
1694         )
1695         self.previous_after = after
1696         self.previous_line = current_line
1697         return before, after
1698
1699     def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
1700         max_allowed = 1
1701         if current_line.depth == 0:
1702             max_allowed = 1 if self.is_pyi else 2
1703         if current_line.leaves:
1704             # Consume the first leaf's extra newlines.
1705             first_leaf = current_line.leaves[0]
1706             before = first_leaf.prefix.count("\n")
1707             before = min(before, max_allowed)
1708             first_leaf.prefix = ""
1709         else:
1710             before = 0
1711         depth = current_line.depth
1712         while self.previous_defs and self.previous_defs[-1] >= depth:
1713             self.previous_defs.pop()
1714             if self.is_pyi:
1715                 before = 0 if depth else 1
1716             else:
1717                 before = 1 if depth else 2
1718         if current_line.is_decorator or current_line.is_def or current_line.is_class:
1719             return self._maybe_empty_lines_for_class_or_def(current_line, before)
1720
1721         if (
1722             self.previous_line
1723             and self.previous_line.is_import
1724             and not current_line.is_import
1725             and depth == self.previous_line.depth
1726         ):
1727             return (before or 1), 0
1728
1729         if (
1730             self.previous_line
1731             and self.previous_line.is_class
1732             and current_line.is_triple_quoted_string
1733         ):
1734             return before, 1
1735
1736         return before, 0
1737
1738     def _maybe_empty_lines_for_class_or_def(
1739         self, current_line: Line, before: int
1740     ) -> Tuple[int, int]:
1741         if not current_line.is_decorator:
1742             self.previous_defs.append(current_line.depth)
1743         if self.previous_line is None:
1744             # Don't insert empty lines before the first line in the file.
1745             return 0, 0
1746
1747         if self.previous_line.is_decorator:
1748             return 0, 0
1749
1750         if self.previous_line.depth < current_line.depth and (
1751             self.previous_line.is_class or self.previous_line.is_def
1752         ):
1753             return 0, 0
1754
1755         if (
1756             self.previous_line.is_comment
1757             and self.previous_line.depth == current_line.depth
1758             and before == 0
1759         ):
1760             return 0, 0
1761
1762         if self.is_pyi:
1763             if self.previous_line.depth > current_line.depth:
1764                 newlines = 1
1765             elif current_line.is_class or self.previous_line.is_class:
1766                 if current_line.is_stub_class and self.previous_line.is_stub_class:
1767                     # No blank line between classes with an empty body
1768                     newlines = 0
1769                 else:
1770                     newlines = 1
1771             elif current_line.is_def and not self.previous_line.is_def:
1772                 # Blank line between a block of functions and a block of non-functions
1773                 newlines = 1
1774             else:
1775                 newlines = 0
1776         else:
1777             newlines = 2
1778         if current_line.depth and newlines:
1779             newlines -= 1
1780         return newlines, 0
1781
1782
1783 @dataclass
1784 class LineGenerator(Visitor[Line]):
1785     """Generates reformatted Line objects.  Empty lines are not emitted.
1786
1787     Note: destroys the tree it's visiting by mutating prefixes of its leaves
1788     in ways that will no longer stringify to valid Python code on the tree.
1789     """
1790
1791     is_pyi: bool = False
1792     normalize_strings: bool = True
1793     current_line: Line = field(default_factory=Line)
1794     remove_u_prefix: bool = False
1795
1796     def line(self, indent: int = 0) -> Iterator[Line]:
1797         """Generate a line.
1798
1799         If the line is empty, only emit if it makes sense.
1800         If the line is too long, split it first and then generate.
1801
1802         If any lines were generated, set up a new current_line.
1803         """
1804         if not self.current_line:
1805             self.current_line.depth += indent
1806             return  # Line is empty, don't emit. Creating a new one unnecessary.
1807
1808         complete_line = self.current_line
1809         self.current_line = Line(depth=complete_line.depth + indent)
1810         yield complete_line
1811
1812     def visit_default(self, node: LN) -> Iterator[Line]:
1813         """Default `visit_*()` implementation. Recurses to children of `node`."""
1814         if isinstance(node, Leaf):
1815             any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
1816             for comment in generate_comments(node):
1817                 if any_open_brackets:
1818                     # any comment within brackets is subject to splitting
1819                     self.current_line.append(comment)
1820                 elif comment.type == token.COMMENT:
1821                     # regular trailing comment
1822                     self.current_line.append(comment)
1823                     yield from self.line()
1824
1825                 else:
1826                     # regular standalone comment
1827                     yield from self.line()
1828
1829                     self.current_line.append(comment)
1830                     yield from self.line()
1831
1832             normalize_prefix(node, inside_brackets=any_open_brackets)
1833             if self.normalize_strings and node.type == token.STRING:
1834                 normalize_string_prefix(node, remove_u_prefix=self.remove_u_prefix)
1835                 normalize_string_quotes(node)
1836             if node.type == token.NUMBER:
1837                 normalize_numeric_literal(node)
1838             if node.type not in WHITESPACE:
1839                 self.current_line.append(node)
1840         yield from super().visit_default(node)
1841
1842     def visit_INDENT(self, node: Leaf) -> Iterator[Line]:
1843         """Increase indentation level, maybe yield a line."""
1844         # In blib2to3 INDENT never holds comments.
1845         yield from self.line(+1)
1846         yield from self.visit_default(node)
1847
1848     def visit_DEDENT(self, node: Leaf) -> Iterator[Line]:
1849         """Decrease indentation level, maybe yield a line."""
1850         # The current line might still wait for trailing comments.  At DEDENT time
1851         # there won't be any (they would be prefixes on the preceding NEWLINE).
1852         # Emit the line then.
1853         yield from self.line()
1854
1855         # While DEDENT has no value, its prefix may contain standalone comments
1856         # that belong to the current indentation level.  Get 'em.
1857         yield from self.visit_default(node)
1858
1859         # Finally, emit the dedent.
1860         yield from self.line(-1)
1861
1862     def visit_stmt(
1863         self, node: Node, keywords: Set[str], parens: Set[str]
1864     ) -> Iterator[Line]:
1865         """Visit a statement.
1866
1867         This implementation is shared for `if`, `while`, `for`, `try`, `except`,
1868         `def`, `with`, `class`, `assert` and assignments.
1869
1870         The relevant Python language `keywords` for a given statement will be
1871         NAME leaves within it. This methods puts those on a separate line.
1872
1873         `parens` holds a set of string leaf values immediately after which
1874         invisible parens should be put.
1875         """
1876         normalize_invisible_parens(node, parens_after=parens)
1877         for child in node.children:
1878             if child.type == token.NAME and child.value in keywords:  # type: ignore
1879                 yield from self.line()
1880
1881             yield from self.visit(child)
1882
1883     def visit_suite(self, node: Node) -> Iterator[Line]:
1884         """Visit a suite."""
1885         if self.is_pyi and is_stub_suite(node):
1886             yield from self.visit(node.children[2])
1887         else:
1888             yield from self.visit_default(node)
1889
1890     def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
1891         """Visit a statement without nested statements."""
1892         is_suite_like = node.parent and node.parent.type in STATEMENT
1893         if is_suite_like:
1894             if self.is_pyi and is_stub_body(node):
1895                 yield from self.visit_default(node)
1896             else:
1897                 yield from self.line(+1)
1898                 yield from self.visit_default(node)
1899                 yield from self.line(-1)
1900
1901         else:
1902             if not self.is_pyi or not node.parent or not is_stub_suite(node.parent):
1903                 yield from self.line()
1904             yield from self.visit_default(node)
1905
1906     def visit_async_stmt(self, node: Node) -> Iterator[Line]:
1907         """Visit `async def`, `async for`, `async with`."""
1908         yield from self.line()
1909
1910         children = iter(node.children)
1911         for child in children:
1912             yield from self.visit(child)
1913
1914             if child.type == token.ASYNC:
1915                 break
1916
1917         internal_stmt = next(children)
1918         for child in internal_stmt.children:
1919             yield from self.visit(child)
1920
1921     def visit_decorators(self, node: Node) -> Iterator[Line]:
1922         """Visit decorators."""
1923         for child in node.children:
1924             yield from self.line()
1925             yield from self.visit(child)
1926
1927     def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
1928         """Remove a semicolon and put the other statement on a separate line."""
1929         yield from self.line()
1930
1931     def visit_ENDMARKER(self, leaf: Leaf) -> Iterator[Line]:
1932         """End of file. Process outstanding comments and end with a newline."""
1933         yield from self.visit_default(leaf)
1934         yield from self.line()
1935
1936     def visit_STANDALONE_COMMENT(self, leaf: Leaf) -> Iterator[Line]:
1937         if not self.current_line.bracket_tracker.any_open_brackets():
1938             yield from self.line()
1939         yield from self.visit_default(leaf)
1940
1941     def visit_factor(self, node: Node) -> Iterator[Line]:
1942         """Force parentheses between a unary op and a binary power:
1943
1944         -2 ** 8 -> -(2 ** 8)
1945         """
1946         _operator, operand = node.children
1947         if (
1948             operand.type == syms.power
1949             and len(operand.children) == 3
1950             and operand.children[1].type == token.DOUBLESTAR
1951         ):
1952             lpar = Leaf(token.LPAR, "(")
1953             rpar = Leaf(token.RPAR, ")")
1954             index = operand.remove() or 0
1955             node.insert_child(index, Node(syms.atom, [lpar, operand, rpar]))
1956         yield from self.visit_default(node)
1957
1958     def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
1959         # Check if it's a docstring
1960         if prev_siblings_are(
1961             leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
1962         ) and is_multiline_string(leaf):
1963             prefix = "    " * self.current_line.depth
1964             docstring = fix_docstring(leaf.value[3:-3], prefix)
1965             leaf.value = leaf.value[0:3] + docstring + leaf.value[-3:]
1966             normalize_string_quotes(leaf)
1967
1968         yield from self.visit_default(leaf)
1969
1970     def __post_init__(self) -> None:
1971         """You are in a twisty little maze of passages."""
1972         v = self.visit_stmt
1973         Ø: Set[str] = set()
1974         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
1975         self.visit_if_stmt = partial(
1976             v, keywords={"if", "else", "elif"}, parens={"if", "elif"}
1977         )
1978         self.visit_while_stmt = partial(v, keywords={"while", "else"}, parens={"while"})
1979         self.visit_for_stmt = partial(v, keywords={"for", "else"}, parens={"for", "in"})
1980         self.visit_try_stmt = partial(
1981             v, keywords={"try", "except", "else", "finally"}, parens=Ø
1982         )
1983         self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
1984         self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
1985         self.visit_funcdef = partial(v, keywords={"def"}, parens=Ø)
1986         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
1987         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
1988         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
1989         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
1990         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
1991         self.visit_async_funcdef = self.visit_async_stmt
1992         self.visit_decorated = self.visit_decorators
1993
1994
1995 IMPLICIT_TUPLE = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
1996 BRACKET = {token.LPAR: token.RPAR, token.LSQB: token.RSQB, token.LBRACE: token.RBRACE}
1997 OPENING_BRACKETS = set(BRACKET.keys())
1998 CLOSING_BRACKETS = set(BRACKET.values())
1999 BRACKETS = OPENING_BRACKETS | CLOSING_BRACKETS
2000 ALWAYS_NO_SPACE = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
2001
2002
2003 def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
2004     """Return whitespace prefix if needed for the given `leaf`.
2005
2006     `complex_subscript` signals whether the given leaf is part of a subscription
2007     which has non-trivial arguments, like arithmetic expressions or function calls.
2008     """
2009     NO = ""
2010     SPACE = " "
2011     DOUBLESPACE = "  "
2012     t = leaf.type
2013     p = leaf.parent
2014     v = leaf.value
2015     if t in ALWAYS_NO_SPACE:
2016         return NO
2017
2018     if t == token.COMMENT:
2019         return DOUBLESPACE
2020
2021     assert p is not None, f"INTERNAL ERROR: hand-made leaf without parent: {leaf!r}"
2022     if t == token.COLON and p.type not in {
2023         syms.subscript,
2024         syms.subscriptlist,
2025         syms.sliceop,
2026     }:
2027         return NO
2028
2029     prev = leaf.prev_sibling
2030     if not prev:
2031         prevp = preceding_leaf(p)
2032         if not prevp or prevp.type in OPENING_BRACKETS:
2033             return NO
2034
2035         if t == token.COLON:
2036             if prevp.type == token.COLON:
2037                 return NO
2038
2039             elif prevp.type != token.COMMA and not complex_subscript:
2040                 return NO
2041
2042             return SPACE
2043
2044         if prevp.type == token.EQUAL:
2045             if prevp.parent:
2046                 if prevp.parent.type in {
2047                     syms.arglist,
2048                     syms.argument,
2049                     syms.parameters,
2050                     syms.varargslist,
2051                 }:
2052                     return NO
2053
2054                 elif prevp.parent.type == syms.typedargslist:
2055                     # A bit hacky: if the equal sign has whitespace, it means we
2056                     # previously found it's a typed argument.  So, we're using
2057                     # that, too.
2058                     return prevp.prefix
2059
2060         elif prevp.type in VARARGS_SPECIALS:
2061             if is_vararg(prevp, within=VARARGS_PARENTS | UNPACKING_PARENTS):
2062                 return NO
2063
2064         elif prevp.type == token.COLON:
2065             if prevp.parent and prevp.parent.type in {syms.subscript, syms.sliceop}:
2066                 return SPACE if complex_subscript else NO
2067
2068         elif (
2069             prevp.parent
2070             and prevp.parent.type == syms.factor
2071             and prevp.type in MATH_OPERATORS
2072         ):
2073             return NO
2074
2075         elif (
2076             prevp.type == token.RIGHTSHIFT
2077             and prevp.parent
2078             and prevp.parent.type == syms.shift_expr
2079             and prevp.prev_sibling
2080             and prevp.prev_sibling.type == token.NAME
2081             and prevp.prev_sibling.value == "print"  # type: ignore
2082         ):
2083             # Python 2 print chevron
2084             return NO
2085
2086     elif prev.type in OPENING_BRACKETS:
2087         return NO
2088
2089     if p.type in {syms.parameters, syms.arglist}:
2090         # untyped function signatures or calls
2091         if not prev or prev.type != token.COMMA:
2092             return NO
2093
2094     elif p.type == syms.varargslist:
2095         # lambdas
2096         if prev and prev.type != token.COMMA:
2097             return NO
2098
2099     elif p.type == syms.typedargslist:
2100         # typed function signatures
2101         if not prev:
2102             return NO
2103
2104         if t == token.EQUAL:
2105             if prev.type != syms.tname:
2106                 return NO
2107
2108         elif prev.type == token.EQUAL:
2109             # A bit hacky: if the equal sign has whitespace, it means we
2110             # previously found it's a typed argument.  So, we're using that, too.
2111             return prev.prefix
2112
2113         elif prev.type != token.COMMA:
2114             return NO
2115
2116     elif p.type == syms.tname:
2117         # type names
2118         if not prev:
2119             prevp = preceding_leaf(p)
2120             if not prevp or prevp.type != token.COMMA:
2121                 return NO
2122
2123     elif p.type == syms.trailer:
2124         # attributes and calls
2125         if t == token.LPAR or t == token.RPAR:
2126             return NO
2127
2128         if not prev:
2129             if t == token.DOT:
2130                 prevp = preceding_leaf(p)
2131                 if not prevp or prevp.type != token.NUMBER:
2132                     return NO
2133
2134             elif t == token.LSQB:
2135                 return NO
2136
2137         elif prev.type != token.COMMA:
2138             return NO
2139
2140     elif p.type == syms.argument:
2141         # single argument
2142         if t == token.EQUAL:
2143             return NO
2144
2145         if not prev:
2146             prevp = preceding_leaf(p)
2147             if not prevp or prevp.type == token.LPAR:
2148                 return NO
2149
2150         elif prev.type in {token.EQUAL} | VARARGS_SPECIALS:
2151             return NO
2152
2153     elif p.type == syms.decorator:
2154         # decorators
2155         return NO
2156
2157     elif p.type == syms.dotted_name:
2158         if prev:
2159             return NO
2160
2161         prevp = preceding_leaf(p)
2162         if not prevp or prevp.type == token.AT or prevp.type == token.DOT:
2163             return NO
2164
2165     elif p.type == syms.classdef:
2166         if t == token.LPAR:
2167             return NO
2168
2169         if prev and prev.type == token.LPAR:
2170             return NO
2171
2172     elif p.type in {syms.subscript, syms.sliceop}:
2173         # indexing
2174         if not prev:
2175             assert p.parent is not None, "subscripts are always parented"
2176             if p.parent.type == syms.subscriptlist:
2177                 return SPACE
2178
2179             return NO
2180
2181         elif not complex_subscript:
2182             return NO
2183
2184     elif p.type == syms.atom:
2185         if prev and t == token.DOT:
2186             # dots, but not the first one.
2187             return NO
2188
2189     elif p.type == syms.dictsetmaker:
2190         # dict unpacking
2191         if prev and prev.type == token.DOUBLESTAR:
2192             return NO
2193
2194     elif p.type in {syms.factor, syms.star_expr}:
2195         # unary ops
2196         if not prev:
2197             prevp = preceding_leaf(p)
2198             if not prevp or prevp.type in OPENING_BRACKETS:
2199                 return NO
2200
2201             prevp_parent = prevp.parent
2202             assert prevp_parent is not None
2203             if prevp.type == token.COLON and prevp_parent.type in {
2204                 syms.subscript,
2205                 syms.sliceop,
2206             }:
2207                 return NO
2208
2209             elif prevp.type == token.EQUAL and prevp_parent.type == syms.argument:
2210                 return NO
2211
2212         elif t in {token.NAME, token.NUMBER, token.STRING}:
2213             return NO
2214
2215     elif p.type == syms.import_from:
2216         if t == token.DOT:
2217             if prev and prev.type == token.DOT:
2218                 return NO
2219
2220         elif t == token.NAME:
2221             if v == "import":
2222                 return SPACE
2223
2224             if prev and prev.type == token.DOT:
2225                 return NO
2226
2227     elif p.type == syms.sliceop:
2228         return NO
2229
2230     return SPACE
2231
2232
2233 def preceding_leaf(node: Optional[LN]) -> Optional[Leaf]:
2234     """Return the first leaf that precedes `node`, if any."""
2235     while node:
2236         res = node.prev_sibling
2237         if res:
2238             if isinstance(res, Leaf):
2239                 return res
2240
2241             try:
2242                 return list(res.leaves())[-1]
2243
2244             except IndexError:
2245                 return None
2246
2247         node = node.parent
2248     return None
2249
2250
2251 def prev_siblings_are(node: Optional[LN], tokens: List[Optional[NodeType]]) -> bool:
2252     """Return if the `node` and its previous siblings match types against the provided
2253     list of tokens; the provided `node`has its type matched against the last element in
2254     the list.  `None` can be used as the first element to declare that the start of the
2255     list is anchored at the start of its parent's children."""
2256     if not tokens:
2257         return True
2258     if tokens[-1] is None:
2259         return node is None
2260     if not node:
2261         return False
2262     if node.type != tokens[-1]:
2263         return False
2264     return prev_siblings_are(node.prev_sibling, tokens[:-1])
2265
2266
2267 def child_towards(ancestor: Node, descendant: LN) -> Optional[LN]:
2268     """Return the child of `ancestor` that contains `descendant`."""
2269     node: Optional[LN] = descendant
2270     while node and node.parent != ancestor:
2271         node = node.parent
2272     return node
2273
2274
2275 def container_of(leaf: Leaf) -> LN:
2276     """Return `leaf` or one of its ancestors that is the topmost container of it.
2277
2278     By "container" we mean a node where `leaf` is the very first child.
2279     """
2280     same_prefix = leaf.prefix
2281     container: LN = leaf
2282     while container:
2283         parent = container.parent
2284         if parent is None:
2285             break
2286
2287         if parent.children[0].prefix != same_prefix:
2288             break
2289
2290         if parent.type == syms.file_input:
2291             break
2292
2293         if parent.prev_sibling is not None and parent.prev_sibling.type in BRACKETS:
2294             break
2295
2296         container = parent
2297     return container
2298
2299
2300 def is_split_after_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
2301     """Return the priority of the `leaf` delimiter, given a line break after it.
2302
2303     The delimiter priorities returned here are from those delimiters that would
2304     cause a line break after themselves.
2305
2306     Higher numbers are higher priority.
2307     """
2308     if leaf.type == token.COMMA:
2309         return COMMA_PRIORITY
2310
2311     return 0
2312
2313
2314 def is_split_before_delimiter(leaf: Leaf, previous: Optional[Leaf] = None) -> Priority:
2315     """Return the priority of the `leaf` delimiter, given a line break before it.
2316
2317     The delimiter priorities returned here are from those delimiters that would
2318     cause a line break before themselves.
2319
2320     Higher numbers are higher priority.
2321     """
2322     if is_vararg(leaf, within=VARARGS_PARENTS | UNPACKING_PARENTS):
2323         # * and ** might also be MATH_OPERATORS but in this case they are not.
2324         # Don't treat them as a delimiter.
2325         return 0
2326
2327     if (
2328         leaf.type == token.DOT
2329         and leaf.parent
2330         and leaf.parent.type not in {syms.import_from, syms.dotted_name}
2331         and (previous is None or previous.type in CLOSING_BRACKETS)
2332     ):
2333         return DOT_PRIORITY
2334
2335     if (
2336         leaf.type in MATH_OPERATORS
2337         and leaf.parent
2338         and leaf.parent.type not in {syms.factor, syms.star_expr}
2339     ):
2340         return MATH_PRIORITIES[leaf.type]
2341
2342     if leaf.type in COMPARATORS:
2343         return COMPARATOR_PRIORITY
2344
2345     if (
2346         leaf.type == token.STRING
2347         and previous is not None
2348         and previous.type == token.STRING
2349     ):
2350         return STRING_PRIORITY
2351
2352     if leaf.type not in {token.NAME, token.ASYNC}:
2353         return 0
2354
2355     if (
2356         leaf.value == "for"
2357         and leaf.parent
2358         and leaf.parent.type in {syms.comp_for, syms.old_comp_for}
2359         or leaf.type == token.ASYNC
2360     ):
2361         if (
2362             not isinstance(leaf.prev_sibling, Leaf)
2363             or leaf.prev_sibling.value != "async"
2364         ):
2365             return COMPREHENSION_PRIORITY
2366
2367     if (
2368         leaf.value == "if"
2369         and leaf.parent
2370         and leaf.parent.type in {syms.comp_if, syms.old_comp_if}
2371     ):
2372         return COMPREHENSION_PRIORITY
2373
2374     if leaf.value in {"if", "else"} and leaf.parent and leaf.parent.type == syms.test:
2375         return TERNARY_PRIORITY
2376
2377     if leaf.value == "is":
2378         return COMPARATOR_PRIORITY
2379
2380     if (
2381         leaf.value == "in"
2382         and leaf.parent
2383         and leaf.parent.type in {syms.comp_op, syms.comparison}
2384         and not (
2385             previous is not None
2386             and previous.type == token.NAME
2387             and previous.value == "not"
2388         )
2389     ):
2390         return COMPARATOR_PRIORITY
2391
2392     if (
2393         leaf.value == "not"
2394         and leaf.parent
2395         and leaf.parent.type == syms.comp_op
2396         and not (
2397             previous is not None
2398             and previous.type == token.NAME
2399             and previous.value == "is"
2400         )
2401     ):
2402         return COMPARATOR_PRIORITY
2403
2404     if leaf.value in LOGIC_OPERATORS and leaf.parent:
2405         return LOGIC_PRIORITY
2406
2407     return 0
2408
2409
2410 FMT_OFF = {"# fmt: off", "# fmt:off", "# yapf: disable"}
2411 FMT_ON = {"# fmt: on", "# fmt:on", "# yapf: enable"}
2412
2413
2414 def generate_comments(leaf: LN) -> Iterator[Leaf]:
2415     """Clean the prefix of the `leaf` and generate comments from it, if any.
2416
2417     Comments in lib2to3 are shoved into the whitespace prefix.  This happens
2418     in `pgen2/driver.py:Driver.parse_tokens()`.  This was a brilliant implementation
2419     move because it does away with modifying the grammar to include all the
2420     possible places in which comments can be placed.
2421
2422     The sad consequence for us though is that comments don't "belong" anywhere.
2423     This is why this function generates simple parentless Leaf objects for
2424     comments.  We simply don't know what the correct parent should be.
2425
2426     No matter though, we can live without this.  We really only need to
2427     differentiate between inline and standalone comments.  The latter don't
2428     share the line with any code.
2429
2430     Inline comments are emitted as regular token.COMMENT leaves.  Standalone
2431     are emitted with a fake STANDALONE_COMMENT token identifier.
2432     """
2433     for pc in list_comments(leaf.prefix, is_endmarker=leaf.type == token.ENDMARKER):
2434         yield Leaf(pc.type, pc.value, prefix="\n" * pc.newlines)
2435
2436
2437 @dataclass
2438 class ProtoComment:
2439     """Describes a piece of syntax that is a comment.
2440
2441     It's not a :class:`blib2to3.pytree.Leaf` so that:
2442
2443     * it can be cached (`Leaf` objects should not be reused more than once as
2444       they store their lineno, column, prefix, and parent information);
2445     * `newlines` and `consumed` fields are kept separate from the `value`. This
2446       simplifies handling of special marker comments like ``# fmt: off/on``.
2447     """
2448
2449     type: int  # token.COMMENT or STANDALONE_COMMENT
2450     value: str  # content of the comment
2451     newlines: int  # how many newlines before the comment
2452     consumed: int  # how many characters of the original leaf's prefix did we consume
2453
2454
2455 @lru_cache(maxsize=4096)
2456 def list_comments(prefix: str, *, is_endmarker: bool) -> List[ProtoComment]:
2457     """Return a list of :class:`ProtoComment` objects parsed from the given `prefix`."""
2458     result: List[ProtoComment] = []
2459     if not prefix or "#" not in prefix:
2460         return result
2461
2462     consumed = 0
2463     nlines = 0
2464     ignored_lines = 0
2465     for index, line in enumerate(prefix.split("\n")):
2466         consumed += len(line) + 1  # adding the length of the split '\n'
2467         line = line.lstrip()
2468         if not line:
2469             nlines += 1
2470         if not line.startswith("#"):
2471             # Escaped newlines outside of a comment are not really newlines at
2472             # all. We treat a single-line comment following an escaped newline
2473             # as a simple trailing comment.
2474             if line.endswith("\\"):
2475                 ignored_lines += 1
2476             continue
2477
2478         if index == ignored_lines and not is_endmarker:
2479             comment_type = token.COMMENT  # simple trailing comment
2480         else:
2481             comment_type = STANDALONE_COMMENT
2482         comment = make_comment(line)
2483         result.append(
2484             ProtoComment(
2485                 type=comment_type, value=comment, newlines=nlines, consumed=consumed
2486             )
2487         )
2488         nlines = 0
2489     return result
2490
2491
2492 def make_comment(content: str) -> str:
2493     """Return a consistently formatted comment from the given `content` string.
2494
2495     All comments (except for "##", "#!", "#:", '#'", "#%%") should have a single
2496     space between the hash sign and the content.
2497
2498     If `content` didn't start with a hash sign, one is provided.
2499     """
2500     content = content.rstrip()
2501     if not content:
2502         return "#"
2503
2504     if content[0] == "#":
2505         content = content[1:]
2506     if content and content[0] not in " !:#'%":
2507         content = " " + content
2508     return "#" + content
2509
2510
2511 def transform_line(
2512     line: Line,
2513     line_length: int,
2514     normalize_strings: bool,
2515     features: Collection[Feature] = (),
2516 ) -> Iterator[Line]:
2517     """Transform a `line`, potentially splitting it into many lines.
2518
2519     They should fit in the allotted `line_length` but might not be able to.
2520
2521     `features` are syntactical features that may be used in the output.
2522     """
2523     if line.is_comment:
2524         yield line
2525         return
2526
2527     line_str = line_to_string(line)
2528
2529     def init_st(ST: Type[StringTransformer]) -> StringTransformer:
2530         """Initialize StringTransformer"""
2531         return ST(line_length, normalize_strings)
2532
2533     string_merge = init_st(StringMerger)
2534     string_paren_strip = init_st(StringParenStripper)
2535     string_split = init_st(StringSplitter)
2536     string_paren_wrap = init_st(StringParenWrapper)
2537
2538     transformers: List[Transformer]
2539     if (
2540         not line.contains_uncollapsable_type_comments()
2541         and not line.should_explode
2542         and not line.is_collection_with_optional_trailing_comma
2543         and (
2544             is_line_short_enough(line, line_length=line_length, line_str=line_str)
2545             or line.contains_unsplittable_type_ignore()
2546         )
2547     ):
2548         # Only apply basic string preprocessing, since lines shouldn't be split here.
2549         transformers = [string_merge, string_paren_strip]
2550     elif line.is_def:
2551         transformers = [left_hand_split]
2552     else:
2553
2554         def rhs(line: Line, features: Collection[Feature]) -> Iterator[Line]:
2555             for omit in generate_trailers_to_omit(line, line_length):
2556                 lines = list(right_hand_split(line, line_length, features, omit=omit))
2557                 if is_line_short_enough(lines[0], line_length=line_length):
2558                     yield from lines
2559                     return
2560
2561             # All splits failed, best effort split with no omits.
2562             # This mostly happens to multiline strings that are by definition
2563             # reported as not fitting a single line.
2564             # line_length=1 here was historically a bug that somehow became a feature.
2565             # See #762 and #781 for the full story.
2566             yield from right_hand_split(line, line_length=1, features=features)
2567
2568         if line.inside_brackets:
2569             transformers = [
2570                 string_merge,
2571                 string_paren_strip,
2572                 delimiter_split,
2573                 standalone_comment_split,
2574                 string_split,
2575                 string_paren_wrap,
2576                 rhs,
2577             ]
2578         else:
2579             transformers = [
2580                 string_merge,
2581                 string_paren_strip,
2582                 string_split,
2583                 string_paren_wrap,
2584                 rhs,
2585             ]
2586
2587     for transform in transformers:
2588         # We are accumulating lines in `result` because we might want to abort
2589         # mission and return the original line in the end, or attempt a different
2590         # split altogether.
2591         result: List[Line] = []
2592         try:
2593             for l in transform(line, features):
2594                 if str(l).strip("\n") == line_str:
2595                     raise CannotTransform(
2596                         "Line transformer returned an unchanged result"
2597                     )
2598
2599                 result.extend(
2600                     transform_line(
2601                         l,
2602                         line_length=line_length,
2603                         normalize_strings=normalize_strings,
2604                         features=features,
2605                     )
2606                 )
2607         except CannotTransform:
2608             continue
2609         else:
2610             yield from result
2611             break
2612
2613     else:
2614         yield line
2615
2616
2617 @dataclass  # type: ignore
2618 class StringTransformer(ABC):
2619     """
2620     An implementation of the Transformer protocol that relies on its
2621     subclasses overriding the template methods `do_match(...)` and
2622     `do_transform(...)`.
2623
2624     This Transformer works exclusively on strings (for example, by merging
2625     or splitting them).
2626
2627     The following sections can be found among the docstrings of each concrete
2628     StringTransformer subclass.
2629
2630     Requirements:
2631         Which requirements must be met of the given Line for this
2632         StringTransformer to be applied?
2633
2634     Transformations:
2635         If the given Line meets all of the above requirments, which string
2636         transformations can you expect to be applied to it by this
2637         StringTransformer?
2638
2639     Collaborations:
2640         What contractual agreements does this StringTransformer have with other
2641         StringTransfomers? Such collaborations should be eliminated/minimized
2642         as much as possible.
2643     """
2644
2645     line_length: int
2646     normalize_strings: bool
2647
2648     @abstractmethod
2649     def do_match(self, line: Line) -> TMatchResult:
2650         """
2651         Returns:
2652             * Ok(string_idx) such that `line.leaves[string_idx]` is our target
2653             string, if a match was able to be made.
2654                 OR
2655             * Err(CannotTransform), if a match was not able to be made.
2656         """
2657
2658     @abstractmethod
2659     def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
2660         """
2661         Yields:
2662             * Ok(new_line) where new_line is the new transformed line.
2663                 OR
2664             * Err(CannotTransform) if the transformation failed for some reason. The
2665             `do_match(...)` template method should usually be used to reject
2666             the form of the given Line, but in some cases it is difficult to
2667             know whether or not a Line meets the StringTransformer's
2668             requirements until the transformation is already midway.
2669
2670         Side Effects:
2671             This method should NOT mutate @line directly, but it MAY mutate the
2672             Line's underlying Node structure. (WARNING: If the underlying Node
2673             structure IS altered, then this method should NOT be allowed to
2674             yield an CannotTransform after that point.)
2675         """
2676
2677     def __call__(self, line: Line, _features: Collection[Feature]) -> Iterator[Line]:
2678         """
2679         StringTransformer instances have a call signature that mirrors that of
2680         the Transformer type.
2681
2682         Raises:
2683             CannotTransform(...) if the concrete StringTransformer class is unable
2684             to transform @line.
2685         """
2686         # Optimization to avoid calling `self.do_match(...)` when the line does
2687         # not contain any string.
2688         if not any(leaf.type == token.STRING for leaf in line.leaves):
2689             raise CannotTransform("There are no strings in this line.")
2690
2691         match_result = self.do_match(line)
2692
2693         if isinstance(match_result, Err):
2694             cant_transform = match_result.err()
2695             raise CannotTransform(
2696                 f"The string transformer {self.__class__.__name__} does not recognize"
2697                 " this line as one that it can transform."
2698             ) from cant_transform
2699
2700         string_idx = match_result.ok()
2701
2702         for line_result in self.do_transform(line, string_idx):
2703             if isinstance(line_result, Err):
2704                 cant_transform = line_result.err()
2705                 raise CannotTransform(
2706                     "StringTransformer failed while attempting to transform string."
2707                 ) from cant_transform
2708             line = line_result.ok()
2709             yield line
2710
2711
2712 @dataclass
2713 class CustomSplit:
2714     """A custom (i.e. manual) string split.
2715
2716     A single CustomSplit instance represents a single substring.
2717
2718     Examples:
2719         Consider the following string:
2720         ```
2721         "Hi there friend."
2722         " This is a custom"
2723         f" string {split}."
2724         ```
2725
2726         This string will correspond to the following three CustomSplit instances:
2727         ```
2728         CustomSplit(False, 16)
2729         CustomSplit(False, 17)
2730         CustomSplit(True, 16)
2731         ```
2732     """
2733
2734     has_prefix: bool
2735     break_idx: int
2736
2737
2738 class CustomSplitMapMixin:
2739     """
2740     This mixin class is used to map merged strings to a sequence of
2741     CustomSplits, which will then be used to re-split the strings iff none of
2742     the resultant substrings go over the configured max line length.
2743     """
2744
2745     _Key = Tuple[StringID, str]
2746     _CUSTOM_SPLIT_MAP: Dict[_Key, Tuple[CustomSplit, ...]] = defaultdict(tuple)
2747
2748     @staticmethod
2749     def _get_key(string: str) -> "CustomSplitMapMixin._Key":
2750         """
2751         Returns:
2752             A unique identifier that is used internally to map @string to a
2753             group of custom splits.
2754         """
2755         return (id(string), string)
2756
2757     def add_custom_splits(
2758         self, string: str, custom_splits: Iterable[CustomSplit]
2759     ) -> None:
2760         """Custom Split Map Setter Method
2761
2762         Side Effects:
2763             Adds a mapping from @string to the custom splits @custom_splits.
2764         """
2765         key = self._get_key(string)
2766         self._CUSTOM_SPLIT_MAP[key] = tuple(custom_splits)
2767
2768     def pop_custom_splits(self, string: str) -> List[CustomSplit]:
2769         """Custom Split Map Getter Method
2770
2771         Returns:
2772             * A list of the custom splits that are mapped to @string, if any
2773             exist.
2774                 OR
2775             * [], otherwise.
2776
2777         Side Effects:
2778             Deletes the mapping between @string and its associated custom
2779             splits (which are returned to the caller).
2780         """
2781         key = self._get_key(string)
2782
2783         custom_splits = self._CUSTOM_SPLIT_MAP[key]
2784         del self._CUSTOM_SPLIT_MAP[key]
2785
2786         return list(custom_splits)
2787
2788     def has_custom_splits(self, string: str) -> bool:
2789         """
2790         Returns:
2791             True iff @string is associated with a set of custom splits.
2792         """
2793         key = self._get_key(string)
2794         return key in self._CUSTOM_SPLIT_MAP
2795
2796
2797 class StringMerger(CustomSplitMapMixin, StringTransformer):
2798     """StringTransformer that merges strings together.
2799
2800     Requirements:
2801         (A) The line contains adjacent strings such that at most one substring
2802         has inline comments AND none of those inline comments are pragmas AND
2803         the set of all substring prefixes is either of length 1 or equal to
2804         {"", "f"} AND none of the substrings are raw strings (i.e. are prefixed
2805         with 'r').
2806             OR
2807         (B) The line contains a string which uses line continuation backslashes.
2808
2809     Transformations:
2810         Depending on which of the two requirements above where met, either:
2811
2812         (A) The string group associated with the target string is merged.
2813             OR
2814         (B) All line-continuation backslashes are removed from the target string.
2815
2816     Collaborations:
2817         StringMerger provides custom split information to StringSplitter.
2818     """
2819
2820     def do_match(self, line: Line) -> TMatchResult:
2821         LL = line.leaves
2822
2823         is_valid_index = is_valid_index_factory(LL)
2824
2825         for (i, leaf) in enumerate(LL):
2826             if (
2827                 leaf.type == token.STRING
2828                 and is_valid_index(i + 1)
2829                 and LL[i + 1].type == token.STRING
2830             ):
2831                 return Ok(i)
2832
2833             if leaf.type == token.STRING and "\\\n" in leaf.value:
2834                 return Ok(i)
2835
2836         return TErr("This line has no strings that need merging.")
2837
2838     def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
2839         new_line = line
2840         rblc_result = self.__remove_backslash_line_continuation_chars(
2841             new_line, string_idx
2842         )
2843         if isinstance(rblc_result, Ok):
2844             new_line = rblc_result.ok()
2845
2846         msg_result = self.__merge_string_group(new_line, string_idx)
2847         if isinstance(msg_result, Ok):
2848             new_line = msg_result.ok()
2849
2850         if isinstance(rblc_result, Err) and isinstance(msg_result, Err):
2851             msg_cant_transform = msg_result.err()
2852             rblc_cant_transform = rblc_result.err()
2853             cant_transform = CannotTransform(
2854                 "StringMerger failed to merge any strings in this line."
2855             )
2856
2857             # Chain the errors together using `__cause__`.
2858             msg_cant_transform.__cause__ = rblc_cant_transform
2859             cant_transform.__cause__ = msg_cant_transform
2860
2861             yield Err(cant_transform)
2862         else:
2863             yield Ok(new_line)
2864
2865     @staticmethod
2866     def __remove_backslash_line_continuation_chars(
2867         line: Line, string_idx: int
2868     ) -> TResult[Line]:
2869         """
2870         Merge strings that were split across multiple lines using
2871         line-continuation backslashes.
2872
2873         Returns:
2874             Ok(new_line), if @line contains backslash line-continuation
2875             characters.
2876                 OR
2877             Err(CannotTransform), otherwise.
2878         """
2879         LL = line.leaves
2880
2881         string_leaf = LL[string_idx]
2882         if not (
2883             string_leaf.type == token.STRING
2884             and "\\\n" in string_leaf.value
2885             and not has_triple_quotes(string_leaf.value)
2886         ):
2887             return TErr(
2888                 f"String leaf {string_leaf} does not contain any backslash line"
2889                 " continuation characters."
2890             )
2891
2892         new_line = line.clone()
2893         new_line.comments = line.comments
2894         append_leaves(new_line, line, LL)
2895
2896         new_string_leaf = new_line.leaves[string_idx]
2897         new_string_leaf.value = new_string_leaf.value.replace("\\\n", "")
2898
2899         return Ok(new_line)
2900
2901     def __merge_string_group(self, line: Line, string_idx: int) -> TResult[Line]:
2902         """
2903         Merges string group (i.e. set of adjacent strings) where the first
2904         string in the group is `line.leaves[string_idx]`.
2905
2906         Returns:
2907             Ok(new_line), if ALL of the validation checks found in
2908             __validate_msg(...) pass.
2909                 OR
2910             Err(CannotTransform), otherwise.
2911         """
2912         LL = line.leaves
2913
2914         is_valid_index = is_valid_index_factory(LL)
2915
2916         vresult = self.__validate_msg(line, string_idx)
2917         if isinstance(vresult, Err):
2918             return vresult
2919
2920         # If the string group is wrapped inside an Atom node, we must make sure
2921         # to later replace that Atom with our new (merged) string leaf.
2922         atom_node = LL[string_idx].parent
2923
2924         # We will place BREAK_MARK in between every two substrings that we
2925         # merge. We will then later go through our final result and use the
2926         # various instances of BREAK_MARK we find to add the right values to
2927         # the custom split map.
2928         BREAK_MARK = "@@@@@ BLACK BREAKPOINT MARKER @@@@@"
2929
2930         QUOTE = LL[string_idx].value[-1]
2931
2932         def make_naked(string: str, string_prefix: str) -> str:
2933             """Strip @string (i.e. make it a "naked" string)
2934
2935             Pre-conditions:
2936                 * assert_is_leaf_string(@string)
2937
2938             Returns:
2939                 A string that is identical to @string except that
2940                 @string_prefix has been stripped, the surrounding QUOTE
2941                 characters have been removed, and any remaining QUOTE
2942                 characters have been escaped.
2943             """
2944             assert_is_leaf_string(string)
2945
2946             RE_EVEN_BACKSLASHES = r"(?:(?<!\\)(?:\\\\)*)"
2947             naked_string = string[len(string_prefix) + 1 : -1]
2948             naked_string = re.sub(
2949                 "(" + RE_EVEN_BACKSLASHES + ")" + QUOTE, r"\1\\" + QUOTE, naked_string
2950             )
2951             return naked_string
2952
2953         # Holds the CustomSplit objects that will later be added to the custom
2954         # split map.
2955         custom_splits = []
2956
2957         # Temporary storage for the 'has_prefix' part of the CustomSplit objects.
2958         prefix_tracker = []
2959
2960         # Sets the 'prefix' variable. This is the prefix that the final merged
2961         # string will have.
2962         next_str_idx = string_idx
2963         prefix = ""
2964         while (
2965             not prefix
2966             and is_valid_index(next_str_idx)
2967             and LL[next_str_idx].type == token.STRING
2968         ):
2969             prefix = get_string_prefix(LL[next_str_idx].value)
2970             next_str_idx += 1
2971
2972         # The next loop merges the string group. The final string will be
2973         # contained in 'S'.
2974         #
2975         # The following convenience variables are used:
2976         #
2977         #   S: string
2978         #   NS: naked string
2979         #   SS: next string
2980         #   NSS: naked next string
2981         S = ""
2982         NS = ""
2983         num_of_strings = 0
2984         next_str_idx = string_idx
2985         while is_valid_index(next_str_idx) and LL[next_str_idx].type == token.STRING:
2986             num_of_strings += 1
2987
2988             SS = LL[next_str_idx].value
2989             next_prefix = get_string_prefix(SS)
2990
2991             # If this is an f-string group but this substring is not prefixed
2992             # with 'f'...
2993             if "f" in prefix and "f" not in next_prefix:
2994                 # Then we must escape any braces contained in this substring.
2995                 SS = re.subf(r"(\{|\})", "{1}{1}", SS)
2996
2997             NSS = make_naked(SS, next_prefix)
2998
2999             has_prefix = bool(next_prefix)
3000             prefix_tracker.append(has_prefix)
3001
3002             S = prefix + QUOTE + NS + NSS + BREAK_MARK + QUOTE
3003             NS = make_naked(S, prefix)
3004
3005             next_str_idx += 1
3006
3007         S_leaf = Leaf(token.STRING, S)
3008         if self.normalize_strings:
3009             normalize_string_quotes(S_leaf)
3010
3011         # Fill the 'custom_splits' list with the appropriate CustomSplit objects.
3012         temp_string = S_leaf.value[len(prefix) + 1 : -1]
3013         for has_prefix in prefix_tracker:
3014             mark_idx = temp_string.find(BREAK_MARK)
3015             assert (
3016                 mark_idx >= 0
3017             ), "Logic error while filling the custom string breakpoint cache."
3018
3019             temp_string = temp_string[mark_idx + len(BREAK_MARK) :]
3020             breakpoint_idx = mark_idx + (len(prefix) if has_prefix else 0) + 1
3021             custom_splits.append(CustomSplit(has_prefix, breakpoint_idx))
3022
3023         string_leaf = Leaf(token.STRING, S_leaf.value.replace(BREAK_MARK, ""))
3024
3025         if atom_node is not None:
3026             replace_child(atom_node, string_leaf)
3027
3028         # Build the final line ('new_line') that this method will later return.
3029         new_line = line.clone()
3030         for (i, leaf) in enumerate(LL):
3031             if i == string_idx:
3032                 new_line.append(string_leaf)
3033
3034             if string_idx <= i < string_idx + num_of_strings:
3035                 for comment_leaf in line.comments_after(LL[i]):
3036                     new_line.append(comment_leaf, preformatted=True)
3037                 continue
3038
3039             append_leaves(new_line, line, [leaf])
3040
3041         self.add_custom_splits(string_leaf.value, custom_splits)
3042         return Ok(new_line)
3043
3044     @staticmethod
3045     def __validate_msg(line: Line, string_idx: int) -> TResult[None]:
3046         """Validate (M)erge (S)tring (G)roup
3047
3048         Transform-time string validation logic for __merge_string_group(...).
3049
3050         Returns:
3051             * Ok(None), if ALL validation checks (listed below) pass.
3052                 OR
3053             * Err(CannotTransform), if any of the following are true:
3054                 - The target string is not in a string group (i.e. it has no
3055                   adjacent strings).
3056                 - The string group has more than one inline comment.
3057                 - The string group has an inline comment that appears to be a pragma.
3058                 - The set of all string prefixes in the string group is of
3059                   length greater than one and is not equal to {"", "f"}.
3060                 - The string group consists of raw strings.
3061         """
3062         num_of_inline_string_comments = 0
3063         set_of_prefixes = set()
3064         num_of_strings = 0
3065         for leaf in line.leaves[string_idx:]:
3066             if leaf.type != token.STRING:
3067                 # If the string group is trailed by a comma, we count the
3068                 # comments trailing the comma to be one of the string group's
3069                 # comments.
3070                 if leaf.type == token.COMMA and id(leaf) in line.comments:
3071                     num_of_inline_string_comments += 1
3072                 break
3073
3074             if has_triple_quotes(leaf.value):
3075                 return TErr("StringMerger does NOT merge multiline strings.")
3076
3077             num_of_strings += 1
3078             prefix = get_string_prefix(leaf.value)
3079             if "r" in prefix:
3080                 return TErr("StringMerger does NOT merge raw strings.")
3081
3082             set_of_prefixes.add(prefix)
3083
3084             if id(leaf) in line.comments:
3085                 num_of_inline_string_comments += 1
3086                 if contains_pragma_comment(line.comments[id(leaf)]):
3087                     return TErr("Cannot merge strings which have pragma comments.")
3088
3089         if num_of_strings < 2:
3090             return TErr(
3091                 f"Not enough strings to merge (num_of_strings={num_of_strings})."
3092             )
3093
3094         if num_of_inline_string_comments > 1:
3095             return TErr(
3096                 f"Too many inline string comments ({num_of_inline_string_comments})."
3097             )
3098
3099         if len(set_of_prefixes) > 1 and set_of_prefixes != {"", "f"}:
3100             return TErr(f"Too many different prefixes ({set_of_prefixes}).")
3101
3102         return Ok(None)
3103
3104
3105 class StringParenStripper(StringTransformer):
3106     """StringTransformer that strips surrounding parentheses from strings.
3107
3108     Requirements:
3109         The line contains a string which is surrounded by parentheses and:
3110             - The target string is NOT the only argument to a function call).
3111             - The RPAR is NOT followed by an attribute access (i.e. a dot).
3112
3113     Transformations:
3114         The parentheses mentioned in the 'Requirements' section are stripped.
3115
3116     Collaborations:
3117         StringParenStripper has its own inherent usefulness, but it is also
3118         relied on to clean up the parentheses created by StringParenWrapper (in
3119         the event that they are no longer needed).
3120     """
3121
3122     def do_match(self, line: Line) -> TMatchResult:
3123         LL = line.leaves
3124
3125         is_valid_index = is_valid_index_factory(LL)
3126
3127         for (idx, leaf) in enumerate(LL):
3128             # Should be a string...
3129             if leaf.type != token.STRING:
3130                 continue
3131
3132             # Should be preceded by a non-empty LPAR...
3133             if (
3134                 not is_valid_index(idx - 1)
3135                 or LL[idx - 1].type != token.LPAR
3136                 or is_empty_lpar(LL[idx - 1])
3137             ):
3138                 continue
3139
3140             # That LPAR should NOT be preceded by a function name or a closing
3141             # bracket (which could be a function which returns a function or a
3142             # list/dictionary that contains a function)...
3143             if is_valid_index(idx - 2) and (
3144                 LL[idx - 2].type == token.NAME or LL[idx - 2].type in CLOSING_BRACKETS
3145             ):
3146                 continue
3147
3148             string_idx = idx
3149
3150             # Skip the string trailer, if one exists.
3151             string_parser = StringParser()
3152             next_idx = string_parser.parse(LL, string_idx)
3153
3154             # Should be followed by a non-empty RPAR...
3155             if (
3156                 is_valid_index(next_idx)
3157                 and LL[next_idx].type == token.RPAR
3158                 and not is_empty_rpar(LL[next_idx])
3159             ):
3160                 # That RPAR should NOT be followed by a '.' symbol.
3161                 if is_valid_index(next_idx + 1) and LL[next_idx + 1].type == token.DOT:
3162                     continue
3163
3164                 return Ok(string_idx)
3165
3166         return TErr("This line has no strings wrapped in parens.")
3167
3168     def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
3169         LL = line.leaves
3170
3171         string_parser = StringParser()
3172         rpar_idx = string_parser.parse(LL, string_idx)
3173
3174         for leaf in (LL[string_idx - 1], LL[rpar_idx]):
3175             if line.comments_after(leaf):
3176                 yield TErr(
3177                     "Will not strip parentheses which have comments attached to them."
3178                 )
3179
3180         new_line = line.clone()
3181         new_line.comments = line.comments.copy()
3182
3183         append_leaves(new_line, line, LL[: string_idx - 1])
3184
3185         string_leaf = Leaf(token.STRING, LL[string_idx].value)
3186         LL[string_idx - 1].remove()
3187         replace_child(LL[string_idx], string_leaf)
3188         new_line.append(string_leaf)
3189
3190         append_leaves(
3191             new_line, line, LL[string_idx + 1 : rpar_idx] + LL[rpar_idx + 1 :],
3192         )
3193
3194         LL[rpar_idx].remove()
3195
3196         yield Ok(new_line)
3197
3198
3199 class BaseStringSplitter(StringTransformer):
3200     """
3201     Abstract class for StringTransformers which transform a Line's strings by splitting
3202     them or placing them on their own lines where necessary to avoid going over
3203     the configured line length.
3204
3205     Requirements:
3206         * The target string value is responsible for the line going over the
3207         line length limit. It follows that after all of black's other line
3208         split methods have been exhausted, this line (or one of the resulting
3209         lines after all line splits are performed) would still be over the
3210         line_length limit unless we split this string.
3211             AND
3212         * The target string is NOT a "pointless" string (i.e. a string that has
3213         no parent or siblings).
3214             AND
3215         * The target string is not followed by an inline comment that appears
3216         to be a pragma.
3217             AND
3218         * The target string is not a multiline (i.e. triple-quote) string.
3219     """
3220
3221     @abstractmethod
3222     def do_splitter_match(self, line: Line) -> TMatchResult:
3223         """
3224         BaseStringSplitter asks its clients to override this method instead of
3225         `StringTransformer.do_match(...)`.
3226
3227         Follows the same protocol as `StringTransformer.do_match(...)`.
3228
3229         Refer to `help(StringTransformer.do_match)` for more information.
3230         """
3231
3232     def do_match(self, line: Line) -> TMatchResult:
3233         match_result = self.do_splitter_match(line)
3234         if isinstance(match_result, Err):
3235             return match_result
3236
3237         string_idx = match_result.ok()
3238         vresult = self.__validate(line, string_idx)
3239         if isinstance(vresult, Err):
3240             return vresult
3241
3242         return match_result
3243
3244     def __validate(self, line: Line, string_idx: int) -> TResult[None]:
3245         """
3246         Checks that @line meets all of the requirements listed in this classes'
3247         docstring. Refer to `help(BaseStringSplitter)` for a detailed
3248         description of those requirements.
3249
3250         Returns:
3251             * Ok(None), if ALL of the requirements are met.
3252                 OR
3253             * Err(CannotTransform), if ANY of the requirements are NOT met.
3254         """
3255         LL = line.leaves
3256
3257         string_leaf = LL[string_idx]
3258
3259         max_string_length = self.__get_max_string_length(line, string_idx)
3260         if len(string_leaf.value) <= max_string_length:
3261             return TErr(
3262                 "The string itself is not what is causing this line to be too long."
3263             )
3264
3265         if not string_leaf.parent or [L.type for L in string_leaf.parent.children] == [
3266             token.STRING,
3267             token.NEWLINE,
3268         ]:
3269             return TErr(
3270                 f"This string ({string_leaf.value}) appears to be pointless (i.e. has"
3271                 " no parent)."
3272             )
3273
3274         if id(line.leaves[string_idx]) in line.comments and contains_pragma_comment(
3275             line.comments[id(line.leaves[string_idx])]
3276         ):
3277             return TErr(
3278                 "Line appears to end with an inline pragma comment. Splitting the line"
3279                 " could modify the pragma's behavior."
3280             )
3281
3282         if has_triple_quotes(string_leaf.value):
3283             return TErr("We cannot split multiline strings.")
3284
3285         return Ok(None)
3286
3287     def __get_max_string_length(self, line: Line, string_idx: int) -> int:
3288         """
3289         Calculates the max string length used when attempting to determine
3290         whether or not the target string is responsible for causing the line to
3291         go over the line length limit.
3292
3293         WARNING: This method is tightly coupled to both StringSplitter and
3294         (especially) StringParenWrapper. There is probably a better way to
3295         accomplish what is being done here.
3296
3297         Returns:
3298             max_string_length: such that `line.leaves[string_idx].value >
3299             max_string_length` implies that the target string IS responsible
3300             for causing this line to exceed the line length limit.
3301         """
3302         LL = line.leaves
3303
3304         is_valid_index = is_valid_index_factory(LL)
3305
3306         # We use the shorthand "WMA4" in comments to abbreviate "We must
3307         # account for". When giving examples, we use STRING to mean some/any
3308         # valid string.
3309         #
3310         # Finally, we use the following convenience variables:
3311         #
3312         #   P:  The leaf that is before the target string leaf.
3313         #   N:  The leaf that is after the target string leaf.
3314         #   NN: The leaf that is after N.
3315
3316         # WMA4 the whitespace at the beginning of the line.
3317         offset = line.depth * 4
3318
3319         if is_valid_index(string_idx - 1):
3320             p_idx = string_idx - 1
3321             if (
3322                 LL[string_idx - 1].type == token.LPAR
3323                 and LL[string_idx - 1].value == ""
3324                 and string_idx >= 2
3325             ):
3326                 # If the previous leaf is an empty LPAR placeholder, we should skip it.
3327                 p_idx -= 1
3328
3329             P = LL[p_idx]
3330             if P.type == token.PLUS:
3331                 # WMA4 a space and a '+' character (e.g. `+ STRING`).
3332                 offset += 2
3333
3334             if P.type == token.COMMA:
3335                 # WMA4 a space, a comma, and a closing bracket [e.g. `), STRING`].
3336                 offset += 3
3337
3338             if P.type in [token.COLON, token.EQUAL, token.NAME]:
3339                 # This conditional branch is meant to handle dictionary keys,
3340                 # variable assignments, 'return STRING' statement lines, and
3341                 # 'else STRING' ternary expression lines.
3342
3343                 # WMA4 a single space.
3344                 offset += 1
3345
3346                 # WMA4 the lengths of any leaves that came before that space.
3347                 for leaf in LL[: p_idx + 1]:
3348                     offset += len(str(leaf))
3349
3350         if is_valid_index(string_idx + 1):
3351             N = LL[string_idx + 1]
3352             if N.type == token.RPAR and N.value == "" and len(LL) > string_idx + 2:
3353                 # If the next leaf is an empty RPAR placeholder, we should skip it.
3354                 N = LL[string_idx + 2]
3355
3356             if N.type == token.COMMA:
3357                 # WMA4 a single comma at the end of the string (e.g `STRING,`).
3358                 offset += 1
3359
3360             if is_valid_index(string_idx + 2):
3361                 NN = LL[string_idx + 2]
3362
3363                 if N.type == token.DOT and NN.type == token.NAME:
3364                     # This conditional branch is meant to handle method calls invoked
3365                     # off of a string literal up to and including the LPAR character.
3366
3367                     # WMA4 the '.' character.
3368                     offset += 1
3369
3370                     if (
3371                         is_valid_index(string_idx + 3)
3372                         and LL[string_idx + 3].type == token.LPAR
3373                     ):
3374                         # WMA4 the left parenthesis character.
3375                         offset += 1
3376
3377                     # WMA4 the length of the method's name.
3378                     offset += len(NN.value)
3379
3380         has_comments = False
3381         for comment_leaf in line.comments_after(LL[string_idx]):
3382             if not has_comments:
3383                 has_comments = True
3384                 # WMA4 two spaces before the '#' character.
3385                 offset += 2
3386
3387             # WMA4 the length of the inline comment.
3388             offset += len(comment_leaf.value)
3389
3390         max_string_length = self.line_length - offset
3391         return max_string_length
3392
3393
3394 class StringSplitter(CustomSplitMapMixin, BaseStringSplitter):
3395     """
3396     StringTransformer that splits "atom" strings (i.e. strings which exist on
3397     lines by themselves).
3398
3399     Requirements:
3400         * The line consists ONLY of a single string (with the exception of a
3401         '+' symbol which MAY exist at the start of the line), MAYBE a string
3402         trailer, and MAYBE a trailing comma.
3403             AND
3404         * All of the requirements listed in BaseStringSplitter's docstring.
3405
3406     Transformations:
3407         The string mentioned in the 'Requirements' section is split into as
3408         many substrings as necessary to adhere to the configured line length.
3409
3410         In the final set of substrings, no substring should be smaller than
3411         MIN_SUBSTR_SIZE characters.
3412
3413         The string will ONLY be split on spaces (i.e. each new substring should
3414         start with a space).
3415
3416         If the string is an f-string, it will NOT be split in the middle of an
3417         f-expression (e.g. in f"FooBar: {foo() if x else bar()}", {foo() if x
3418         else bar()} is an f-expression).
3419
3420         If the string that is being split has an associated set of custom split
3421         records and those custom splits will NOT result in any line going over
3422         the configured line length, those custom splits are used. Otherwise the
3423         string is split as late as possible (from left-to-right) while still
3424         adhering to the transformation rules listed above.
3425
3426     Collaborations:
3427         StringSplitter relies on StringMerger to construct the appropriate
3428         CustomSplit objects and add them to the custom split map.
3429     """
3430
3431     MIN_SUBSTR_SIZE = 6
3432     # Matches an "f-expression" (e.g. {var}) that might be found in an f-string.
3433     RE_FEXPR = r"""
3434     (?<!\{)\{
3435         (?:
3436             [^\{\}]
3437             | \{\{
3438             | \}\}
3439         )+?
3440     (?<!\})(?:\}\})*\}(?!\})
3441     """
3442
3443     def do_splitter_match(self, line: Line) -> TMatchResult:
3444         LL = line.leaves
3445
3446         is_valid_index = is_valid_index_factory(LL)
3447
3448         idx = 0
3449
3450         # The first leaf MAY be a '+' symbol...
3451         if is_valid_index(idx) and LL[idx].type == token.PLUS:
3452             idx += 1
3453
3454         # The next/first leaf MAY be an empty LPAR...
3455         if is_valid_index(idx) and is_empty_lpar(LL[idx]):
3456             idx += 1
3457
3458         # The next/first leaf MUST be a string...
3459         if not is_valid_index(idx) or LL[idx].type != token.STRING:
3460             return TErr("Line does not start with a string.")
3461
3462         string_idx = idx
3463
3464         # Skip the string trailer, if one exists.
3465         string_parser = StringParser()
3466         idx = string_parser.parse(LL, string_idx)
3467
3468         # That string MAY be followed by an empty RPAR...
3469         if is_valid_index(idx) and is_empty_rpar(LL[idx]):
3470             idx += 1
3471
3472         # That string / empty RPAR leaf MAY be followed by a comma...
3473         if is_valid_index(idx) and LL[idx].type == token.COMMA:
3474             idx += 1
3475
3476         # But no more leaves are allowed...
3477         if is_valid_index(idx):
3478             return TErr("This line does not end with a string.")
3479
3480         return Ok(string_idx)
3481
3482     def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
3483         LL = line.leaves
3484
3485         QUOTE = LL[string_idx].value[-1]
3486
3487         is_valid_index = is_valid_index_factory(LL)
3488         insert_str_child = insert_str_child_factory(LL[string_idx])
3489
3490         prefix = get_string_prefix(LL[string_idx].value)
3491
3492         # We MAY choose to drop the 'f' prefix from substrings that don't
3493         # contain any f-expressions, but ONLY if the original f-string
3494         # containes at least one f-expression. Otherwise, we will alter the AST
3495         # of the program.
3496         drop_pointless_f_prefix = ("f" in prefix) and re.search(
3497             self.RE_FEXPR, LL[string_idx].value, re.VERBOSE
3498         )
3499
3500         first_string_line = True
3501         starts_with_plus = LL[0].type == token.PLUS
3502
3503         def line_needs_plus() -> bool:
3504             return first_string_line and starts_with_plus
3505
3506         def maybe_append_plus(new_line: Line) -> None:
3507             """
3508             Side Effects:
3509                 If @line starts with a plus and this is the first line we are
3510                 constructing, this function appends a PLUS leaf to @new_line
3511                 and replaces the old PLUS leaf in the node structure. Otherwise
3512                 this function does nothing.
3513             """
3514             if line_needs_plus():
3515                 plus_leaf = Leaf(token.PLUS, "+")
3516                 replace_child(LL[0], plus_leaf)
3517                 new_line.append(plus_leaf)
3518
3519         ends_with_comma = (
3520             is_valid_index(string_idx + 1) and LL[string_idx + 1].type == token.COMMA
3521         )
3522
3523         def max_last_string() -> int:
3524             """
3525             Returns:
3526                 The max allowed length of the string value used for the last
3527                 line we will construct.
3528             """
3529             result = self.line_length
3530             result -= line.depth * 4
3531             result -= 1 if ends_with_comma else 0
3532             result -= 2 if line_needs_plus() else 0
3533             return result
3534
3535         # --- Calculate Max Break Index (for string value)
3536         # We start with the line length limit
3537         max_break_idx = self.line_length
3538         # The last index of a string of length N is N-1.
3539         max_break_idx -= 1
3540         # Leading whitespace is not present in the string value (e.g. Leaf.value).
3541         max_break_idx -= line.depth * 4
3542         if max_break_idx < 0:
3543             yield TErr(
3544                 f"Unable to split {LL[string_idx].value} at such high of a line depth:"
3545                 f" {line.depth}"
3546             )
3547             return
3548
3549         # Check if StringMerger registered any custom splits.
3550         custom_splits = self.pop_custom_splits(LL[string_idx].value)
3551         # We use them ONLY if none of them would produce lines that exceed the
3552         # line limit.
3553         use_custom_breakpoints = bool(
3554             custom_splits
3555             and all(csplit.break_idx <= max_break_idx for csplit in custom_splits)
3556         )
3557
3558         # Temporary storage for the remaining chunk of the string line that
3559         # can't fit onto the line currently being constructed.
3560         rest_value = LL[string_idx].value
3561
3562         def more_splits_should_be_made() -> bool:
3563             """
3564             Returns:
3565                 True iff `rest_value` (the remaining string value from the last
3566                 split), should be split again.
3567             """
3568             if use_custom_breakpoints:
3569                 return len(custom_splits) > 1
3570             else:
3571                 return len(rest_value) > max_last_string()
3572
3573         string_line_results: List[Ok[Line]] = []
3574         while more_splits_should_be_made():
3575             if use_custom_breakpoints:
3576                 # Custom User Split (manual)
3577                 csplit = custom_splits.pop(0)
3578                 break_idx = csplit.break_idx
3579             else:
3580                 # Algorithmic Split (automatic)
3581                 max_bidx = max_break_idx - 2 if line_needs_plus() else max_break_idx
3582                 maybe_break_idx = self.__get_break_idx(rest_value, max_bidx)
3583                 if maybe_break_idx is None:
3584                     # If we are unable to algorthmically determine a good split
3585                     # and this string has custom splits registered to it, we
3586                     # fall back to using them--which means we have to start
3587                     # over from the beginning.
3588                     if custom_splits:
3589                         rest_value = LL[string_idx].value
3590                         string_line_results = []
3591                         first_string_line = True
3592                         use_custom_breakpoints = True
3593                         continue
3594
3595                     # Otherwise, we stop splitting here.
3596                     break
3597
3598                 break_idx = maybe_break_idx
3599
3600             # --- Construct `next_value`
3601             next_value = rest_value[:break_idx] + QUOTE
3602             if (
3603                 # Are we allowed to try to drop a pointless 'f' prefix?
3604                 drop_pointless_f_prefix
3605                 # If we are, will we be successful?
3606                 and next_value != self.__normalize_f_string(next_value, prefix)
3607             ):
3608                 # If the current custom split did NOT originally use a prefix,
3609                 # then `csplit.break_idx` will be off by one after removing
3610                 # the 'f' prefix.
3611                 break_idx = (
3612                     break_idx + 1
3613                     if use_custom_breakpoints and not csplit.has_prefix
3614                     else break_idx
3615                 )
3616                 next_value = rest_value[:break_idx] + QUOTE
3617                 next_value = self.__normalize_f_string(next_value, prefix)
3618
3619             # --- Construct `next_leaf`
3620             next_leaf = Leaf(token.STRING, next_value)
3621             insert_str_child(next_leaf)
3622             self.__maybe_normalize_string_quotes(next_leaf)
3623
3624             # --- Construct `next_line`
3625             next_line = line.clone()
3626             maybe_append_plus(next_line)
3627             next_line.append(next_leaf)
3628             string_line_results.append(Ok(next_line))
3629
3630             rest_value = prefix + QUOTE + rest_value[break_idx:]
3631             first_string_line = False
3632
3633         yield from string_line_results
3634
3635         if drop_pointless_f_prefix:
3636             rest_value = self.__normalize_f_string(rest_value, prefix)
3637
3638         rest_leaf = Leaf(token.STRING, rest_value)
3639         insert_str_child(rest_leaf)
3640
3641         # NOTE: I could not find a test case that verifies that the following
3642         # line is actually necessary, but it seems to be. Otherwise we risk
3643         # not normalizing the last substring, right?
3644         self.__maybe_normalize_string_quotes(rest_leaf)
3645
3646         last_line = line.clone()
3647         maybe_append_plus(last_line)
3648
3649         # If there are any leaves to the right of the target string...
3650         if is_valid_index(string_idx + 1):
3651             # We use `temp_value` here to determine how long the last line
3652             # would be if we were to append all the leaves to the right of the
3653             # target string to the last string line.
3654             temp_value = rest_value
3655             for leaf in LL[string_idx + 1 :]:
3656                 temp_value += str(leaf)
3657                 if leaf.type == token.LPAR:
3658                     break
3659
3660             # Try to fit them all on the same line with the last substring...
3661             if (
3662                 len(temp_value) <= max_last_string()
3663                 or LL[string_idx + 1].type == token.COMMA
3664             ):
3665                 last_line.append(rest_leaf)
3666                 append_leaves(last_line, line, LL[string_idx + 1 :])
3667                 yield Ok(last_line)
3668             # Otherwise, place the last substring on one line and everything
3669             # else on a line below that...
3670             else:
3671                 last_line.append(rest_leaf)
3672                 yield Ok(last_line)
3673
3674                 non_string_line = line.clone()
3675                 append_leaves(non_string_line, line, LL[string_idx + 1 :])
3676                 yield Ok(non_string_line)
3677         # Else the target string was the last leaf...
3678         else:
3679             last_line.append(rest_leaf)
3680             last_line.comments = line.comments.copy()
3681             yield Ok(last_line)
3682
3683     def __get_break_idx(self, string: str, max_break_idx: int) -> Optional[int]:
3684         """
3685         This method contains the algorithm that StringSplitter uses to
3686         determine which character to split each string at.
3687
3688         Args:
3689             @string: The substring that we are attempting to split.
3690             @max_break_idx: The ideal break index. We will return this value if it
3691             meets all the necessary conditions. In the likely event that it
3692             doesn't we will try to find the closest index BELOW @max_break_idx
3693             that does. If that fails, we will expand our search by also
3694             considering all valid indices ABOVE @max_break_idx.
3695
3696         Pre-Conditions:
3697             * assert_is_leaf_string(@string)
3698             * 0 <= @max_break_idx < len(@string)
3699
3700         Returns:
3701             break_idx, if an index is able to be found that meets all of the
3702             conditions listed in the 'Transformations' section of this classes'
3703             docstring.
3704                 OR
3705             None, otherwise.
3706         """
3707         is_valid_index = is_valid_index_factory(string)
3708
3709         assert is_valid_index(max_break_idx)
3710         assert_is_leaf_string(string)
3711
3712         _fexpr_slices: Optional[List[Tuple[Index, Index]]] = None
3713
3714         def fexpr_slices() -> Iterator[Tuple[Index, Index]]:
3715             """
3716             Yields:
3717                 All ranges of @string which, if @string were to be split there,
3718                 would result in the splitting of an f-expression (which is NOT
3719                 allowed).
3720             """
3721             nonlocal _fexpr_slices
3722
3723             if _fexpr_slices is None:
3724                 _fexpr_slices = []
3725                 for match in re.finditer(self.RE_FEXPR, string, re.VERBOSE):
3726                     _fexpr_slices.append(match.span())
3727
3728             yield from _fexpr_slices
3729
3730         is_fstring = "f" in get_string_prefix(string)
3731
3732         def breaks_fstring_expression(i: Index) -> bool:
3733             """
3734             Returns:
3735                 True iff returning @i would result in the splitting of an
3736                 f-expression (which is NOT allowed).
3737             """
3738             if not is_fstring:
3739                 return False
3740
3741             for (start, end) in fexpr_slices():
3742                 if start <= i < end:
3743                     return True
3744
3745             return False
3746
3747         def passes_all_checks(i: Index) -> bool:
3748             """
3749             Returns:
3750                 True iff ALL of the conditions listed in the 'Transformations'
3751                 section of this classes' docstring would be be met by returning @i.
3752             """
3753             is_space = string[i] == " "
3754             is_big_enough = (
3755                 len(string[i:]) >= self.MIN_SUBSTR_SIZE
3756                 and len(string[:i]) >= self.MIN_SUBSTR_SIZE
3757             )
3758             return is_space and is_big_enough and not breaks_fstring_expression(i)
3759
3760         # First, we check all indices BELOW @max_break_idx.
3761         break_idx = max_break_idx
3762         while is_valid_index(break_idx - 1) and not passes_all_checks(break_idx):
3763             break_idx -= 1
3764
3765         if not passes_all_checks(break_idx):
3766             # If that fails, we check all indices ABOVE @max_break_idx.
3767             #
3768             # If we are able to find a valid index here, the next line is going
3769             # to be longer than the specified line length, but it's probably
3770             # better than doing nothing at all.
3771             break_idx = max_break_idx + 1
3772             while is_valid_index(break_idx + 1) and not passes_all_checks(break_idx):
3773                 break_idx += 1
3774
3775             if not is_valid_index(break_idx) or not passes_all_checks(break_idx):
3776                 return None
3777
3778         return break_idx
3779
3780     def __maybe_normalize_string_quotes(self, leaf: Leaf) -> None:
3781         if self.normalize_strings:
3782             normalize_string_quotes(leaf)
3783
3784     def __normalize_f_string(self, string: str, prefix: str) -> str:
3785         """
3786         Pre-Conditions:
3787             * assert_is_leaf_string(@string)
3788
3789         Returns:
3790             * If @string is an f-string that contains no f-expressions, we
3791             return a string identical to @string except that the 'f' prefix
3792             has been stripped and all double braces (i.e. '{{' or '}}') have
3793             been normalized (i.e. turned into '{' or '}').
3794                 OR
3795             * Otherwise, we return @string.
3796         """
3797         assert_is_leaf_string(string)
3798
3799         if "f" in prefix and not re.search(self.RE_FEXPR, string, re.VERBOSE):
3800             new_prefix = prefix.replace("f", "")
3801
3802             temp = string[len(prefix) :]
3803             temp = re.sub(r"\{\{", "{", temp)
3804             temp = re.sub(r"\}\}", "}", temp)
3805             new_string = temp
3806
3807             return f"{new_prefix}{new_string}"
3808         else:
3809             return string
3810
3811
3812 class StringParenWrapper(CustomSplitMapMixin, BaseStringSplitter):
3813     """
3814     StringTransformer that splits non-"atom" strings (i.e. strings that do not
3815     exist on lines by themselves).
3816
3817     Requirements:
3818         All of the requirements listed in BaseStringSplitter's docstring in
3819         addition to the requirements listed below:
3820
3821         * The line is a return/yield statement, which returns/yields a string.
3822             OR
3823         * The line is part of a ternary expression (e.g. `x = y if cond else
3824         z`) such that the line starts with `else <string>`, where <string> is
3825         some string.
3826             OR
3827         * The line is an assert statement, which ends with a string.
3828             OR
3829         * The line is an assignment statement (e.g. `x = <string>` or `x +=
3830         <string>`) such that the variable is being assigned the value of some
3831         string.
3832             OR
3833         * The line is a dictionary key assignment where some valid key is being
3834         assigned the value of some string.
3835
3836     Transformations:
3837         The chosen string is wrapped in parentheses and then split at the LPAR.
3838
3839         We then have one line which ends with an LPAR and another line that
3840         starts with the chosen string. The latter line is then split again at
3841         the RPAR. This results in the RPAR (and possibly a trailing comma)
3842         being placed on its own line.
3843
3844         NOTE: If any leaves exist to the right of the chosen string (except
3845         for a trailing comma, which would be placed after the RPAR), those
3846         leaves are placed inside the parentheses.  In effect, the chosen
3847         string is not necessarily being "wrapped" by parentheses. We can,
3848         however, count on the LPAR being placed directly before the chosen
3849         string.
3850
3851         In other words, StringParenWrapper creates "atom" strings. These
3852         can then be split again by StringSplitter, if necessary.
3853
3854     Collaborations:
3855         In the event that a string line split by StringParenWrapper is
3856         changed such that it no longer needs to be given its own line,
3857         StringParenWrapper relies on StringParenStripper to clean up the
3858         parentheses it created.
3859     """
3860
3861     def do_splitter_match(self, line: Line) -> TMatchResult:
3862         LL = line.leaves
3863
3864         string_idx = None
3865         string_idx = string_idx or self._return_match(LL)
3866         string_idx = string_idx or self._else_match(LL)
3867         string_idx = string_idx or self._assert_match(LL)
3868         string_idx = string_idx or self._assign_match(LL)
3869         string_idx = string_idx or self._dict_match(LL)
3870
3871         if string_idx is not None:
3872             string_value = line.leaves[string_idx].value
3873             # If the string has no spaces...
3874             if " " not in string_value:
3875                 # And will still violate the line length limit when split...
3876                 max_string_length = self.line_length - ((line.depth + 1) * 4)
3877                 if len(string_value) > max_string_length:
3878                     # And has no associated custom splits...
3879                     if not self.has_custom_splits(string_value):
3880                         # Then we should NOT put this string on its own line.
3881                         return TErr(
3882                             "We do not wrap long strings in parentheses when the"
3883                             " resultant line would still be over the specified line"
3884                             " length and can't be split further by StringSplitter."
3885                         )
3886             return Ok(string_idx)
3887
3888         return TErr("This line does not contain any non-atomic strings.")
3889
3890     @staticmethod
3891     def _return_match(LL: List[Leaf]) -> Optional[int]:
3892         """
3893         Returns:
3894             string_idx such that @LL[string_idx] is equal to our target (i.e.
3895             matched) string, if this line matches the return/yield statement
3896             requirements listed in the 'Requirements' section of this classes'
3897             docstring.
3898                 OR
3899             None, otherwise.
3900         """
3901         # If this line is apart of a return/yield statement and the first leaf
3902         # contains either the "return" or "yield" keywords...
3903         if parent_type(LL[0]) in [syms.return_stmt, syms.yield_expr] and LL[
3904             0
3905         ].value in ["return", "yield"]:
3906             is_valid_index = is_valid_index_factory(LL)
3907
3908             idx = 2 if is_valid_index(1) and is_empty_par(LL[1]) else 1
3909             # The next visible leaf MUST contain a string...
3910             if is_valid_index(idx) and LL[idx].type == token.STRING:
3911                 return idx
3912
3913         return None
3914
3915     @staticmethod
3916     def _else_match(LL: List[Leaf]) -> Optional[int]:
3917         """
3918         Returns:
3919             string_idx such that @LL[string_idx] is equal to our target (i.e.
3920             matched) string, if this line matches the ternary expression
3921             requirements listed in the 'Requirements' section of this classes'
3922             docstring.
3923                 OR
3924             None, otherwise.
3925         """
3926         # If this line is apart of a ternary expression and the first leaf
3927         # contains the "else" keyword...
3928         if (
3929             parent_type(LL[0]) == syms.test
3930             and LL[0].type == token.NAME
3931             and LL[0].value == "else"
3932         ):
3933             is_valid_index = is_valid_index_factory(LL)
3934
3935             idx = 2 if is_valid_index(1) and is_empty_par(LL[1]) else 1
3936             # The next visible leaf MUST contain a string...
3937             if is_valid_index(idx) and LL[idx].type == token.STRING:
3938                 return idx
3939
3940         return None
3941
3942     @staticmethod
3943     def _assert_match(LL: List[Leaf]) -> Optional[int]:
3944         """
3945         Returns:
3946             string_idx such that @LL[string_idx] is equal to our target (i.e.
3947             matched) string, if this line matches the assert statement
3948             requirements listed in the 'Requirements' section of this classes'
3949             docstring.
3950                 OR
3951             None, otherwise.
3952         """
3953         # If this line is apart of an assert statement and the first leaf
3954         # contains the "assert" keyword...
3955         if parent_type(LL[0]) == syms.assert_stmt and LL[0].value == "assert":
3956             is_valid_index = is_valid_index_factory(LL)
3957
3958             for (i, leaf) in enumerate(LL):
3959                 # We MUST find a comma...
3960                 if leaf.type == token.COMMA:
3961                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
3962
3963                     # That comma MUST be followed by a string...
3964                     if is_valid_index(idx) and LL[idx].type == token.STRING:
3965                         string_idx = idx
3966
3967                         # Skip the string trailer, if one exists.
3968                         string_parser = StringParser()
3969                         idx = string_parser.parse(LL, string_idx)
3970
3971                         # But no more leaves are allowed...
3972                         if not is_valid_index(idx):
3973                             return string_idx
3974
3975         return None
3976
3977     @staticmethod
3978     def _assign_match(LL: List[Leaf]) -> Optional[int]:
3979         """
3980         Returns:
3981             string_idx such that @LL[string_idx] is equal to our target (i.e.
3982             matched) string, if this line matches the assignment statement
3983             requirements listed in the 'Requirements' section of this classes'
3984             docstring.
3985                 OR
3986             None, otherwise.
3987         """
3988         # If this line is apart of an expression statement or is a function
3989         # argument AND the first leaf contains a variable name...
3990         if (
3991             parent_type(LL[0]) in [syms.expr_stmt, syms.argument, syms.power]
3992             and LL[0].type == token.NAME
3993         ):
3994             is_valid_index = is_valid_index_factory(LL)
3995
3996             for (i, leaf) in enumerate(LL):
3997                 # We MUST find either an '=' or '+=' symbol...
3998                 if leaf.type in [token.EQUAL, token.PLUSEQUAL]:
3999                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
4000
4001                     # That symbol MUST be followed by a string...
4002                     if is_valid_index(idx) and LL[idx].type == token.STRING:
4003                         string_idx = idx
4004
4005                         # Skip the string trailer, if one exists.
4006                         string_parser = StringParser()
4007                         idx = string_parser.parse(LL, string_idx)
4008
4009                         # The next leaf MAY be a comma iff this line is apart
4010                         # of a function argument...
4011                         if (
4012                             parent_type(LL[0]) == syms.argument
4013                             and is_valid_index(idx)
4014                             and LL[idx].type == token.COMMA
4015                         ):
4016                             idx += 1
4017
4018                         # But no more leaves are allowed...
4019                         if not is_valid_index(idx):
4020                             return string_idx
4021
4022         return None
4023
4024     @staticmethod
4025     def _dict_match(LL: List[Leaf]) -> Optional[int]:
4026         """
4027         Returns:
4028             string_idx such that @LL[string_idx] is equal to our target (i.e.
4029             matched) string, if this line matches the dictionary key assignment
4030             statement requirements listed in the 'Requirements' section of this
4031             classes' docstring.
4032                 OR
4033             None, otherwise.
4034         """
4035         # If this line is apart of a dictionary key assignment...
4036         if syms.dictsetmaker in [parent_type(LL[0]), parent_type(LL[0].parent)]:
4037             is_valid_index = is_valid_index_factory(LL)
4038
4039             for (i, leaf) in enumerate(LL):
4040                 # We MUST find a colon...
4041                 if leaf.type == token.COLON:
4042                     idx = i + 2 if is_empty_par(LL[i + 1]) else i + 1
4043
4044                     # That colon MUST be followed by a string...
4045                     if is_valid_index(idx) and LL[idx].type == token.STRING:
4046                         string_idx = idx
4047
4048                         # Skip the string trailer, if one exists.
4049                         string_parser = StringParser()
4050                         idx = string_parser.parse(LL, string_idx)
4051
4052                         # That string MAY be followed by a comma...
4053                         if is_valid_index(idx) and LL[idx].type == token.COMMA:
4054                             idx += 1
4055
4056                         # But no more leaves are allowed...
4057                         if not is_valid_index(idx):
4058                             return string_idx
4059
4060         return None
4061
4062     def do_transform(self, line: Line, string_idx: int) -> Iterator[TResult[Line]]:
4063         LL = line.leaves
4064
4065         is_valid_index = is_valid_index_factory(LL)
4066         insert_str_child = insert_str_child_factory(LL[string_idx])
4067
4068         comma_idx = len(LL) - 1
4069         ends_with_comma = False
4070         if LL[comma_idx].type == token.COMMA:
4071             ends_with_comma = True
4072
4073         leaves_to_steal_comments_from = [LL[string_idx]]
4074         if ends_with_comma:
4075             leaves_to_steal_comments_from.append(LL[comma_idx])
4076
4077         # --- First Line
4078         first_line = line.clone()
4079         left_leaves = LL[:string_idx]
4080
4081         # We have to remember to account for (possibly invisible) LPAR and RPAR
4082         # leaves that already wrapped the target string. If these leaves do
4083         # exist, we will replace them with our own LPAR and RPAR leaves.
4084         old_parens_exist = False
4085         if left_leaves and left_leaves[-1].type == token.LPAR:
4086             old_parens_exist = True
4087             leaves_to_steal_comments_from.append(left_leaves[-1])
4088             left_leaves.pop()
4089
4090         append_leaves(first_line, line, left_leaves)
4091
4092         lpar_leaf = Leaf(token.LPAR, "(")
4093         if old_parens_exist:
4094             replace_child(LL[string_idx - 1], lpar_leaf)
4095         else:
4096             insert_str_child(lpar_leaf)
4097         first_line.append(lpar_leaf)
4098
4099         # We throw inline comments that were originally to the right of the
4100         # target string to the top line. They will now be shown to the right of
4101         # the LPAR.
4102         for leaf in leaves_to_steal_comments_from:
4103             for comment_leaf in line.comments_after(leaf):
4104                 first_line.append(comment_leaf, preformatted=True)
4105
4106         yield Ok(first_line)
4107
4108         # --- Middle (String) Line
4109         # We only need to yield one (possibly too long) string line, since the
4110         # `StringSplitter` will break it down further if necessary.
4111         string_value = LL[string_idx].value
4112         string_line = Line(
4113             depth=line.depth + 1,
4114             inside_brackets=True,
4115             should_explode=line.should_explode,
4116         )
4117         string_leaf = Leaf(token.STRING, string_value)
4118         insert_str_child(string_leaf)
4119         string_line.append(string_leaf)
4120
4121         old_rpar_leaf = None
4122         if is_valid_index(string_idx + 1):
4123             right_leaves = LL[string_idx + 1 :]
4124             if ends_with_comma:
4125                 right_leaves.pop()
4126
4127             if old_parens_exist:
4128                 assert (
4129                     right_leaves and right_leaves[-1].type == token.RPAR
4130                 ), "Apparently, old parentheses do NOT exist?!"
4131                 old_rpar_leaf = right_leaves.pop()
4132
4133             append_leaves(string_line, line, right_leaves)
4134
4135         yield Ok(string_line)
4136
4137         # --- Last Line
4138         last_line = line.clone()
4139         last_line.bracket_tracker = first_line.bracket_tracker
4140
4141         new_rpar_leaf = Leaf(token.RPAR, ")")
4142         if old_rpar_leaf is not None:
4143             replace_child(old_rpar_leaf, new_rpar_leaf)
4144         else:
4145             insert_str_child(new_rpar_leaf)
4146         last_line.append(new_rpar_leaf)
4147
4148         # If the target string ended with a comma, we place this comma to the
4149         # right of the RPAR on the last line.
4150         if ends_with_comma:
4151             comma_leaf = Leaf(token.COMMA, ",")
4152             replace_child(LL[comma_idx], comma_leaf)
4153             last_line.append(comma_leaf)
4154
4155         yield Ok(last_line)
4156
4157
4158 class StringParser:
4159     """
4160     A state machine that aids in parsing a string's "trailer", which can be
4161     either non-existant, an old-style formatting sequence (e.g. `% varX` or `%
4162     (varX, varY)`), or a method-call / attribute access (e.g. `.format(varX,
4163     varY)`).
4164
4165     NOTE: A new StringParser object MUST be instantiated for each string
4166     trailer we need to parse.
4167
4168     Examples:
4169         We shall assume that `line` equals the `Line` object that corresponds
4170         to the following line of python code:
4171         ```
4172         x = "Some {}.".format("String") + some_other_string
4173         ```
4174
4175         Furthermore, we will assume that `string_idx` is some index such that:
4176         ```
4177         assert line.leaves[string_idx].value == "Some {}."
4178         ```
4179
4180         The following code snippet then holds:
4181         ```
4182         string_parser = StringParser()
4183         idx = string_parser.parse(line.leaves, string_idx)
4184         assert line.leaves[idx].type == token.PLUS
4185         ```
4186     """
4187
4188     DEFAULT_TOKEN = -1
4189
4190     # String Parser States
4191     START = 1
4192     DOT = 2
4193     NAME = 3
4194     PERCENT = 4
4195     SINGLE_FMT_ARG = 5
4196     LPAR = 6
4197     RPAR = 7
4198     DONE = 8
4199
4200     # Lookup Table for Next State
4201     _goto: Dict[Tuple[ParserState, NodeType], ParserState] = {
4202         # A string trailer may start with '.' OR '%'.
4203         (START, token.DOT): DOT,
4204         (START, token.PERCENT): PERCENT,
4205         (START, DEFAULT_TOKEN): DONE,
4206         # A '.' MUST be followed by an attribute or method name.
4207         (DOT, token.NAME): NAME,
4208         # A method name MUST be followed by an '(', whereas an attribute name
4209         # is the last symbol in the string trailer.
4210         (NAME, token.LPAR): LPAR,
4211         (NAME, DEFAULT_TOKEN): DONE,
4212         # A '%' symbol can be followed by an '(' or a single argument (e.g. a
4213         # string or variable name).
4214         (PERCENT, token.LPAR): LPAR,
4215         (PERCENT, DEFAULT_TOKEN): SINGLE_FMT_ARG,
4216         # If a '%' symbol is followed by a single argument, that argument is
4217         # the last leaf in the string trailer.
4218         (SINGLE_FMT_ARG, DEFAULT_TOKEN): DONE,
4219         # If present, a ')' symbol is the last symbol in a string trailer.
4220         # (NOTE: LPARS and nested RPARS are not included in this lookup table,
4221         # since they are treated as a special case by the parsing logic in this
4222         # classes' implementation.)
4223         (RPAR, DEFAULT_TOKEN): DONE,
4224     }
4225
4226     def __init__(self) -> None:
4227         self._state = self.START
4228         self._unmatched_lpars = 0
4229
4230     def parse(self, leaves: List[Leaf], string_idx: int) -> int:
4231         """
4232         Pre-conditions:
4233             * @leaves[@string_idx].type == token.STRING
4234
4235         Returns:
4236             The index directly after the last leaf which is apart of the string
4237             trailer, if a "trailer" exists.
4238                 OR
4239             @string_idx + 1, if no string "trailer" exists.
4240         """
4241         assert leaves[string_idx].type == token.STRING
4242
4243         idx = string_idx + 1
4244         while idx < len(leaves) and self._next_state(leaves[idx]):
4245             idx += 1
4246         return idx
4247
4248     def _next_state(self, leaf: Leaf) -> bool:
4249         """
4250         Pre-conditions:
4251             * On the first call to this function, @leaf MUST be the leaf that
4252             was directly after the string leaf in question (e.g. if our target
4253             string is `line.leaves[i]` then the first call to this method must
4254             be `line.leaves[i + 1]`).
4255             * On the next call to this function, the leaf paramater passed in
4256             MUST be the leaf directly following @leaf.
4257
4258         Returns:
4259             True iff @leaf is apart of the string's trailer.
4260         """
4261         # We ignore empty LPAR or RPAR leaves.
4262         if is_empty_par(leaf):
4263             return True
4264
4265         next_token = leaf.type
4266         if next_token == token.LPAR:
4267             self._unmatched_lpars += 1
4268
4269         current_state = self._state
4270
4271         # The LPAR parser state is a special case. We will return True until we
4272         # find the matching RPAR token.
4273         if current_state == self.LPAR:
4274             if next_token == token.RPAR:
4275                 self._unmatched_lpars -= 1
4276                 if self._unmatched_lpars == 0:
4277                     self._state = self.RPAR
4278         # Otherwise, we use a lookup table to determine the next state.
4279         else:
4280             # If the lookup table matches the current state to the next
4281             # token, we use the lookup table.
4282             if (current_state, next_token) in self._goto:
4283                 self._state = self._goto[current_state, next_token]
4284             else:
4285                 # Otherwise, we check if a the current state was assigned a
4286                 # default.
4287                 if (current_state, self.DEFAULT_TOKEN) in self._goto:
4288                     self._state = self._goto[current_state, self.DEFAULT_TOKEN]
4289                 # If no default has been assigned, then this parser has a logic
4290                 # error.
4291                 else:
4292                     raise RuntimeError(f"{self.__class__.__name__} LOGIC ERROR!")
4293
4294             if self._state == self.DONE:
4295                 return False
4296
4297         return True
4298
4299
4300 def TErr(err_msg: str) -> Err[CannotTransform]:
4301     """(T)ransform Err
4302
4303     Convenience function used when working with the TResult type.
4304     """
4305     cant_transform = CannotTransform(err_msg)
4306     return Err(cant_transform)
4307
4308
4309 def contains_pragma_comment(comment_list: List[Leaf]) -> bool:
4310     """
4311     Returns:
4312         True iff one of the comments in @comment_list is a pragma used by one
4313         of the more common static analysis tools for python (e.g. mypy, flake8,
4314         pylint).
4315     """
4316     for comment in comment_list:
4317         if comment.value.startswith(("# type:", "# noqa", "# pylint:")):
4318             return True
4319
4320     return False
4321
4322
4323 def insert_str_child_factory(string_leaf: Leaf) -> Callable[[LN], None]:
4324     """
4325     Factory for a convenience function that is used to orphan @string_leaf
4326     and then insert multiple new leaves into the same part of the node
4327     structure that @string_leaf had originally occupied.
4328
4329     Examples:
4330         Let `string_leaf = Leaf(token.STRING, '"foo"')` and `N =
4331         string_leaf.parent`. Assume the node `N` has the following
4332         original structure:
4333
4334         Node(
4335             expr_stmt, [
4336                 Leaf(NAME, 'x'),
4337                 Leaf(EQUAL, '='),
4338                 Leaf(STRING, '"foo"'),
4339             ]
4340         )
4341
4342         We then run the code snippet shown below.
4343         ```
4344         insert_str_child = insert_str_child_factory(string_leaf)
4345
4346         lpar = Leaf(token.LPAR, '(')
4347         insert_str_child(lpar)
4348
4349         bar = Leaf(token.STRING, '"bar"')
4350         insert_str_child(bar)
4351
4352         rpar = Leaf(token.RPAR, ')')
4353         insert_str_child(rpar)
4354         ```
4355
4356         After which point, it follows that `string_leaf.parent is None` and
4357         the node `N` now has the following structure:
4358
4359         Node(
4360             expr_stmt, [
4361                 Leaf(NAME, 'x'),
4362                 Leaf(EQUAL, '='),
4363                 Leaf(LPAR, '('),
4364                 Leaf(STRING, '"bar"'),
4365                 Leaf(RPAR, ')'),
4366             ]
4367         )
4368     """
4369     string_parent = string_leaf.parent
4370     string_child_idx = string_leaf.remove()
4371
4372     def insert_str_child(child: LN) -> None:
4373         nonlocal string_child_idx
4374
4375         assert string_parent is not None
4376         assert string_child_idx is not None
4377
4378         string_parent.insert_child(string_child_idx, child)
4379         string_child_idx += 1
4380
4381     return insert_str_child
4382
4383
4384 def has_triple_quotes(string: str) -> bool:
4385     """
4386     Returns:
4387         True iff @string starts with three quotation characters.
4388     """
4389     raw_string = string.lstrip(STRING_PREFIX_CHARS)
4390     return raw_string[:3] in {'"""', "'''"}
4391
4392
4393 def parent_type(node: Optional[LN]) -> Optional[NodeType]:
4394     """
4395     Returns:
4396         @node.parent.type, if @node is not None and has a parent.
4397             OR
4398         None, otherwise.
4399     """
4400     if node is None or node.parent is None:
4401         return None
4402
4403     return node.parent.type
4404
4405
4406 def is_empty_par(leaf: Leaf) -> bool:
4407     return is_empty_lpar(leaf) or is_empty_rpar(leaf)
4408
4409
4410 def is_empty_lpar(leaf: Leaf) -> bool:
4411     return leaf.type == token.LPAR and leaf.value == ""
4412
4413
4414 def is_empty_rpar(leaf: Leaf) -> bool:
4415     return leaf.type == token.RPAR and leaf.value == ""
4416
4417
4418 def is_valid_index_factory(seq: Sequence[Any]) -> Callable[[int], bool]:
4419     """
4420     Examples:
4421         ```
4422         my_list = [1, 2, 3]
4423
4424         is_valid_index = is_valid_index_factory(my_list)
4425
4426         assert is_valid_index(0)
4427         assert is_valid_index(2)
4428
4429         assert not is_valid_index(3)
4430         assert not is_valid_index(-1)
4431         ```
4432     """
4433
4434     def is_valid_index(idx: int) -> bool:
4435         """
4436         Returns:
4437             True iff @idx is positive AND seq[@idx] does NOT raise an
4438             IndexError.
4439         """
4440         return 0 <= idx < len(seq)
4441
4442     return is_valid_index
4443
4444
4445 def line_to_string(line: Line) -> str:
4446     """Returns the string representation of @line.
4447
4448     WARNING: This is known to be computationally expensive.
4449     """
4450     return str(line).strip("\n")
4451
4452
4453 def append_leaves(new_line: Line, old_line: Line, leaves: List[Leaf]) -> None:
4454     """
4455     Append leaves (taken from @old_line) to @new_line, making sure to fix the
4456     underlying Node structure where appropriate.
4457
4458     All of the leaves in @leaves are duplicated. The duplicates are then
4459     appended to @new_line and used to replace their originals in the underlying
4460     Node structure. Any comments attatched to the old leaves are reattached to
4461     the new leaves.
4462
4463     Pre-conditions:
4464         set(@leaves) is a subset of set(@old_line.leaves).
4465     """
4466     for old_leaf in leaves:
4467         assert old_leaf in old_line.leaves
4468
4469         new_leaf = Leaf(old_leaf.type, old_leaf.value)
4470         replace_child(old_leaf, new_leaf)
4471         new_line.append(new_leaf)
4472
4473         for comment_leaf in old_line.comments_after(old_leaf):
4474             new_line.append(comment_leaf, preformatted=True)
4475
4476
4477 def replace_child(old_child: LN, new_child: LN) -> None:
4478     """
4479     Side Effects:
4480         * If @old_child.parent is set, replace @old_child with @new_child in
4481         @old_child's underlying Node structure.
4482             OR
4483         * Otherwise, this function does nothing.
4484     """
4485     parent = old_child.parent
4486     if not parent:
4487         return
4488
4489     child_idx = old_child.remove()
4490     if child_idx is not None:
4491         parent.insert_child(child_idx, new_child)
4492
4493
4494 def get_string_prefix(string: str) -> str:
4495     """
4496     Pre-conditions:
4497         * assert_is_leaf_string(@string)
4498
4499     Returns:
4500         @string's prefix (e.g. '', 'r', 'f', or 'rf').
4501     """
4502     assert_is_leaf_string(string)
4503
4504     prefix = ""
4505     prefix_idx = 0
4506     while string[prefix_idx] in STRING_PREFIX_CHARS:
4507         prefix += string[prefix_idx].lower()
4508         prefix_idx += 1
4509
4510     return prefix
4511
4512
4513 def assert_is_leaf_string(string: str) -> None:
4514     """
4515     Checks the pre-condition that @string has the format that you would expect
4516     of `leaf.value` where `leaf` is some Leaf such that `leaf.type ==
4517     token.STRING`. A more precise description of the pre-conditions that are
4518     checked are listed below.
4519
4520     Pre-conditions:
4521         * @string starts with either ', ", <prefix>', or <prefix>" where
4522         `set(<prefix>)` is some subset of `set(STRING_PREFIX_CHARS)`.
4523         * @string ends with a quote character (' or ").
4524
4525     Raises:
4526         AssertionError(...) if the pre-conditions listed above are not
4527         satisfied.
4528     """
4529     dquote_idx = string.find('"')
4530     squote_idx = string.find("'")
4531     if -1 in [dquote_idx, squote_idx]:
4532         quote_idx = max(dquote_idx, squote_idx)
4533     else:
4534         quote_idx = min(squote_idx, dquote_idx)
4535
4536     assert (
4537         0 <= quote_idx < len(string) - 1
4538     ), f"{string!r} is missing a starting quote character (' or \")."
4539     assert string[-1] in (
4540         "'",
4541         '"',
4542     ), f"{string!r} is missing an ending quote character (' or \")."
4543     assert set(string[:quote_idx]).issubset(
4544         set(STRING_PREFIX_CHARS)
4545     ), f"{set(string[:quote_idx])} is NOT a subset of {set(STRING_PREFIX_CHARS)}."
4546
4547
4548 def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
4549     """Split line into many lines, starting with the first matching bracket pair.
4550
4551     Note: this usually looks weird, only use this for function definitions.
4552     Prefer RHS otherwise.  This is why this function is not symmetrical with
4553     :func:`right_hand_split` which also handles optional parentheses.
4554     """
4555     tail_leaves: List[Leaf] = []
4556     body_leaves: List[Leaf] = []
4557     head_leaves: List[Leaf] = []
4558     current_leaves = head_leaves
4559     matching_bracket: Optional[Leaf] = None
4560     for leaf in line.leaves:
4561         if (
4562             current_leaves is body_leaves
4563             and leaf.type in CLOSING_BRACKETS
4564             and leaf.opening_bracket is matching_bracket
4565         ):
4566             current_leaves = tail_leaves if body_leaves else head_leaves
4567         current_leaves.append(leaf)
4568         if current_leaves is head_leaves:
4569             if leaf.type in OPENING_BRACKETS:
4570                 matching_bracket = leaf
4571                 current_leaves = body_leaves
4572     if not matching_bracket:
4573         raise CannotSplit("No brackets found")
4574
4575     head = bracket_split_build_line(head_leaves, line, matching_bracket)
4576     body = bracket_split_build_line(body_leaves, line, matching_bracket, is_body=True)
4577     tail = bracket_split_build_line(tail_leaves, line, matching_bracket)
4578     bracket_split_succeeded_or_raise(head, body, tail)
4579     for result in (head, body, tail):
4580         if result:
4581             yield result
4582
4583
4584 def right_hand_split(
4585     line: Line,
4586     line_length: int,
4587     features: Collection[Feature] = (),
4588     omit: Collection[LeafID] = (),
4589 ) -> Iterator[Line]:
4590     """Split line into many lines, starting with the last matching bracket pair.
4591
4592     If the split was by optional parentheses, attempt splitting without them, too.
4593     `omit` is a collection of closing bracket IDs that shouldn't be considered for
4594     this split.
4595
4596     Note: running this function modifies `bracket_depth` on the leaves of `line`.
4597     """
4598     tail_leaves: List[Leaf] = []
4599     body_leaves: List[Leaf] = []
4600     head_leaves: List[Leaf] = []
4601     current_leaves = tail_leaves
4602     opening_bracket: Optional[Leaf] = None
4603     closing_bracket: Optional[Leaf] = None
4604     for leaf in reversed(line.leaves):
4605         if current_leaves is body_leaves:
4606             if leaf is opening_bracket:
4607                 current_leaves = head_leaves if body_leaves else tail_leaves
4608         current_leaves.append(leaf)
4609         if current_leaves is tail_leaves:
4610             if leaf.type in CLOSING_BRACKETS and id(leaf) not in omit:
4611                 opening_bracket = leaf.opening_bracket
4612                 closing_bracket = leaf
4613                 current_leaves = body_leaves
4614     if not (opening_bracket and closing_bracket and head_leaves):
4615         # If there is no opening or closing_bracket that means the split failed and
4616         # all content is in the tail.  Otherwise, if `head_leaves` are empty, it means
4617         # the matching `opening_bracket` wasn't available on `line` anymore.
4618         raise CannotSplit("No brackets found")
4619
4620     tail_leaves.reverse()
4621     body_leaves.reverse()
4622     head_leaves.reverse()
4623     head = bracket_split_build_line(head_leaves, line, opening_bracket)
4624     body = bracket_split_build_line(body_leaves, line, opening_bracket, is_body=True)
4625     tail = bracket_split_build_line(tail_leaves, line, opening_bracket)
4626     bracket_split_succeeded_or_raise(head, body, tail)
4627     if (
4628         # the body shouldn't be exploded
4629         not body.should_explode
4630         # the opening bracket is an optional paren
4631         and opening_bracket.type == token.LPAR
4632         and not opening_bracket.value
4633         # the closing bracket is an optional paren
4634         and closing_bracket.type == token.RPAR
4635         and not closing_bracket.value
4636         # it's not an import (optional parens are the only thing we can split on
4637         # in this case; attempting a split without them is a waste of time)
4638         and not line.is_import
4639         # there are no standalone comments in the body
4640         and not body.contains_standalone_comments(0)
4641         # and we can actually remove the parens
4642         and can_omit_invisible_parens(body, line_length)
4643     ):
4644         omit = {id(closing_bracket), *omit}
4645         try:
4646             yield from right_hand_split(line, line_length, features=features, omit=omit)
4647             return
4648
4649         except CannotSplit:
4650             if not (
4651                 can_be_split(body)
4652                 or is_line_short_enough(body, line_length=line_length)
4653             ):
4654                 raise CannotSplit(
4655                     "Splitting failed, body is still too long and can't be split."
4656                 )
4657
4658             elif head.contains_multiline_strings() or tail.contains_multiline_strings():
4659                 raise CannotSplit(
4660                     "The current optional pair of parentheses is bound to fail to"
4661                     " satisfy the splitting algorithm because the head or the tail"
4662                     " contains multiline strings which by definition never fit one"
4663                     " line."
4664                 )
4665
4666     ensure_visible(opening_bracket)
4667     ensure_visible(closing_bracket)
4668     for result in (head, body, tail):
4669         if result:
4670             yield result
4671
4672
4673 def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
4674     """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
4675
4676     Do nothing otherwise.
4677
4678     A left- or right-hand split is based on a pair of brackets. Content before
4679     (and including) the opening bracket is left on one line, content inside the
4680     brackets is put on a separate line, and finally content starting with and
4681     following the closing bracket is put on a separate line.
4682
4683     Those are called `head`, `body`, and `tail`, respectively. If the split
4684     produced the same line (all content in `head`) or ended up with an empty `body`
4685     and the `tail` is just the closing bracket, then it's considered failed.
4686     """
4687     tail_len = len(str(tail).strip())
4688     if not body:
4689         if tail_len == 0:
4690             raise CannotSplit("Splitting brackets produced the same line")
4691
4692         elif tail_len < 3:
4693             raise CannotSplit(
4694                 f"Splitting brackets on an empty body to save {tail_len} characters is"
4695                 " not worth it"
4696             )
4697
4698
4699 def bracket_split_build_line(
4700     leaves: List[Leaf], original: Line, opening_bracket: Leaf, *, is_body: bool = False
4701 ) -> Line:
4702     """Return a new line with given `leaves` and respective comments from `original`.
4703
4704     If `is_body` is True, the result line is one-indented inside brackets and as such
4705     has its first leaf's prefix normalized and a trailing comma added when expected.
4706     """
4707     result = Line(depth=original.depth)
4708     if is_body:
4709         result.inside_brackets = True
4710         result.depth += 1
4711         if leaves:
4712             # Since body is a new indent level, remove spurious leading whitespace.
4713             normalize_prefix(leaves[0], inside_brackets=True)
4714             # Ensure a trailing comma for imports and standalone function arguments, but
4715             # be careful not to add one after any comments or within type annotations.
4716             no_commas = (
4717                 original.is_def
4718                 and opening_bracket.value == "("
4719                 and not any(l.type == token.COMMA for l in leaves)
4720             )
4721
4722             if original.is_import or no_commas:
4723                 for i in range(len(leaves) - 1, -1, -1):
4724                     if leaves[i].type == STANDALONE_COMMENT:
4725                         continue
4726
4727                     if leaves[i].type != token.COMMA:
4728                         leaves.insert(i + 1, Leaf(token.COMMA, ","))
4729                     break
4730
4731     # Populate the line
4732     for leaf in leaves:
4733         result.append(leaf, preformatted=True)
4734         for comment_after in original.comments_after(leaf):
4735             result.append(comment_after, preformatted=True)
4736     if is_body:
4737         result.should_explode = should_explode(result, opening_bracket)
4738     return result
4739
4740
4741 def dont_increase_indentation(split_func: Transformer) -> Transformer:
4742     """Normalize prefix of the first leaf in every line returned by `split_func`.
4743
4744     This is a decorator over relevant split functions.
4745     """
4746
4747     @wraps(split_func)
4748     def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
4749         for l in split_func(line, features):
4750             normalize_prefix(l.leaves[0], inside_brackets=True)
4751             yield l
4752
4753     return split_wrapper
4754
4755
4756 @dont_increase_indentation
4757 def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
4758     """Split according to delimiters of the highest priority.
4759
4760     If the appropriate Features are given, the split will add trailing commas
4761     also in function signatures and calls that contain `*` and `**`.
4762     """
4763     try:
4764         last_leaf = line.leaves[-1]
4765     except IndexError:
4766         raise CannotSplit("Line empty")
4767
4768     bt = line.bracket_tracker
4769     try:
4770         delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
4771     except ValueError:
4772         raise CannotSplit("No delimiters found")
4773
4774     if delimiter_priority == DOT_PRIORITY:
4775         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
4776             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
4777
4778     current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
4779     lowest_depth = sys.maxsize
4780     trailing_comma_safe = True
4781
4782     def append_to_line(leaf: Leaf) -> Iterator[Line]:
4783         """Append `leaf` to current line or to new line if appending impossible."""
4784         nonlocal current_line
4785         try:
4786             current_line.append_safe(leaf, preformatted=True)
4787         except ValueError:
4788             yield current_line
4789
4790             current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
4791             current_line.append(leaf)
4792
4793     for leaf in line.leaves:
4794         yield from append_to_line(leaf)
4795
4796         for comment_after in line.comments_after(leaf):
4797             yield from append_to_line(comment_after)
4798
4799         lowest_depth = min(lowest_depth, leaf.bracket_depth)
4800         if leaf.bracket_depth == lowest_depth:
4801             if is_vararg(leaf, within={syms.typedargslist}):
4802                 trailing_comma_safe = (
4803                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
4804                 )
4805             elif is_vararg(leaf, within={syms.arglist, syms.argument}):
4806                 trailing_comma_safe = (
4807                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
4808                 )
4809
4810         leaf_priority = bt.delimiters.get(id(leaf))
4811         if leaf_priority == delimiter_priority:
4812             yield current_line
4813
4814             current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
4815     if current_line:
4816         if (
4817             trailing_comma_safe
4818             and delimiter_priority == COMMA_PRIORITY
4819             and current_line.leaves[-1].type != token.COMMA
4820             and current_line.leaves[-1].type != STANDALONE_COMMENT
4821         ):
4822             current_line.append(Leaf(token.COMMA, ","))
4823         yield current_line
4824
4825
4826 @dont_increase_indentation
4827 def standalone_comment_split(
4828     line: Line, features: Collection[Feature] = ()
4829 ) -> Iterator[Line]:
4830     """Split standalone comments from the rest of the line."""
4831     if not line.contains_standalone_comments(0):
4832         raise CannotSplit("Line does not have any standalone comments")
4833
4834     current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
4835
4836     def append_to_line(leaf: Leaf) -> Iterator[Line]:
4837         """Append `leaf` to current line or to new line if appending impossible."""
4838         nonlocal current_line
4839         try:
4840             current_line.append_safe(leaf, preformatted=True)
4841         except ValueError:
4842             yield current_line
4843
4844             current_line = Line(depth=line.depth, inside_brackets=line.inside_brackets)
4845             current_line.append(leaf)
4846
4847     for leaf in line.leaves:
4848         yield from append_to_line(leaf)
4849
4850         for comment_after in line.comments_after(leaf):
4851             yield from append_to_line(comment_after)
4852
4853     if current_line:
4854         yield current_line
4855
4856
4857 def is_import(leaf: Leaf) -> bool:
4858     """Return True if the given leaf starts an import statement."""
4859     p = leaf.parent
4860     t = leaf.type
4861     v = leaf.value
4862     return bool(
4863         t == token.NAME
4864         and (
4865             (v == "import" and p and p.type == syms.import_name)
4866             or (v == "from" and p and p.type == syms.import_from)
4867         )
4868     )
4869
4870
4871 def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
4872     """Return True if the given leaf is a special comment.
4873     Only returns true for type comments for now."""
4874     t = leaf.type
4875     v = leaf.value
4876     return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:" + suffix)
4877
4878
4879 def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
4880     """Leave existing extra newlines if not `inside_brackets`. Remove everything
4881     else.
4882
4883     Note: don't use backslashes for formatting or you'll lose your voting rights.
4884     """
4885     if not inside_brackets:
4886         spl = leaf.prefix.split("#")
4887         if "\\" not in spl[0]:
4888             nl_count = spl[-1].count("\n")
4889             if len(spl) > 1:
4890                 nl_count -= 1
4891             leaf.prefix = "\n" * nl_count
4892             return
4893
4894     leaf.prefix = ""
4895
4896
4897 def normalize_string_prefix(leaf: Leaf, remove_u_prefix: bool = False) -> None:
4898     """Make all string prefixes lowercase.
4899
4900     If remove_u_prefix is given, also removes any u prefix from the string.
4901
4902     Note: Mutates its argument.
4903     """
4904     match = re.match(r"^([" + STRING_PREFIX_CHARS + r"]*)(.*)$", leaf.value, re.DOTALL)
4905     assert match is not None, f"failed to match string {leaf.value!r}"
4906     orig_prefix = match.group(1)
4907     new_prefix = orig_prefix.replace("F", "f").replace("B", "b").replace("U", "u")
4908     if remove_u_prefix:
4909         new_prefix = new_prefix.replace("u", "")
4910     leaf.value = f"{new_prefix}{match.group(2)}"
4911
4912
4913 def normalize_string_quotes(leaf: Leaf) -> None:
4914     """Prefer double quotes but only if it doesn't cause more escaping.
4915
4916     Adds or removes backslashes as appropriate. Doesn't parse and fix
4917     strings nested in f-strings (yet).
4918
4919     Note: Mutates its argument.
4920     """
4921     value = leaf.value.lstrip(STRING_PREFIX_CHARS)
4922     if value[:3] == '"""':
4923         return
4924
4925     elif value[:3] == "'''":
4926         orig_quote = "'''"
4927         new_quote = '"""'
4928     elif value[0] == '"':
4929         orig_quote = '"'
4930         new_quote = "'"
4931     else:
4932         orig_quote = "'"
4933         new_quote = '"'
4934     first_quote_pos = leaf.value.find(orig_quote)
4935     if first_quote_pos == -1:
4936         return  # There's an internal error
4937
4938     prefix = leaf.value[:first_quote_pos]
4939     unescaped_new_quote = re.compile(rf"(([^\\]|^)(\\\\)*){new_quote}")
4940     escaped_new_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){new_quote}")
4941     escaped_orig_quote = re.compile(rf"([^\\]|^)\\((?:\\\\)*){orig_quote}")
4942     body = leaf.value[first_quote_pos + len(orig_quote) : -len(orig_quote)]
4943     if "r" in prefix.casefold():
4944         if unescaped_new_quote.search(body):
4945             # There's at least one unescaped new_quote in this raw string
4946             # so converting is impossible
4947             return
4948
4949         # Do not introduce or remove backslashes in raw strings
4950         new_body = body
4951     else:
4952         # remove unnecessary escapes
4953         new_body = sub_twice(escaped_new_quote, rf"\1\2{new_quote}", body)
4954         if body != new_body:
4955             # Consider the string without unnecessary escapes as the original
4956             body = new_body
4957             leaf.value = f"{prefix}{orig_quote}{body}{orig_quote}"
4958         new_body = sub_twice(escaped_orig_quote, rf"\1\2{orig_quote}", new_body)
4959         new_body = sub_twice(unescaped_new_quote, rf"\1\\{new_quote}", new_body)
4960     if "f" in prefix.casefold():
4961         matches = re.findall(
4962             r"""
4963             (?:[^{]|^)\{  # start of the string or a non-{ followed by a single {
4964                 ([^{].*?)  # contents of the brackets except if begins with {{
4965             \}(?:[^}]|$)  # A } followed by end of the string or a non-}
4966             """,
4967             new_body,
4968             re.VERBOSE,
4969         )
4970         for m in matches:
4971             if "\\" in str(m):
4972                 # Do not introduce backslashes in interpolated expressions
4973                 return
4974
4975     if new_quote == '"""' and new_body[-1:] == '"':
4976         # edge case:
4977         new_body = new_body[:-1] + '\\"'
4978     orig_escape_count = body.count("\\")
4979     new_escape_count = new_body.count("\\")
4980     if new_escape_count > orig_escape_count:
4981         return  # Do not introduce more escaping
4982
4983     if new_escape_count == orig_escape_count and orig_quote == '"':
4984         return  # Prefer double quotes
4985
4986     leaf.value = f"{prefix}{new_quote}{new_body}{new_quote}"
4987
4988
4989 def normalize_numeric_literal(leaf: Leaf) -> None:
4990     """Normalizes numeric (float, int, and complex) literals.
4991
4992     All letters used in the representation are normalized to lowercase (except
4993     in Python 2 long literals).
4994     """
4995     text = leaf.value.lower()
4996     if text.startswith(("0o", "0b")):
4997         # Leave octal and binary literals alone.
4998         pass
4999     elif text.startswith("0x"):
5000         # Change hex literals to upper case.
5001         before, after = text[:2], text[2:]
5002         text = f"{before}{after.upper()}"
5003     elif "e" in text:
5004         before, after = text.split("e")
5005         sign = ""
5006         if after.startswith("-"):
5007             after = after[1:]
5008             sign = "-"
5009         elif after.startswith("+"):
5010             after = after[1:]
5011         before = format_float_or_int_string(before)
5012         text = f"{before}e{sign}{after}"
5013     elif text.endswith(("j", "l")):
5014         number = text[:-1]
5015         suffix = text[-1]
5016         # Capitalize in "2L" because "l" looks too similar to "1".
5017         if suffix == "l":
5018             suffix = "L"
5019         text = f"{format_float_or_int_string(number)}{suffix}"
5020     else:
5021         text = format_float_or_int_string(text)
5022     leaf.value = text
5023
5024
5025 def format_float_or_int_string(text: str) -> str:
5026     """Formats a float string like "1.0"."""
5027     if "." not in text:
5028         return text
5029
5030     before, after = text.split(".")
5031     return f"{before or 0}.{after or 0}"
5032
5033
5034 def normalize_invisible_parens(node: Node, parens_after: Set[str]) -> None:
5035     """Make existing optional parentheses invisible or create new ones.
5036
5037     `parens_after` is a set of string leaf values immediately after which parens
5038     should be put.
5039
5040     Standardizes on visible parentheses for single-element tuples, and keeps
5041     existing visible parentheses for other tuples and generator expressions.
5042     """
5043     for pc in list_comments(node.prefix, is_endmarker=False):
5044         if pc.value in FMT_OFF:
5045             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
5046             return
5047     check_lpar = False
5048     for index, child in enumerate(list(node.children)):
5049         # Fixes a bug where invisible parens are not properly stripped from
5050         # assignment statements that contain type annotations.
5051         if isinstance(child, Node) and child.type == syms.annassign:
5052             normalize_invisible_parens(child, parens_after=parens_after)
5053
5054         # Add parentheses around long tuple unpacking in assignments.
5055         if (
5056             index == 0
5057             and isinstance(child, Node)
5058             and child.type == syms.testlist_star_expr
5059         ):
5060             check_lpar = True
5061
5062         if check_lpar:
5063             if is_walrus_assignment(child):
5064                 continue
5065
5066             if child.type == syms.atom:
5067                 if maybe_make_parens_invisible_in_atom(child, parent=node):
5068                     wrap_in_parentheses(node, child, visible=False)
5069             elif is_one_tuple(child):
5070                 wrap_in_parentheses(node, child, visible=True)
5071             elif node.type == syms.import_from:
5072                 # "import from" nodes store parentheses directly as part of
5073                 # the statement
5074                 if child.type == token.LPAR:
5075                     # make parentheses invisible
5076                     child.value = ""  # type: ignore
5077                     node.children[-1].value = ""  # type: ignore
5078                 elif child.type != token.STAR:
5079                     # insert invisible parentheses
5080                     node.insert_child(index, Leaf(token.LPAR, ""))
5081                     node.append_child(Leaf(token.RPAR, ""))
5082                 break
5083
5084             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
5085                 wrap_in_parentheses(node, child, visible=False)
5086
5087         check_lpar = isinstance(child, Leaf) and child.value in parens_after
5088
5089
5090 def normalize_fmt_off(node: Node) -> None:
5091     """Convert content between `# fmt: off`/`# fmt: on` into standalone comments."""
5092     try_again = True
5093     while try_again:
5094         try_again = convert_one_fmt_off_pair(node)
5095
5096
5097 def convert_one_fmt_off_pair(node: Node) -> bool:
5098     """Convert content of a single `# fmt: off`/`# fmt: on` into a standalone comment.
5099
5100     Returns True if a pair was converted.
5101     """
5102     for leaf in node.leaves():
5103         previous_consumed = 0
5104         for comment in list_comments(leaf.prefix, is_endmarker=False):
5105             if comment.value in FMT_OFF:
5106                 # We only want standalone comments. If there's no previous leaf or
5107                 # the previous leaf is indentation, it's a standalone comment in
5108                 # disguise.
5109                 if comment.type != STANDALONE_COMMENT:
5110                     prev = preceding_leaf(leaf)
5111                     if prev and prev.type not in WHITESPACE:
5112                         continue
5113
5114                 ignored_nodes = list(generate_ignored_nodes(leaf))
5115                 if not ignored_nodes:
5116                     continue
5117
5118                 first = ignored_nodes[0]  # Can be a container node with the `leaf`.
5119                 parent = first.parent
5120                 prefix = first.prefix
5121                 first.prefix = prefix[comment.consumed :]
5122                 hidden_value = (
5123                     comment.value + "\n" + "".join(str(n) for n in ignored_nodes)
5124                 )
5125                 if hidden_value.endswith("\n"):
5126                     # That happens when one of the `ignored_nodes` ended with a NEWLINE
5127                     # leaf (possibly followed by a DEDENT).
5128                     hidden_value = hidden_value[:-1]
5129                 first_idx: Optional[int] = None
5130                 for ignored in ignored_nodes:
5131                     index = ignored.remove()
5132                     if first_idx is None:
5133                         first_idx = index
5134                 assert parent is not None, "INTERNAL ERROR: fmt: on/off handling (1)"
5135                 assert first_idx is not None, "INTERNAL ERROR: fmt: on/off handling (2)"
5136                 parent.insert_child(
5137                     first_idx,
5138                     Leaf(
5139                         STANDALONE_COMMENT,
5140                         hidden_value,
5141                         prefix=prefix[:previous_consumed] + "\n" * comment.newlines,
5142                     ),
5143                 )
5144                 return True
5145
5146             previous_consumed = comment.consumed
5147
5148     return False
5149
5150
5151 def generate_ignored_nodes(leaf: Leaf) -> Iterator[LN]:
5152     """Starting from the container of `leaf`, generate all leaves until `# fmt: on`.
5153
5154     Stops at the end of the block.
5155     """
5156     container: Optional[LN] = container_of(leaf)
5157     while container is not None and container.type != token.ENDMARKER:
5158         if fmt_on(container):
5159             return
5160
5161         # fix for fmt: on in children
5162         if contains_fmt_on_at_column(container, leaf.column):
5163             for child in container.children:
5164                 if contains_fmt_on_at_column(child, leaf.column):
5165                     return
5166                 yield child
5167         else:
5168             yield container
5169             container = container.next_sibling
5170
5171
5172 def fmt_on(container: LN) -> bool:
5173     is_fmt_on = False
5174     for comment in list_comments(container.prefix, is_endmarker=False):
5175         if comment.value in FMT_ON:
5176             is_fmt_on = True
5177         elif comment.value in FMT_OFF:
5178             is_fmt_on = False
5179     return is_fmt_on
5180
5181
5182 def contains_fmt_on_at_column(container: LN, column: int) -> bool:
5183     for child in container.children:
5184         if (
5185             isinstance(child, Node)
5186             and first_leaf_column(child) == column
5187             or isinstance(child, Leaf)
5188             and child.column == column
5189         ):
5190             if fmt_on(child):
5191                 return True
5192
5193     return False
5194
5195
5196 def first_leaf_column(node: Node) -> Optional[int]:
5197     for child in node.children:
5198         if isinstance(child, Leaf):
5199             return child.column
5200     return None
5201
5202
5203 def maybe_make_parens_invisible_in_atom(node: LN, parent: LN) -> bool:
5204     """If it's safe, make the parens in the atom `node` invisible, recursively.
5205     Additionally, remove repeated, adjacent invisible parens from the atom `node`
5206     as they are redundant.
5207
5208     Returns whether the node should itself be wrapped in invisible parentheses.
5209
5210     """
5211     if (
5212         node.type != syms.atom
5213         or is_empty_tuple(node)
5214         or is_one_tuple(node)
5215         or (is_yield(node) and parent.type != syms.expr_stmt)
5216         or max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
5217     ):
5218         return False
5219
5220     first = node.children[0]
5221     last = node.children[-1]
5222     if first.type == token.LPAR and last.type == token.RPAR:
5223         middle = node.children[1]
5224         # make parentheses invisible
5225         first.value = ""  # type: ignore
5226         last.value = ""  # type: ignore
5227         maybe_make_parens_invisible_in_atom(middle, parent=parent)
5228
5229         if is_atom_with_invisible_parens(middle):
5230             # Strip the invisible parens from `middle` by replacing
5231             # it with the child in-between the invisible parens
5232             middle.replace(middle.children[1])
5233
5234         return False
5235
5236     return True
5237
5238
5239 def is_atom_with_invisible_parens(node: LN) -> bool:
5240     """Given a `LN`, determines whether it's an atom `node` with invisible
5241     parens. Useful in dedupe-ing and normalizing parens.
5242     """
5243     if isinstance(node, Leaf) or node.type != syms.atom:
5244         return False
5245
5246     first, last = node.children[0], node.children[-1]
5247     return (
5248         isinstance(first, Leaf)
5249         and first.type == token.LPAR
5250         and first.value == ""
5251         and isinstance(last, Leaf)
5252         and last.type == token.RPAR
5253         and last.value == ""
5254     )
5255
5256
5257 def is_empty_tuple(node: LN) -> bool:
5258     """Return True if `node` holds an empty tuple."""
5259     return (
5260         node.type == syms.atom
5261         and len(node.children) == 2
5262         and node.children[0].type == token.LPAR
5263         and node.children[1].type == token.RPAR
5264     )
5265
5266
5267 def unwrap_singleton_parenthesis(node: LN) -> Optional[LN]:
5268     """Returns `wrapped` if `node` is of the shape ( wrapped ).
5269
5270     Parenthesis can be optional. Returns None otherwise"""
5271     if len(node.children) != 3:
5272         return None
5273
5274     lpar, wrapped, rpar = node.children
5275     if not (lpar.type == token.LPAR and rpar.type == token.RPAR):
5276         return None
5277
5278     return wrapped
5279
5280
5281 def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
5282     """Wrap `child` in parentheses.
5283
5284     This replaces `child` with an atom holding the parentheses and the old
5285     child.  That requires moving the prefix.
5286
5287     If `visible` is False, the leaves will be valueless (and thus invisible).
5288     """
5289     lpar = Leaf(token.LPAR, "(" if visible else "")
5290     rpar = Leaf(token.RPAR, ")" if visible else "")
5291     prefix = child.prefix
5292     child.prefix = ""
5293     index = child.remove() or 0
5294     new_child = Node(syms.atom, [lpar, child, rpar])
5295     new_child.prefix = prefix
5296     parent.insert_child(index, new_child)
5297
5298
5299 def is_one_tuple(node: LN) -> bool:
5300     """Return True if `node` holds a tuple with one element, with or without parens."""
5301     if node.type == syms.atom:
5302         gexp = unwrap_singleton_parenthesis(node)
5303         if gexp is None or gexp.type != syms.testlist_gexp:
5304             return False
5305
5306         return len(gexp.children) == 2 and gexp.children[1].type == token.COMMA
5307
5308     return (
5309         node.type in IMPLICIT_TUPLE
5310         and len(node.children) == 2
5311         and node.children[1].type == token.COMMA
5312     )
5313
5314
5315 def is_walrus_assignment(node: LN) -> bool:
5316     """Return True iff `node` is of the shape ( test := test )"""
5317     inner = unwrap_singleton_parenthesis(node)
5318     return inner is not None and inner.type == syms.namedexpr_test
5319
5320
5321 def is_yield(node: LN) -> bool:
5322     """Return True if `node` holds a `yield` or `yield from` expression."""
5323     if node.type == syms.yield_expr:
5324         return True
5325
5326     if node.type == token.NAME and node.value == "yield":  # type: ignore
5327         return True
5328
5329     if node.type != syms.atom:
5330         return False
5331
5332     if len(node.children) != 3:
5333         return False
5334
5335     lpar, expr, rpar = node.children
5336     if lpar.type == token.LPAR and rpar.type == token.RPAR:
5337         return is_yield(expr)
5338
5339     return False
5340
5341
5342 def is_vararg(leaf: Leaf, within: Set[NodeType]) -> bool:
5343     """Return True if `leaf` is a star or double star in a vararg or kwarg.
5344
5345     If `within` includes VARARGS_PARENTS, this applies to function signatures.
5346     If `within` includes UNPACKING_PARENTS, it applies to right hand-side
5347     extended iterable unpacking (PEP 3132) and additional unpacking
5348     generalizations (PEP 448).
5349     """
5350     if leaf.type not in VARARGS_SPECIALS or not leaf.parent:
5351         return False
5352
5353     p = leaf.parent
5354     if p.type == syms.star_expr:
5355         # Star expressions are also used as assignment targets in extended
5356         # iterable unpacking (PEP 3132).  See what its parent is instead.
5357         if not p.parent:
5358             return False
5359
5360         p = p.parent
5361
5362     return p.type in within
5363
5364
5365 def is_multiline_string(leaf: Leaf) -> bool:
5366     """Return True if `leaf` is a multiline string that actually spans many lines."""
5367     return has_triple_quotes(leaf.value) and "\n" in leaf.value
5368
5369
5370 def is_stub_suite(node: Node) -> bool:
5371     """Return True if `node` is a suite with a stub body."""
5372     if (
5373         len(node.children) != 4
5374         or node.children[0].type != token.NEWLINE
5375         or node.children[1].type != token.INDENT
5376         or node.children[3].type != token.DEDENT
5377     ):
5378         return False
5379
5380     return is_stub_body(node.children[2])
5381
5382
5383 def is_stub_body(node: LN) -> bool:
5384     """Return True if `node` is a simple statement containing an ellipsis."""
5385     if not isinstance(node, Node) or node.type != syms.simple_stmt:
5386         return False
5387
5388     if len(node.children) != 2:
5389         return False
5390
5391     child = node.children[0]
5392     return (
5393         child.type == syms.atom
5394         and len(child.children) == 3
5395         and all(leaf == Leaf(token.DOT, ".") for leaf in child.children)
5396     )
5397
5398
5399 def max_delimiter_priority_in_atom(node: LN) -> Priority:
5400     """Return maximum delimiter priority inside `node`.
5401
5402     This is specific to atoms with contents contained in a pair of parentheses.
5403     If `node` isn't an atom or there are no enclosing parentheses, returns 0.
5404     """
5405     if node.type != syms.atom:
5406         return 0
5407
5408     first = node.children[0]
5409     last = node.children[-1]
5410     if not (first.type == token.LPAR and last.type == token.RPAR):
5411         return 0
5412
5413     bt = BracketTracker()
5414     for c in node.children[1:-1]:
5415         if isinstance(c, Leaf):
5416             bt.mark(c)
5417         else:
5418             for leaf in c.leaves():
5419                 bt.mark(leaf)
5420     try:
5421         return bt.max_delimiter_priority()
5422
5423     except ValueError:
5424         return 0
5425
5426
5427 def ensure_visible(leaf: Leaf) -> None:
5428     """Make sure parentheses are visible.
5429
5430     They could be invisible as part of some statements (see
5431     :func:`normalize_invisible_parens` and :func:`visit_import_from`).
5432     """
5433     if leaf.type == token.LPAR:
5434         leaf.value = "("
5435     elif leaf.type == token.RPAR:
5436         leaf.value = ")"
5437
5438
5439 def should_explode(line: Line, opening_bracket: Leaf) -> bool:
5440     """Should `line` immediately be split with `delimiter_split()` after RHS?"""
5441
5442     if not (
5443         opening_bracket.parent
5444         and opening_bracket.parent.type in {syms.atom, syms.import_from}
5445         and opening_bracket.value in "[{("
5446     ):
5447         return False
5448
5449     try:
5450         last_leaf = line.leaves[-1]
5451         exclude = {id(last_leaf)} if last_leaf.type == token.COMMA else set()
5452         max_priority = line.bracket_tracker.max_delimiter_priority(exclude=exclude)
5453     except (IndexError, ValueError):
5454         return False
5455
5456     return max_priority == COMMA_PRIORITY
5457
5458
5459 def get_features_used(node: Node) -> Set[Feature]:
5460     """Return a set of (relatively) new Python features used in this file.
5461
5462     Currently looking for:
5463     - f-strings;
5464     - underscores in numeric literals;
5465     - trailing commas after * or ** in function signatures and calls;
5466     - positional only arguments in function signatures and lambdas;
5467     """
5468     features: Set[Feature] = set()
5469     for n in node.pre_order():
5470         if n.type == token.STRING:
5471             value_head = n.value[:2]  # type: ignore
5472             if value_head in {'f"', 'F"', "f'", "F'", "rf", "fr", "RF", "FR"}:
5473                 features.add(Feature.F_STRINGS)
5474
5475         elif n.type == token.NUMBER:
5476             if "_" in n.value:  # type: ignore
5477                 features.add(Feature.NUMERIC_UNDERSCORES)
5478
5479         elif n.type == token.SLASH:
5480             if n.parent and n.parent.type in {syms.typedargslist, syms.arglist}:
5481                 features.add(Feature.POS_ONLY_ARGUMENTS)
5482
5483         elif n.type == token.COLONEQUAL:
5484             features.add(Feature.ASSIGNMENT_EXPRESSIONS)
5485
5486         elif (
5487             n.type in {syms.typedargslist, syms.arglist}
5488             and n.children
5489             and n.children[-1].type == token.COMMA
5490         ):
5491             if n.type == syms.typedargslist:
5492                 feature = Feature.TRAILING_COMMA_IN_DEF
5493             else:
5494                 feature = Feature.TRAILING_COMMA_IN_CALL
5495
5496             for ch in n.children:
5497                 if ch.type in STARS:
5498                     features.add(feature)
5499
5500                 if ch.type == syms.argument:
5501                     for argch in ch.children:
5502                         if argch.type in STARS:
5503                             features.add(feature)
5504
5505     return features
5506
5507
5508 def detect_target_versions(node: Node) -> Set[TargetVersion]:
5509     """Detect the version to target based on the nodes used."""
5510     features = get_features_used(node)
5511     return {
5512         version for version in TargetVersion if features <= VERSION_TO_FEATURES[version]
5513     }
5514
5515
5516 def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[LeafID]]:
5517     """Generate sets of closing bracket IDs that should be omitted in a RHS.
5518
5519     Brackets can be omitted if the entire trailer up to and including
5520     a preceding closing bracket fits in one line.
5521
5522     Yielded sets are cumulative (contain results of previous yields, too).  First
5523     set is empty.
5524     """
5525
5526     omit: Set[LeafID] = set()
5527     yield omit
5528
5529     length = 4 * line.depth
5530     opening_bracket: Optional[Leaf] = None
5531     closing_bracket: Optional[Leaf] = None
5532     inner_brackets: Set[LeafID] = set()
5533     for index, leaf, leaf_length in enumerate_with_length(line, reversed=True):
5534         length += leaf_length
5535         if length > line_length:
5536             break
5537
5538         has_inline_comment = leaf_length > len(leaf.value) + len(leaf.prefix)
5539         if leaf.type == STANDALONE_COMMENT or has_inline_comment:
5540             break
5541
5542         if opening_bracket:
5543             if leaf is opening_bracket:
5544                 opening_bracket = None
5545             elif leaf.type in CLOSING_BRACKETS:
5546                 inner_brackets.add(id(leaf))
5547         elif leaf.type in CLOSING_BRACKETS:
5548             if index > 0 and line.leaves[index - 1].type in OPENING_BRACKETS:
5549                 # Empty brackets would fail a split so treat them as "inner"
5550                 # brackets (e.g. only add them to the `omit` set if another
5551                 # pair of brackets was good enough.
5552                 inner_brackets.add(id(leaf))
5553                 continue
5554
5555             if closing_bracket:
5556                 omit.add(id(closing_bracket))
5557                 omit.update(inner_brackets)
5558                 inner_brackets.clear()
5559                 yield omit
5560
5561             if leaf.value:
5562                 opening_bracket = leaf.opening_bracket
5563                 closing_bracket = leaf
5564
5565
5566 def get_future_imports(node: Node) -> Set[str]:
5567     """Return a set of __future__ imports in the file."""
5568     imports: Set[str] = set()
5569
5570     def get_imports_from_children(children: List[LN]) -> Generator[str, None, None]:
5571         for child in children:
5572             if isinstance(child, Leaf):
5573                 if child.type == token.NAME:
5574                     yield child.value
5575
5576             elif child.type == syms.import_as_name:
5577                 orig_name = child.children[0]
5578                 assert isinstance(orig_name, Leaf), "Invalid syntax parsing imports"
5579                 assert orig_name.type == token.NAME, "Invalid syntax parsing imports"
5580                 yield orig_name.value
5581
5582             elif child.type == syms.import_as_names:
5583                 yield from get_imports_from_children(child.children)
5584
5585             else:
5586                 raise AssertionError("Invalid syntax parsing imports")
5587
5588     for child in node.children:
5589         if child.type != syms.simple_stmt:
5590             break
5591
5592         first_child = child.children[0]
5593         if isinstance(first_child, Leaf):
5594             # Continue looking if we see a docstring; otherwise stop.
5595             if (
5596                 len(child.children) == 2
5597                 and first_child.type == token.STRING
5598                 and child.children[1].type == token.NEWLINE
5599             ):
5600                 continue
5601
5602             break
5603
5604         elif first_child.type == syms.import_from:
5605             module_name = first_child.children[1]
5606             if not isinstance(module_name, Leaf) or module_name.value != "__future__":
5607                 break
5608
5609             imports |= set(get_imports_from_children(first_child.children[3:]))
5610         else:
5611             break
5612
5613     return imports
5614
5615
5616 @lru_cache()
5617 def get_gitignore(root: Path) -> PathSpec:
5618     """ Return a PathSpec matching gitignore content if present."""
5619     gitignore = root / ".gitignore"
5620     lines: List[str] = []
5621     if gitignore.is_file():
5622         with gitignore.open() as gf:
5623             lines = gf.readlines()
5624     return PathSpec.from_lines("gitwildmatch", lines)
5625
5626
5627 def gen_python_files_in_dir(
5628     path: Path,
5629     root: Path,
5630     include: Pattern[str],
5631     exclude: Pattern[str],
5632     report: "Report",
5633     gitignore: PathSpec,
5634 ) -> Iterator[Path]:
5635     """Generate all files under `path` whose paths are not excluded by the
5636     `exclude` regex, but are included by the `include` regex.
5637
5638     Symbolic links pointing outside of the `root` directory are ignored.
5639
5640     `report` is where output about exclusions goes.
5641     """
5642     assert root.is_absolute(), f"INTERNAL ERROR: `root` must be absolute but is {root}"
5643     for child in path.iterdir():
5644         # First ignore files matching .gitignore
5645         if gitignore.match_file(child.as_posix()):
5646             report.path_ignored(child, "matches the .gitignore file content")
5647             continue
5648
5649         # Then ignore with `exclude` option.
5650         try:
5651             normalized_path = "/" + child.resolve().relative_to(root).as_posix()
5652         except OSError as e:
5653             report.path_ignored(child, f"cannot be read because {e}")
5654             continue
5655
5656         except ValueError:
5657             if child.is_symlink():
5658                 report.path_ignored(
5659                     child, f"is a symbolic link that points outside {root}"
5660                 )
5661                 continue
5662
5663             raise
5664
5665         if child.is_dir():
5666             normalized_path += "/"
5667
5668         exclude_match = exclude.search(normalized_path)
5669         if exclude_match and exclude_match.group(0):
5670             report.path_ignored(child, "matches the --exclude regular expression")
5671             continue
5672
5673         if child.is_dir():
5674             yield from gen_python_files_in_dir(
5675                 child, root, include, exclude, report, gitignore
5676             )
5677
5678         elif child.is_file():
5679             include_match = include.search(normalized_path)
5680             if include_match:
5681                 yield child
5682
5683
5684 @lru_cache()
5685 def find_project_root(srcs: Iterable[str]) -> Path:
5686     """Return a directory containing .git, .hg, or pyproject.toml.
5687
5688     That directory can be one of the directories passed in `srcs` or their
5689     common parent.
5690
5691     If no directory in the tree contains a marker that would specify it's the
5692     project root, the root of the file system is returned.
5693     """
5694     if not srcs:
5695         return Path("/").resolve()
5696
5697     common_base = min(Path(src).resolve() for src in srcs)
5698     if common_base.is_dir():
5699         # Append a fake file so `parents` below returns `common_base_dir`, too.
5700         common_base /= "fake-file"
5701     for directory in common_base.parents:
5702         if (directory / ".git").exists():
5703             return directory
5704
5705         if (directory / ".hg").is_dir():
5706             return directory
5707
5708         if (directory / "pyproject.toml").is_file():
5709             return directory
5710
5711     return directory
5712
5713
5714 @dataclass
5715 class Report:
5716     """Provides a reformatting counter. Can be rendered with `str(report)`."""
5717
5718     check: bool = False
5719     diff: bool = False
5720     quiet: bool = False
5721     verbose: bool = False
5722     change_count: int = 0
5723     same_count: int = 0
5724     failure_count: int = 0
5725
5726     def done(self, src: Path, changed: Changed) -> None:
5727         """Increment the counter for successful reformatting. Write out a message."""
5728         if changed is Changed.YES:
5729             reformatted = "would reformat" if self.check or self.diff else "reformatted"
5730             if self.verbose or not self.quiet:
5731                 out(f"{reformatted} {src}")
5732             self.change_count += 1
5733         else:
5734             if self.verbose:
5735                 if changed is Changed.NO:
5736                     msg = f"{src} already well formatted, good job."
5737                 else:
5738                     msg = f"{src} wasn't modified on disk since last run."
5739                 out(msg, bold=False)
5740             self.same_count += 1
5741
5742     def failed(self, src: Path, message: str) -> None:
5743         """Increment the counter for failed reformatting. Write out a message."""
5744         err(f"error: cannot format {src}: {message}")
5745         self.failure_count += 1
5746
5747     def path_ignored(self, path: Path, message: str) -> None:
5748         if self.verbose:
5749             out(f"{path} ignored: {message}", bold=False)
5750
5751     @property
5752     def return_code(self) -> int:
5753         """Return the exit code that the app should use.
5754
5755         This considers the current state of changed files and failures:
5756         - if there were any failures, return 123;
5757         - if any files were changed and --check is being used, return 1;
5758         - otherwise return 0.
5759         """
5760         # According to http://tldp.org/LDP/abs/html/exitcodes.html starting with
5761         # 126 we have special return codes reserved by the shell.
5762         if self.failure_count:
5763             return 123
5764
5765         elif self.change_count and self.check:
5766             return 1
5767
5768         return 0
5769
5770     def __str__(self) -> str:
5771         """Render a color report of the current state.
5772
5773         Use `click.unstyle` to remove colors.
5774         """
5775         if self.check or self.diff:
5776             reformatted = "would be reformatted"
5777             unchanged = "would be left unchanged"
5778             failed = "would fail to reformat"
5779         else:
5780             reformatted = "reformatted"
5781             unchanged = "left unchanged"
5782             failed = "failed to reformat"
5783         report = []
5784         if self.change_count:
5785             s = "s" if self.change_count > 1 else ""
5786             report.append(
5787                 click.style(f"{self.change_count} file{s} {reformatted}", bold=True)
5788             )
5789         if self.same_count:
5790             s = "s" if self.same_count > 1 else ""
5791             report.append(f"{self.same_count} file{s} {unchanged}")
5792         if self.failure_count:
5793             s = "s" if self.failure_count > 1 else ""
5794             report.append(
5795                 click.style(f"{self.failure_count} file{s} {failed}", fg="red")
5796             )
5797         return ", ".join(report) + "."
5798
5799
5800 def parse_ast(src: str) -> Union[ast.AST, ast3.AST, ast27.AST]:
5801     filename = "<unknown>"
5802     if sys.version_info >= (3, 8):
5803         # TODO: support Python 4+ ;)
5804         for minor_version in range(sys.version_info[1], 4, -1):
5805             try:
5806                 return ast.parse(src, filename, feature_version=(3, minor_version))
5807             except SyntaxError:
5808                 continue
5809     else:
5810         for feature_version in (7, 6):
5811             try:
5812                 return ast3.parse(src, filename, feature_version=feature_version)
5813             except SyntaxError:
5814                 continue
5815
5816     return ast27.parse(src)
5817
5818
5819 def _fixup_ast_constants(
5820     node: Union[ast.AST, ast3.AST, ast27.AST]
5821 ) -> Union[ast.AST, ast3.AST, ast27.AST]:
5822     """Map ast nodes deprecated in 3.8 to Constant."""
5823     if isinstance(node, (ast.Str, ast3.Str, ast27.Str, ast.Bytes, ast3.Bytes)):
5824         return ast.Constant(value=node.s)
5825
5826     if isinstance(node, (ast.Num, ast3.Num, ast27.Num)):
5827         return ast.Constant(value=node.n)
5828
5829     if isinstance(node, (ast.NameConstant, ast3.NameConstant)):
5830         return ast.Constant(value=node.value)
5831
5832     return node
5833
5834
5835 def _stringify_ast(
5836     node: Union[ast.AST, ast3.AST, ast27.AST], depth: int = 0
5837 ) -> Iterator[str]:
5838     """Simple visitor generating strings to compare ASTs by content."""
5839
5840     node = _fixup_ast_constants(node)
5841
5842     yield f"{'  ' * depth}{node.__class__.__name__}("
5843
5844     for field in sorted(node._fields):  # noqa: F402
5845         # TypeIgnore has only one field 'lineno' which breaks this comparison
5846         type_ignore_classes = (ast3.TypeIgnore, ast27.TypeIgnore)
5847         if sys.version_info >= (3, 8):
5848             type_ignore_classes += (ast.TypeIgnore,)
5849         if isinstance(node, type_ignore_classes):
5850             break
5851
5852         try:
5853             value = getattr(node, field)
5854         except AttributeError:
5855             continue
5856
5857         yield f"{'  ' * (depth+1)}{field}="
5858
5859         if isinstance(value, list):
5860             for item in value:
5861                 # Ignore nested tuples within del statements, because we may insert
5862                 # parentheses and they change the AST.
5863                 if (
5864                     field == "targets"
5865                     and isinstance(node, (ast.Delete, ast3.Delete, ast27.Delete))
5866                     and isinstance(item, (ast.Tuple, ast3.Tuple, ast27.Tuple))
5867                 ):
5868                     for item in item.elts:
5869                         yield from _stringify_ast(item, depth + 2)
5870
5871                 elif isinstance(item, (ast.AST, ast3.AST, ast27.AST)):
5872                     yield from _stringify_ast(item, depth + 2)
5873
5874         elif isinstance(value, (ast.AST, ast3.AST, ast27.AST)):
5875             yield from _stringify_ast(value, depth + 2)
5876
5877         else:
5878             # Constant strings may be indented across newlines, if they are
5879             # docstrings; fold spaces after newlines when comparing
5880             if (
5881                 isinstance(node, ast.Constant)
5882                 and field == "value"
5883                 and isinstance(value, str)
5884             ):
5885                 normalized = re.sub(r"\n[ \t]+", "\n ", value)
5886             else:
5887                 normalized = value
5888             yield f"{'  ' * (depth+2)}{normalized!r},  # {value.__class__.__name__}"
5889
5890     yield f"{'  ' * depth})  # /{node.__class__.__name__}"
5891
5892
5893 def assert_equivalent(src: str, dst: str) -> None:
5894     """Raise AssertionError if `src` and `dst` aren't equivalent."""
5895     try:
5896         src_ast = parse_ast(src)
5897     except Exception as exc:
5898         raise AssertionError(
5899             "cannot use --safe with this file; failed to parse source file.  AST"
5900             f" error message: {exc}"
5901         )
5902
5903     try:
5904         dst_ast = parse_ast(dst)
5905     except Exception as exc:
5906         log = dump_to_file("".join(traceback.format_tb(exc.__traceback__)), dst)
5907         raise AssertionError(
5908             f"INTERNAL ERROR: Black produced invalid code: {exc}. Please report a bug"
5909             " on https://github.com/psf/black/issues.  This invalid output might be"
5910             f" helpful: {log}"
5911         ) from None
5912
5913     src_ast_str = "\n".join(_stringify_ast(src_ast))
5914     dst_ast_str = "\n".join(_stringify_ast(dst_ast))
5915     if src_ast_str != dst_ast_str:
5916         log = dump_to_file(diff(src_ast_str, dst_ast_str, "src", "dst"))
5917         raise AssertionError(
5918             "INTERNAL ERROR: Black produced code that is not equivalent to the"
5919             " source.  Please report a bug on https://github.com/psf/black/issues. "
5920             f" This diff might be helpful: {log}"
5921         ) from None
5922
5923
5924 def assert_stable(src: str, dst: str, mode: Mode) -> None:
5925     """Raise AssertionError if `dst` reformats differently the second time."""
5926     newdst = format_str(dst, mode=mode)
5927     if dst != newdst:
5928         log = dump_to_file(
5929             diff(src, dst, "source", "first pass"),
5930             diff(dst, newdst, "first pass", "second pass"),
5931         )
5932         raise AssertionError(
5933             "INTERNAL ERROR: Black produced different code on the second pass of the"
5934             " formatter.  Please report a bug on https://github.com/psf/black/issues."
5935             f"  This diff might be helpful: {log}"
5936         ) from None
5937
5938
5939 @mypyc_attr(patchable=True)
5940 def dump_to_file(*output: str) -> str:
5941     """Dump `output` to a temporary file. Return path to the file."""
5942     with tempfile.NamedTemporaryFile(
5943         mode="w", prefix="blk_", suffix=".log", delete=False, encoding="utf8"
5944     ) as f:
5945         for lines in output:
5946             f.write(lines)
5947             if lines and lines[-1] != "\n":
5948                 f.write("\n")
5949     return f.name
5950
5951
5952 @contextmanager
5953 def nullcontext() -> Iterator[None]:
5954     """Return an empty context manager.
5955
5956     To be used like `nullcontext` in Python 3.7.
5957     """
5958     yield
5959
5960
5961 def diff(a: str, b: str, a_name: str, b_name: str) -> str:
5962     """Return a unified diff string between strings `a` and `b`."""
5963     import difflib
5964
5965     a_lines = [line + "\n" for line in a.splitlines()]
5966     b_lines = [line + "\n" for line in b.splitlines()]
5967     return "".join(
5968         difflib.unified_diff(a_lines, b_lines, fromfile=a_name, tofile=b_name, n=5)
5969     )
5970
5971
5972 def cancel(tasks: Iterable["asyncio.Task[Any]"]) -> None:
5973     """asyncio signal handler that cancels all `tasks` and reports to stderr."""
5974     err("Aborted!")
5975     for task in tasks:
5976         task.cancel()
5977
5978
5979 def shutdown(loop: asyncio.AbstractEventLoop) -> None:
5980     """Cancel all pending tasks on `loop`, wait for them, and close the loop."""
5981     try:
5982         if sys.version_info[:2] >= (3, 7):
5983             all_tasks = asyncio.all_tasks
5984         else:
5985             all_tasks = asyncio.Task.all_tasks
5986         # This part is borrowed from asyncio/runners.py in Python 3.7b2.
5987         to_cancel = [task for task in all_tasks(loop) if not task.done()]
5988         if not to_cancel:
5989             return
5990
5991         for task in to_cancel:
5992             task.cancel()
5993         loop.run_until_complete(
5994             asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
5995         )
5996     finally:
5997         # `concurrent.futures.Future` objects cannot be cancelled once they
5998         # are already running. There might be some when the `shutdown()` happened.
5999         # Silence their logger's spew about the event loop being closed.
6000         cf_logger = logging.getLogger("concurrent.futures")
6001         cf_logger.setLevel(logging.CRITICAL)
6002         loop.close()
6003
6004
6005 def sub_twice(regex: Pattern[str], replacement: str, original: str) -> str:
6006     """Replace `regex` with `replacement` twice on `original`.
6007
6008     This is used by string normalization to perform replaces on
6009     overlapping matches.
6010     """
6011     return regex.sub(replacement, regex.sub(replacement, original))
6012
6013
6014 def re_compile_maybe_verbose(regex: str) -> Pattern[str]:
6015     """Compile a regular expression string in `regex`.
6016
6017     If it contains newlines, use verbose mode.
6018     """
6019     if "\n" in regex:
6020         regex = "(?x)" + regex
6021     compiled: Pattern[str] = re.compile(regex)
6022     return compiled
6023
6024
6025 def enumerate_reversed(sequence: Sequence[T]) -> Iterator[Tuple[Index, T]]:
6026     """Like `reversed(enumerate(sequence))` if that were possible."""
6027     index = len(sequence) - 1
6028     for element in reversed(sequence):
6029         yield (index, element)
6030         index -= 1
6031
6032
6033 def enumerate_with_length(
6034     line: Line, reversed: bool = False
6035 ) -> Iterator[Tuple[Index, Leaf, int]]:
6036     """Return an enumeration of leaves with their length.
6037
6038     Stops prematurely on multiline strings and standalone comments.
6039     """
6040     op = cast(
6041         Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
6042         enumerate_reversed if reversed else enumerate,
6043     )
6044     for index, leaf in op(line.leaves):
6045         length = len(leaf.prefix) + len(leaf.value)
6046         if "\n" in leaf.value:
6047             return  # Multiline strings, we can't continue.
6048
6049         for comment in line.comments_after(leaf):
6050             length += len(comment.value)
6051
6052         yield index, leaf, length
6053
6054
6055 def is_line_short_enough(line: Line, *, line_length: int, line_str: str = "") -> bool:
6056     """Return True if `line` is no longer than `line_length`.
6057
6058     Uses the provided `line_str` rendering, if any, otherwise computes a new one.
6059     """
6060     if not line_str:
6061         line_str = line_to_string(line)
6062     return (
6063         len(line_str) <= line_length
6064         and "\n" not in line_str  # multiline strings
6065         and not line.contains_standalone_comments()
6066     )
6067
6068
6069 def can_be_split(line: Line) -> bool:
6070     """Return False if the line cannot be split *for sure*.
6071
6072     This is not an exhaustive search but a cheap heuristic that we can use to
6073     avoid some unfortunate formattings (mostly around wrapping unsplittable code
6074     in unnecessary parentheses).
6075     """
6076     leaves = line.leaves
6077     if len(leaves) < 2:
6078         return False
6079
6080     if leaves[0].type == token.STRING and leaves[1].type == token.DOT:
6081         call_count = 0
6082         dot_count = 0
6083         next = leaves[-1]
6084         for leaf in leaves[-2::-1]:
6085             if leaf.type in OPENING_BRACKETS:
6086                 if next.type not in CLOSING_BRACKETS:
6087                     return False
6088
6089                 call_count += 1
6090             elif leaf.type == token.DOT:
6091                 dot_count += 1
6092             elif leaf.type == token.NAME:
6093                 if not (next.type == token.DOT or next.type in OPENING_BRACKETS):
6094                     return False
6095
6096             elif leaf.type not in CLOSING_BRACKETS:
6097                 return False
6098
6099             if dot_count > 1 and call_count > 1:
6100                 return False
6101
6102     return True
6103
6104
6105 def can_omit_invisible_parens(line: Line, line_length: int) -> bool:
6106     """Does `line` have a shape safe to reformat without optional parens around it?
6107
6108     Returns True for only a subset of potentially nice looking formattings but
6109     the point is to not return false positives that end up producing lines that
6110     are too long.
6111     """
6112     bt = line.bracket_tracker
6113     if not bt.delimiters:
6114         # Without delimiters the optional parentheses are useless.
6115         return True
6116
6117     max_priority = bt.max_delimiter_priority()
6118     if bt.delimiter_count_with_priority(max_priority) > 1:
6119         # With more than one delimiter of a kind the optional parentheses read better.
6120         return False
6121
6122     if max_priority == DOT_PRIORITY:
6123         # A single stranded method call doesn't require optional parentheses.
6124         return True
6125
6126     assert len(line.leaves) >= 2, "Stranded delimiter"
6127
6128     first = line.leaves[0]
6129     second = line.leaves[1]
6130     penultimate = line.leaves[-2]
6131     last = line.leaves[-1]
6132
6133     # With a single delimiter, omit if the expression starts or ends with
6134     # a bracket.
6135     if first.type in OPENING_BRACKETS and second.type not in CLOSING_BRACKETS:
6136         remainder = False
6137         length = 4 * line.depth
6138         for _index, leaf, leaf_length in enumerate_with_length(line):
6139             if leaf.type in CLOSING_BRACKETS and leaf.opening_bracket is first:
6140                 remainder = True
6141             if remainder:
6142                 length += leaf_length
6143                 if length > line_length:
6144                     break
6145
6146                 if leaf.type in OPENING_BRACKETS:
6147                     # There are brackets we can further split on.
6148                     remainder = False
6149
6150         else:
6151             # checked the entire string and line length wasn't exceeded
6152             if len(line.leaves) == _index + 1:
6153                 return True
6154
6155         # Note: we are not returning False here because a line might have *both*
6156         # a leading opening bracket and a trailing closing bracket.  If the
6157         # opening bracket doesn't match our rule, maybe the closing will.
6158
6159     if (
6160         last.type == token.RPAR
6161         or last.type == token.RBRACE
6162         or (
6163             # don't use indexing for omitting optional parentheses;
6164             # it looks weird
6165             last.type == token.RSQB
6166             and last.parent
6167             and last.parent.type != syms.trailer
6168         )
6169     ):
6170         if penultimate.type in OPENING_BRACKETS:
6171             # Empty brackets don't help.
6172             return False
6173
6174         if is_multiline_string(first):
6175             # Additional wrapping of a multiline string in this situation is
6176             # unnecessary.
6177             return True
6178
6179         length = 4 * line.depth
6180         seen_other_brackets = False
6181         for _index, leaf, leaf_length in enumerate_with_length(line):
6182             length += leaf_length
6183             if leaf is last.opening_bracket:
6184                 if seen_other_brackets or length <= line_length:
6185                     return True
6186
6187             elif leaf.type in OPENING_BRACKETS:
6188                 # There are brackets we can further split on.
6189                 seen_other_brackets = True
6190
6191     return False
6192
6193
6194 def get_cache_file(mode: Mode) -> Path:
6195     return CACHE_DIR / f"cache.{mode.get_cache_key()}.pickle"
6196
6197
6198 def read_cache(mode: Mode) -> Cache:
6199     """Read the cache if it exists and is well formed.
6200
6201     If it is not well formed, the call to write_cache later should resolve the issue.
6202     """
6203     cache_file = get_cache_file(mode)
6204     if not cache_file.exists():
6205         return {}
6206
6207     with cache_file.open("rb") as fobj:
6208         try:
6209             cache: Cache = pickle.load(fobj)
6210         except (pickle.UnpicklingError, ValueError):
6211             return {}
6212
6213     return cache
6214
6215
6216 def get_cache_info(path: Path) -> CacheInfo:
6217     """Return the information used to check if a file is already formatted or not."""
6218     stat = path.stat()
6219     return stat.st_mtime, stat.st_size
6220
6221
6222 def filter_cached(cache: Cache, sources: Iterable[Path]) -> Tuple[Set[Path], Set[Path]]:
6223     """Split an iterable of paths in `sources` into two sets.
6224
6225     The first contains paths of files that modified on disk or are not in the
6226     cache. The other contains paths to non-modified files.
6227     """
6228     todo, done = set(), set()
6229     for src in sources:
6230         src = src.resolve()
6231         if cache.get(src) != get_cache_info(src):
6232             todo.add(src)
6233         else:
6234             done.add(src)
6235     return todo, done
6236
6237
6238 def write_cache(cache: Cache, sources: Iterable[Path], mode: Mode) -> None:
6239     """Update the cache file."""
6240     cache_file = get_cache_file(mode)
6241     try:
6242         CACHE_DIR.mkdir(parents=True, exist_ok=True)
6243         new_cache = {**cache, **{src.resolve(): get_cache_info(src) for src in sources}}
6244         with tempfile.NamedTemporaryFile(dir=str(cache_file.parent), delete=False) as f:
6245             pickle.dump(new_cache, f, protocol=4)
6246         os.replace(f.name, cache_file)
6247     except OSError:
6248         pass
6249
6250
6251 def patch_click() -> None:
6252     """Make Click not crash.
6253
6254     On certain misconfigured environments, Python 3 selects the ASCII encoding as the
6255     default which restricts paths that it can access during the lifetime of the
6256     application.  Click refuses to work in this scenario by raising a RuntimeError.
6257
6258     In case of Black the likelihood that non-ASCII characters are going to be used in
6259     file paths is minimal since it's Python source code.  Moreover, this crash was
6260     spurious on Python 3.7 thanks to PEP 538 and PEP 540.
6261     """
6262     try:
6263         from click import core
6264         from click import _unicodefun  # type: ignore
6265     except ModuleNotFoundError:
6266         return
6267
6268     for module in (core, _unicodefun):
6269         if hasattr(module, "_verify_python3_env"):
6270             module._verify_python3_env = lambda: None
6271
6272
6273 def patched_main() -> None:
6274     freeze_support()
6275     patch_click()
6276     main()
6277
6278
6279 def fix_docstring(docstring: str, prefix: str) -> str:
6280     # https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation
6281     if not docstring:
6282         return ""
6283     # Convert tabs to spaces (following the normal Python rules)
6284     # and split into a list of lines:
6285     lines = docstring.expandtabs().splitlines()
6286     # Determine minimum indentation (first line doesn't count):
6287     indent = sys.maxsize
6288     for line in lines[1:]:
6289         stripped = line.lstrip()
6290         if stripped:
6291             indent = min(indent, len(line) - len(stripped))
6292     # Remove indentation (first line is special):
6293     trimmed = [lines[0].strip()]
6294     if indent < sys.maxsize:
6295         last_line_idx = len(lines) - 2
6296         for i, line in enumerate(lines[1:]):
6297             stripped_line = line[indent:].rstrip()
6298             if stripped_line or i == last_line_idx:
6299                 trimmed.append(prefix + stripped_line)
6300             else:
6301                 trimmed.append("")
6302     # Return a single string:
6303     return "\n".join(trimmed)
6304
6305
6306 if __name__ == "__main__":
6307     patched_main()