src/black/lines.py

   1 import itertools
   2 import math
   3 import sys
   4 from dataclasses import dataclass, field
   5 from typing import (
   6     Callable,
   7     Dict,
   8     Iterator,
   9     List,
  10     Optional,
  11     Sequence,
  12     Tuple,
  13     TypeVar,
  14     Union,
  15     cast,
  16 )
  17
  18 from black.brackets import COMMA_PRIORITY, DOT_PRIORITY, BracketTracker
  19 from black.mode import Mode, Preview
  20 from black.nodes import (
  21     BRACKETS,
  22     CLOSING_BRACKETS,
  23     OPENING_BRACKETS,
  24     STANDALONE_COMMENT,
  25     TEST_DESCENDANTS,
  26     child_towards,
  27     is_import,
  28     is_multiline_string,
  29     is_one_sequence_between,
  30     is_type_comment,
  31     is_type_ignore_comment,
  32     is_with_or_async_with_stmt,
  33     replace_child,
  34     syms,
  35     whitespace,
  36 )
  37 from black.strings import str_width
  38 from blib2to3.pgen2 import token
  39 from blib2to3.pytree import Leaf, Node
  40
  41 # types
  42 T = TypeVar("T")
  43 Index = int
  44 LeafID = int
  45 LN = Union[Leaf, Node]
  46
  47
  48 @dataclass
  49 class Line:
  50     """Holds leaves and comments. Can be printed with `str(line)`."""
  51
  52     mode: Mode = field(repr=False)
  53     depth: int = 0
  54     leaves: List[Leaf] = field(default_factory=list)
  55     # keys ordered like `leaves`
  56     comments: Dict[LeafID, List[Leaf]] = field(default_factory=dict)
  57     bracket_tracker: BracketTracker = field(default_factory=BracketTracker)
  58     inside_brackets: bool = False
  59     should_split_rhs: bool = False
  60     magic_trailing_comma: Optional[Leaf] = None
  61
  62     def append(
  63         self, leaf: Leaf, preformatted: bool = False, track_bracket: bool = False
  64     ) -> None:
  65         """Add a new `leaf` to the end of the line.
  66
  67         Unless `preformatted` is True, the `leaf` will receive a new consistent
  68         whitespace prefix and metadata applied by :class:`BracketTracker`.
  69         Trailing commas are maybe removed, unpacked for loop variables are
  70         demoted from being delimiters.
  71
  72         Inline comments are put aside.
  73         """
  74         has_value = leaf.type in BRACKETS or bool(leaf.value.strip())
  75         if not has_value:
  76             return
  77
  78         if token.COLON == leaf.type and self.is_class_paren_empty:
  79             del self.leaves[-2:]
  80         if self.leaves and not preformatted:
  81             # Note: at this point leaf.prefix should be empty except for
  82             # imports, for which we only preserve newlines.
  83             leaf.prefix += whitespace(
  84                 leaf, complex_subscript=self.is_complex_subscript(leaf)
  85             )
  86         if self.inside_brackets or not preformatted or track_bracket:
  87             self.bracket_tracker.mark(leaf)
  88             if self.mode.magic_trailing_comma:
  89                 if self.has_magic_trailing_comma(leaf):
  90                     self.magic_trailing_comma = leaf
  91             elif self.has_magic_trailing_comma(leaf, ensure_removable=True):
  92                 self.remove_trailing_comma()
  93         if not self.append_comment(leaf):
  94             self.leaves.append(leaf)
  95
  96     def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
  97         """Like :func:`append()` but disallow invalid standalone comment structure.
  98
  99         Raises ValueError when any `leaf` is appended after a standalone comment
 100         or when a standalone comment is not the first leaf on the line.
 101         """
 102         if self.bracket_tracker.depth == 0:
 103             if self.is_comment:
 104                 raise ValueError("cannot append to standalone comments")
 105
 106             if self.leaves and leaf.type == STANDALONE_COMMENT:
 107                 raise ValueError(
 108                     "cannot append standalone comments to a populated line"
 109                 )
 110
 111         self.append(leaf, preformatted=preformatted)
 112
 113     @property
 114     def is_comment(self) -> bool:
 115         """Is this line a standalone comment?"""
 116         return len(self.leaves) == 1 and self.leaves[0].type == STANDALONE_COMMENT
 117
 118     @property
 119     def is_decorator(self) -> bool:
 120         """Is this line a decorator?"""
 121         return bool(self) and self.leaves[0].type == token.AT
 122
 123     @property
 124     def is_import(self) -> bool:
 125         """Is this an import line?"""
 126         return bool(self) and is_import(self.leaves[0])
 127
 128     @property
 129     def is_with_or_async_with_stmt(self) -> bool:
 130         """Is this a with_stmt line?"""
 131         return bool(self) and is_with_or_async_with_stmt(self.leaves[0])
 132
 133     @property
 134     def is_class(self) -> bool:
 135         """Is this line a class definition?"""
 136         return (
 137             bool(self)
 138             and self.leaves[0].type == token.NAME
 139             and self.leaves[0].value == "class"
 140         )
 141
 142     @property
 143     def is_stub_class(self) -> bool:
 144         """Is this line a class definition with a body consisting only of "..."?"""
 145         return self.is_class and self.leaves[-3:] == [
 146             Leaf(token.DOT, ".") for _ in range(3)
 147         ]
 148
 149     @property
 150     def is_def(self) -> bool:
 151         """Is this a function definition? (Also returns True for async defs.)"""
 152         try:
 153             first_leaf = self.leaves[0]
 154         except IndexError:
 155             return False
 156
 157         try:
 158             second_leaf: Optional[Leaf] = self.leaves[1]
 159         except IndexError:
 160             second_leaf = None
 161         return (first_leaf.type == token.NAME and first_leaf.value == "def") or (
 162             first_leaf.type == token.ASYNC
 163             and second_leaf is not None
 164             and second_leaf.type == token.NAME
 165             and second_leaf.value == "def"
 166         )
 167
 168     @property
 169     def is_class_paren_empty(self) -> bool:
 170         """Is this a class with no base classes but using parentheses?
 171
 172         Those are unnecessary and should be removed.
 173         """
 174         return (
 175             bool(self)
 176             and len(self.leaves) == 4
 177             and self.is_class
 178             and self.leaves[2].type == token.LPAR
 179             and self.leaves[2].value == "("
 180             and self.leaves[3].type == token.RPAR
 181             and self.leaves[3].value == ")"
 182         )
 183
 184     @property
 185     def is_triple_quoted_string(self) -> bool:
 186         """Is the line a triple quoted string?"""
 187         return (
 188             bool(self)
 189             and self.leaves[0].type == token.STRING
 190             and self.leaves[0].value.startswith(('"""', "'''"))
 191         )
 192
 193     @property
 194     def opens_block(self) -> bool:
 195         """Does this line open a new level of indentation."""
 196         if len(self.leaves) == 0:
 197             return False
 198         return self.leaves[-1].type == token.COLON
 199
 200     def is_fmt_pass_converted(
 201         self, *, first_leaf_matches: Optional[Callable[[Leaf], bool]] = None
 202     ) -> bool:
 203         """Is this line converted from fmt off/skip code?
 204
 205         If first_leaf_matches is not None, it only returns True if the first
 206         leaf of converted code matches.
 207         """
 208         if len(self.leaves) != 1:
 209             return False
 210         leaf = self.leaves[0]
 211         if (
 212             leaf.type != STANDALONE_COMMENT
 213             or leaf.fmt_pass_converted_first_leaf is None
 214         ):
 215             return False
 216         return first_leaf_matches is None or first_leaf_matches(
 217             leaf.fmt_pass_converted_first_leaf
 218         )
 219
 220     def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
 221         """If so, needs to be split before emitting."""
 222         for leaf in self.leaves:
 223             if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
 224                 return True
 225
 226         return False
 227
 228     def contains_uncollapsable_type_comments(self) -> bool:
 229         ignored_ids = set()
 230         try:
 231             last_leaf = self.leaves[-1]
 232             ignored_ids.add(id(last_leaf))
 233             if last_leaf.type == token.COMMA or (
 234                 last_leaf.type == token.RPAR and not last_leaf.value
 235             ):
 236                 # When trailing commas or optional parens are inserted by Black for
 237                 # consistency, comments after the previous last element are not moved
 238                 # (they don't have to, rendering will still be correct).  So we ignore
 239                 # trailing commas and invisible.
 240                 last_leaf = self.leaves[-2]
 241                 ignored_ids.add(id(last_leaf))
 242         except IndexError:
 243             return False
 244
 245         # A type comment is uncollapsable if it is attached to a leaf
 246         # that isn't at the end of the line (since that could cause it
 247         # to get associated to a different argument) or if there are
 248         # comments before it (since that could cause it to get hidden
 249         # behind a comment.
 250         comment_seen = False
 251         for leaf_id, comments in self.comments.items():
 252             for comment in comments:
 253                 if is_type_comment(comment):
 254                     if comment_seen or (
 255                         not is_type_ignore_comment(comment)
 256                         and leaf_id not in ignored_ids
 257                     ):
 258                         return True
 259
 260                 comment_seen = True
 261
 262         return False
 263
 264     def contains_unsplittable_type_ignore(self) -> bool:
 265         if not self.leaves:
 266             return False
 267
 268         # If a 'type: ignore' is attached to the end of a line, we
 269         # can't split the line, because we can't know which of the
 270         # subexpressions the ignore was meant to apply to.
 271         #
 272         # We only want this to apply to actual physical lines from the
 273         # original source, though: we don't want the presence of a
 274         # 'type: ignore' at the end of a multiline expression to
 275         # justify pushing it all onto one line. Thus we
 276         # (unfortunately) need to check the actual source lines and
 277         # only report an unsplittable 'type: ignore' if this line was
 278         # one line in the original code.
 279
 280         # Grab the first and last line numbers, skipping generated leaves
 281         first_line = next((leaf.lineno for leaf in self.leaves if leaf.lineno != 0), 0)
 282         last_line = next(
 283             (leaf.lineno for leaf in reversed(self.leaves) if leaf.lineno != 0), 0
 284         )
 285
 286         if first_line == last_line:
 287             # We look at the last two leaves since a comma or an
 288             # invisible paren could have been added at the end of the
 289             # line.
 290             for node in self.leaves[-2:]:
 291                 for comment in self.comments.get(id(node), []):
 292                     if is_type_ignore_comment(comment):
 293                         return True
 294
 295         return False
 296
 297     def contains_multiline_strings(self) -> bool:
 298         return any(is_multiline_string(leaf) for leaf in self.leaves)
 299
 300     def has_magic_trailing_comma(
 301         self, closing: Leaf, ensure_removable: bool = False
 302     ) -> bool:
 303         """Return True if we have a magic trailing comma, that is when:
 304         - there's a trailing comma here
 305         - it's not a one-tuple
 306         - it's not a single-element subscript
 307         Additionally, if ensure_removable:
 308         - it's not from square bracket indexing
 309         (specifically, single-element square bracket indexing)
 310         """
 311         if not (
 312             closing.type in CLOSING_BRACKETS
 313             and self.leaves
 314             and self.leaves[-1].type == token.COMMA
 315         ):
 316             return False
 317
 318         if closing.type == token.RBRACE:
 319             return True
 320
 321         if closing.type == token.RSQB:
 322             if (
 323                 closing.parent
 324                 and closing.parent.type == syms.trailer
 325                 and closing.opening_bracket
 326                 and is_one_sequence_between(
 327                     closing.opening_bracket,
 328                     closing,
 329                     self.leaves,
 330                     brackets=(token.LSQB, token.RSQB),
 331                 )
 332             ):
 333                 return False
 334
 335             if not ensure_removable:
 336                 return True
 337
 338             comma = self.leaves[-1]
 339             if comma.parent is None:
 340                 return False
 341             return (
 342                 comma.parent.type != syms.subscriptlist
 343                 or closing.opening_bracket is None
 344                 or not is_one_sequence_between(
 345                     closing.opening_bracket,
 346                     closing,
 347                     self.leaves,
 348                     brackets=(token.LSQB, token.RSQB),
 349                 )
 350             )
 351
 352         if self.is_import:
 353             return True
 354
 355         if closing.opening_bracket is not None and not is_one_sequence_between(
 356             closing.opening_bracket, closing, self.leaves
 357         ):
 358             return True
 359
 360         return False
 361
 362     def append_comment(self, comment: Leaf) -> bool:
 363         """Add an inline or standalone comment to the line."""
 364         if (
 365             comment.type == STANDALONE_COMMENT
 366             and self.bracket_tracker.any_open_brackets()
 367         ):
 368             comment.prefix = ""
 369             return False
 370
 371         if comment.type != token.COMMENT:
 372             return False
 373
 374         if not self.leaves:
 375             comment.type = STANDALONE_COMMENT
 376             comment.prefix = ""
 377             return False
 378
 379         last_leaf = self.leaves[-1]
 380         if (
 381             last_leaf.type == token.RPAR
 382             and not last_leaf.value
 383             and last_leaf.parent
 384             and len(list(last_leaf.parent.leaves())) <= 3
 385             and not is_type_comment(comment)
 386         ):
 387             # Comments on an optional parens wrapping a single leaf should belong to
 388             # the wrapped node except if it's a type comment. Pinning the comment like
 389             # this avoids unstable formatting caused by comment migration.
 390             if len(self.leaves) < 2:
 391                 comment.type = STANDALONE_COMMENT
 392                 comment.prefix = ""
 393                 return False
 394
 395             last_leaf = self.leaves[-2]
 396         self.comments.setdefault(id(last_leaf), []).append(comment)
 397         return True
 398
 399     def comments_after(self, leaf: Leaf) -> List[Leaf]:
 400         """Generate comments that should appear directly after `leaf`."""
 401         return self.comments.get(id(leaf), [])
 402
 403     def remove_trailing_comma(self) -> None:
 404         """Remove the trailing comma and moves the comments attached to it."""
 405         trailing_comma = self.leaves.pop()
 406         trailing_comma_comments = self.comments.pop(id(trailing_comma), [])
 407         self.comments.setdefault(id(self.leaves[-1]), []).extend(
 408             trailing_comma_comments
 409         )
 410
 411     def is_complex_subscript(self, leaf: Leaf) -> bool:
 412         """Return True iff `leaf` is part of a slice with non-trivial exprs."""
 413         open_lsqb = self.bracket_tracker.get_open_lsqb()
 414         if open_lsqb is None:
 415             return False
 416
 417         subscript_start = open_lsqb.next_sibling
 418
 419         if isinstance(subscript_start, Node):
 420             if subscript_start.type == syms.listmaker:
 421                 return False
 422
 423             if subscript_start.type == syms.subscriptlist:
 424                 subscript_start = child_towards(subscript_start, leaf)
 425         return subscript_start is not None and any(
 426             n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
 427         )
 428
 429     def enumerate_with_length(
 430         self, reversed: bool = False
 431     ) -> Iterator[Tuple[Index, Leaf, int]]:
 432         """Return an enumeration of leaves with their length.
 433
 434         Stops prematurely on multiline strings and standalone comments.
 435         """
 436         op = cast(
 437             Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
 438             enumerate_reversed if reversed else enumerate,
 439         )
 440         for index, leaf in op(self.leaves):
 441             length = len(leaf.prefix) + len(leaf.value)
 442             if "\n" in leaf.value:
 443                 return  # Multiline strings, we can't continue.
 444
 445             for comment in self.comments_after(leaf):
 446                 length += len(comment.value)
 447
 448             yield index, leaf, length
 449
 450     def clone(self) -> "Line":
 451         return Line(
 452             mode=self.mode,
 453             depth=self.depth,
 454             inside_brackets=self.inside_brackets,
 455             should_split_rhs=self.should_split_rhs,
 456             magic_trailing_comma=self.magic_trailing_comma,
 457         )
 458
 459     def __str__(self) -> str:
 460         """Render the line."""
 461         if not self:
 462             return "\n"
 463
 464         indent = "    " * self.depth
 465         leaves = iter(self.leaves)
 466         first = next(leaves)
 467         res = f"{first.prefix}{indent}{first.value}"
 468         for leaf in leaves:
 469             res += str(leaf)
 470         for comment in itertools.chain.from_iterable(self.comments.values()):
 471             res += str(comment)
 472
 473         return res + "\n"
 474
 475     def __bool__(self) -> bool:
 476         """Return True if the line has leaves or comments."""
 477         return bool(self.leaves or self.comments)
 478
 479
 480 @dataclass
 481 class RHSResult:
 482     """Intermediate split result from a right hand split."""
 483
 484     head: Line
 485     body: Line
 486     tail: Line
 487     opening_bracket: Leaf
 488     closing_bracket: Leaf
 489
 490
 491 @dataclass
 492 class LinesBlock:
 493     """Class that holds information about a block of formatted lines.
 494
 495     This is introduced so that the EmptyLineTracker can look behind the standalone
 496     comments and adjust their empty lines for class or def lines.
 497     """
 498
 499     mode: Mode
 500     previous_block: Optional["LinesBlock"]
 501     original_line: Line
 502     before: int = 0
 503     content_lines: List[str] = field(default_factory=list)
 504     after: int = 0
 505
 506     def all_lines(self) -> List[str]:
 507         empty_line = str(Line(mode=self.mode))
 508         return (
 509             [empty_line * self.before] + self.content_lines + [empty_line * self.after]
 510         )
 511
 512
 513 @dataclass
 514 class EmptyLineTracker:
 515     """Provides a stateful method that returns the number of potential extra
 516     empty lines needed before and after the currently processed line.
 517
 518     Note: this tracker works on lines that haven't been split yet.  It assumes
 519     the prefix of the first leaf consists of optional newlines.  Those newlines
 520     are consumed by `maybe_empty_lines()` and included in the computation.
 521     """
 522
 523     mode: Mode
 524     previous_line: Optional[Line] = None
 525     previous_block: Optional[LinesBlock] = None
 526     previous_defs: List[Line] = field(default_factory=list)
 527     semantic_leading_comment: Optional[LinesBlock] = None
 528
 529     def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
 530         """Return the number of extra empty lines before and after the `current_line`.
 531
 532         This is for separating `def`, `async def` and `class` with extra empty
 533         lines (two on module-level).
 534         """
 535         before, after = self._maybe_empty_lines(current_line)
 536         previous_after = self.previous_block.after if self.previous_block else 0
 537         before = (
 538             # Black should not insert empty lines at the beginning
 539             # of the file
 540             0
 541             if self.previous_line is None
 542             else before - previous_after
 543         )
 544         block = LinesBlock(
 545             mode=self.mode,
 546             previous_block=self.previous_block,
 547             original_line=current_line,
 548             before=before,
 549             after=after,
 550         )
 551
 552         # Maintain the semantic_leading_comment state.
 553         if current_line.is_comment:
 554             if self.previous_line is None or (
 555                 not self.previous_line.is_decorator
 556                 # `or before` means this comment already has an empty line before
 557                 and (not self.previous_line.is_comment or before)
 558                 and (self.semantic_leading_comment is None or before)
 559             ):
 560                 self.semantic_leading_comment = block
 561         # `or before` means this decorator already has an empty line before
 562         elif not current_line.is_decorator or before:
 563             self.semantic_leading_comment = None
 564
 565         self.previous_line = current_line
 566         self.previous_block = block
 567         return block
 568
 569     def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
 570         max_allowed = 1
 571         if current_line.depth == 0:
 572             max_allowed = 1 if self.mode.is_pyi else 2
 573         if current_line.leaves:
 574             # Consume the first leaf's extra newlines.
 575             first_leaf = current_line.leaves[0]
 576             before = first_leaf.prefix.count("\n")
 577             before = min(before, max_allowed)
 578             first_leaf.prefix = ""
 579         else:
 580             before = 0
 581         depth = current_line.depth
 582
 583         previous_def = None
 584         while self.previous_defs and self.previous_defs[-1].depth >= depth:
 585             previous_def = self.previous_defs.pop()
 586
 587         if previous_def is not None:
 588             assert self.previous_line is not None
 589             if self.mode.is_pyi:
 590                 if depth and not current_line.is_def and self.previous_line.is_def:
 591                     # Empty lines between attributes and methods should be preserved.
 592                     before = min(1, before)
 593                 elif (
 594                     Preview.blank_line_after_nested_stub_class in self.mode
 595                     and previous_def.is_class
 596                     and not previous_def.is_stub_class
 597                 ):
 598                     before = 1
 599                 elif depth:
 600                     before = 0
 601                 else:
 602                     before = 1
 603             else:
 604                 if depth:
 605                     before = 1
 606                 elif (
 607                     not depth
 608                     and previous_def.depth
 609                     and current_line.leaves[-1].type == token.COLON
 610                     and (
 611                         current_line.leaves[0].value
 612                         not in ("with", "try", "for", "while", "if", "match")
 613                     )
 614                 ):
 615                     # We shouldn't add two newlines between an indented function and
 616                     # a dependent non-indented clause. This is to avoid issues with
 617                     # conditional function definitions that are technically top-level
 618                     # and therefore get two trailing newlines, but look weird and
 619                     # inconsistent when they're followed by elif, else, etc. This is
 620                     # worse because these functions only get *one* preceding newline
 621                     # already.
 622                     before = 1
 623                 else:
 624                     before = 2
 625
 626         if current_line.is_decorator or current_line.is_def or current_line.is_class:
 627             return self._maybe_empty_lines_for_class_or_def(current_line, before)
 628
 629         if (
 630             self.previous_line
 631             and self.previous_line.is_import
 632             and not current_line.is_import
 633             and not current_line.is_fmt_pass_converted(first_leaf_matches=is_import)
 634             and depth == self.previous_line.depth
 635         ):
 636             return (before or 1), 0
 637
 638         if (
 639             self.previous_line
 640             and self.previous_line.is_class
 641             and current_line.is_triple_quoted_string
 642         ):
 643             if Preview.no_blank_line_before_class_docstring in current_line.mode:
 644                 return 0, 1
 645             return before, 1
 646
 647         if self.previous_line and self.previous_line.opens_block:
 648             return 0, 0
 649         return before, 0
 650
 651     def _maybe_empty_lines_for_class_or_def(
 652         self, current_line: Line, before: int
 653     ) -> Tuple[int, int]:
 654         if not current_line.is_decorator:
 655             self.previous_defs.append(current_line)
 656         if self.previous_line is None:
 657             # Don't insert empty lines before the first line in the file.
 658             return 0, 0
 659
 660         if self.previous_line.is_decorator:
 661             if self.mode.is_pyi and current_line.is_stub_class:
 662                 # Insert an empty line after a decorated stub class
 663                 return 0, 1
 664
 665             return 0, 0
 666
 667         if self.previous_line.depth < current_line.depth and (
 668             self.previous_line.is_class or self.previous_line.is_def
 669         ):
 670             return 0, 0
 671
 672         comment_to_add_newlines: Optional[LinesBlock] = None
 673         if (
 674             self.previous_line.is_comment
 675             and self.previous_line.depth == current_line.depth
 676             and before == 0
 677         ):
 678             slc = self.semantic_leading_comment
 679             if (
 680                 slc is not None
 681                 and slc.previous_block is not None
 682                 and not slc.previous_block.original_line.is_class
 683                 and not slc.previous_block.original_line.opens_block
 684                 and slc.before <= 1
 685             ):
 686                 comment_to_add_newlines = slc
 687             else:
 688                 return 0, 0
 689
 690         if self.mode.is_pyi:
 691             if current_line.is_class or self.previous_line.is_class:
 692                 if self.previous_line.depth < current_line.depth:
 693                     newlines = 0
 694                 elif self.previous_line.depth > current_line.depth:
 695                     newlines = 1
 696                 elif current_line.is_stub_class and self.previous_line.is_stub_class:
 697                     # No blank line between classes with an empty body
 698                     newlines = 0
 699                 else:
 700                     newlines = 1
 701             elif (
 702                 current_line.is_def or current_line.is_decorator
 703             ) and not self.previous_line.is_def:
 704                 if current_line.depth:
 705                     # In classes empty lines between attributes and methods should
 706                     # be preserved.
 707                     newlines = min(1, before)
 708                 else:
 709                     # Blank line between a block of functions (maybe with preceding
 710                     # decorators) and a block of non-functions
 711                     newlines = 1
 712             elif self.previous_line.depth > current_line.depth:
 713                 newlines = 1
 714             else:
 715                 newlines = 0
 716         else:
 717             newlines = 1 if current_line.depth else 2
 718         if comment_to_add_newlines is not None:
 719             previous_block = comment_to_add_newlines.previous_block
 720             if previous_block is not None:
 721                 comment_to_add_newlines.before = (
 722                     max(comment_to_add_newlines.before, newlines) - previous_block.after
 723                 )
 724                 newlines = 0
 725         return newlines, 0
 726
 727
 728 def enumerate_reversed(sequence: Sequence[T]) -> Iterator[Tuple[Index, T]]:
 729     """Like `reversed(enumerate(sequence))` if that were possible."""
 730     index = len(sequence) - 1
 731     for element in reversed(sequence):
 732         yield (index, element)
 733         index -= 1
 734
 735
 736 def append_leaves(
 737     new_line: Line, old_line: Line, leaves: List[Leaf], preformatted: bool = False
 738 ) -> None:
 739     """
 740     Append leaves (taken from @old_line) to @new_line, making sure to fix the
 741     underlying Node structure where appropriate.
 742
 743     All of the leaves in @leaves are duplicated. The duplicates are then
 744     appended to @new_line and used to replace their originals in the underlying
 745     Node structure. Any comments attached to the old leaves are reattached to
 746     the new leaves.
 747
 748     Pre-conditions:
 749         set(@leaves) is a subset of set(@old_line.leaves).
 750     """
 751     for old_leaf in leaves:
 752         new_leaf = Leaf(old_leaf.type, old_leaf.value)
 753         replace_child(old_leaf, new_leaf)
 754         new_line.append(new_leaf, preformatted=preformatted)
 755
 756         for comment_leaf in old_line.comments_after(old_leaf):
 757             new_line.append(comment_leaf, preformatted=True)
 758
 759
 760 def is_line_short_enough(  # noqa: C901
 761     line: Line, *, mode: Mode, line_str: str = ""
 762 ) -> bool:
 763     """For non-multiline strings, return True if `line` is no longer than `line_length`.
 764     For multiline strings, looks at the context around `line` to determine
 765     if it should be inlined or split up.
 766     Uses the provided `line_str` rendering, if any, otherwise computes a new one.
 767     """
 768     if not line_str:
 769         line_str = line_to_string(line)
 770
 771     width = str_width if mode.preview else len
 772
 773     if Preview.multiline_string_handling not in mode:
 774         return (
 775             width(line_str) <= mode.line_length
 776             and "\n" not in line_str  # multiline strings
 777             and not line.contains_standalone_comments()
 778         )
 779
 780     if line.contains_standalone_comments():
 781         return False
 782     if "\n" not in line_str:
 783         # No multiline strings (MLS) present
 784         return width(line_str) <= mode.line_length
 785
 786     first, *_, last = line_str.split("\n")
 787     if width(first) > mode.line_length or width(last) > mode.line_length:
 788         return False
 789
 790     # Traverse the AST to examine the context of the multiline string (MLS),
 791     # tracking aspects such as depth and comma existence,
 792     # to determine whether to split the MLS or keep it together.
 793     # Depth (which is based on the existing bracket_depth concept)
 794     # is needed to determine nesting level of the MLS.
 795     # Includes special case for trailing commas.
 796     commas: List[int] = []  # tracks number of commas per depth level
 797     multiline_string: Optional[Leaf] = None
 798     # store the leaves that contain parts of the MLS
 799     multiline_string_contexts: List[LN] = []
 800
 801     max_level_to_update: Union[int, float] = math.inf  # track the depth of the MLS
 802     for i, leaf in enumerate(line.leaves):
 803         if max_level_to_update == math.inf:
 804             had_comma: Optional[int] = None
 805             if leaf.bracket_depth + 1 > len(commas):
 806                 commas.append(0)
 807             elif leaf.bracket_depth + 1 < len(commas):
 808                 had_comma = commas.pop()
 809             if (
 810                 had_comma is not None
 811                 and multiline_string is not None
 812                 and multiline_string.bracket_depth == leaf.bracket_depth + 1
 813             ):
 814                 # Have left the level with the MLS, stop tracking commas
 815                 max_level_to_update = leaf.bracket_depth
 816                 if had_comma > 0:
 817                     # MLS was in parens with at least one comma - force split
 818                     return False
 819
 820         if leaf.bracket_depth <= max_level_to_update and leaf.type == token.COMMA:
 821             # Ignore non-nested trailing comma
 822             # directly after MLS/MLS-containing expression
 823             ignore_ctxs: List[Optional[LN]] = [None]
 824             ignore_ctxs += multiline_string_contexts
 825             if not (leaf.prev_sibling in ignore_ctxs and i == len(line.leaves) - 1):
 826                 commas[leaf.bracket_depth] += 1
 827         if max_level_to_update != math.inf:
 828             max_level_to_update = min(max_level_to_update, leaf.bracket_depth)
 829
 830         if is_multiline_string(leaf):
 831             if len(multiline_string_contexts) > 0:
 832                 # >1 multiline string cannot fit on a single line - force split
 833                 return False
 834             multiline_string = leaf
 835             ctx: LN = leaf
 836             # fetch the leaf components of the MLS in the AST
 837             while str(ctx) in line_str:
 838                 multiline_string_contexts.append(ctx)
 839                 if ctx.parent is None:
 840                     break
 841                 ctx = ctx.parent
 842
 843     # May not have a triple-quoted multiline string at all,
 844     # in case of a regular string with embedded newlines and line continuations
 845     if len(multiline_string_contexts) == 0:
 846         return True
 847
 848     return all(val == 0 for val in commas)
 849
 850
 851 def can_be_split(line: Line) -> bool:
 852     """Return False if the line cannot be split *for sure*.
 853
 854     This is not an exhaustive search but a cheap heuristic that we can use to
 855     avoid some unfortunate formattings (mostly around wrapping unsplittable code
 856     in unnecessary parentheses).
 857     """
 858     leaves = line.leaves
 859     if len(leaves) < 2:
 860         return False
 861
 862     if leaves[0].type == token.STRING and leaves[1].type == token.DOT:
 863         call_count = 0
 864         dot_count = 0
 865         next = leaves[-1]
 866         for leaf in leaves[-2::-1]:
 867             if leaf.type in OPENING_BRACKETS:
 868                 if next.type not in CLOSING_BRACKETS:
 869                     return False
 870
 871                 call_count += 1
 872             elif leaf.type == token.DOT:
 873                 dot_count += 1
 874             elif leaf.type == token.NAME:
 875                 if not (next.type == token.DOT or next.type in OPENING_BRACKETS):
 876                     return False
 877
 878             elif leaf.type not in CLOSING_BRACKETS:
 879                 return False
 880
 881             if dot_count > 1 and call_count > 1:
 882                 return False
 883
 884     return True
 885
 886
 887 def can_omit_invisible_parens(
 888     rhs: RHSResult,
 889     line_length: int,
 890 ) -> bool:
 891     """Does `rhs.body` have a shape safe to reformat without optional parens around it?
 892
 893     Returns True for only a subset of potentially nice looking formattings but
 894     the point is to not return false positives that end up producing lines that
 895     are too long.
 896     """
 897     line = rhs.body
 898     bt = line.bracket_tracker
 899     if not bt.delimiters:
 900         # Without delimiters the optional parentheses are useless.
 901         return True
 902
 903     max_priority = bt.max_delimiter_priority()
 904     delimiter_count = bt.delimiter_count_with_priority(max_priority)
 905     if delimiter_count > 1:
 906         # With more than one delimiter of a kind the optional parentheses read better.
 907         return False
 908
 909     if delimiter_count == 1:
 910         if (
 911             Preview.wrap_multiple_context_managers_in_parens in line.mode
 912             and max_priority == COMMA_PRIORITY
 913             and rhs.head.is_with_or_async_with_stmt
 914         ):
 915             # For two context manager with statements, the optional parentheses read
 916             # better. In this case, `rhs.body` is the context managers part of
 917             # the with statement. `rhs.head` is the `with (` part on the previous
 918             # line.
 919             return False
 920         # Otherwise it may also read better, but we don't do it today and requires
 921         # careful considerations for all possible cases. See
 922         # https://github.com/psf/black/issues/2156.
 923
 924     if max_priority == DOT_PRIORITY:
 925         # A single stranded method call doesn't require optional parentheses.
 926         return True
 927
 928     assert len(line.leaves) >= 2, "Stranded delimiter"
 929
 930     # With a single delimiter, omit if the expression starts or ends with
 931     # a bracket.
 932     first = line.leaves[0]
 933     second = line.leaves[1]
 934     if first.type in OPENING_BRACKETS and second.type not in CLOSING_BRACKETS:
 935         if _can_omit_opening_paren(line, first=first, line_length=line_length):
 936             return True
 937
 938         # Note: we are not returning False here because a line might have *both*
 939         # a leading opening bracket and a trailing closing bracket.  If the
 940         # opening bracket doesn't match our rule, maybe the closing will.
 941
 942     penultimate = line.leaves[-2]
 943     last = line.leaves[-1]
 944
 945     if (
 946         last.type == token.RPAR
 947         or last.type == token.RBRACE
 948         or (
 949             # don't use indexing for omitting optional parentheses;
 950             # it looks weird
 951             last.type == token.RSQB
 952             and last.parent
 953             and last.parent.type != syms.trailer
 954         )
 955     ):
 956         if penultimate.type in OPENING_BRACKETS:
 957             # Empty brackets don't help.
 958             return False
 959
 960         if is_multiline_string(first):
 961             # Additional wrapping of a multiline string in this situation is
 962             # unnecessary.
 963             return True
 964
 965         if _can_omit_closing_paren(line, last=last, line_length=line_length):
 966             return True
 967
 968     return False
 969
 970
 971 def _can_omit_opening_paren(line: Line, *, first: Leaf, line_length: int) -> bool:
 972     """See `can_omit_invisible_parens`."""
 973     remainder = False
 974     length = 4 * line.depth
 975     _index = -1
 976     for _index, leaf, leaf_length in line.enumerate_with_length():
 977         if leaf.type in CLOSING_BRACKETS and leaf.opening_bracket is first:
 978             remainder = True
 979         if remainder:
 980             length += leaf_length
 981             if length > line_length:
 982                 break
 983
 984             if leaf.type in OPENING_BRACKETS:
 985                 # There are brackets we can further split on.
 986                 remainder = False
 987
 988     else:
 989         # checked the entire string and line length wasn't exceeded
 990         if len(line.leaves) == _index + 1:
 991             return True
 992
 993     return False
 994
 995
 996 def _can_omit_closing_paren(line: Line, *, last: Leaf, line_length: int) -> bool:
 997     """See `can_omit_invisible_parens`."""
 998     length = 4 * line.depth
 999     seen_other_brackets = False
1000     for _index, leaf, leaf_length in line.enumerate_with_length():
1001         length += leaf_length
1002         if leaf is last.opening_bracket:
1003             if seen_other_brackets or length <= line_length:
1004                 return True
1005
1006         elif leaf.type in OPENING_BRACKETS:
1007             # There are brackets we can further split on.
1008             seen_other_brackets = True
1009
1010     return False
1011
1012
1013 def line_to_string(line: Line) -> str:
1014     """Returns the string representation of @line.
1015
1016     WARNING: This is known to be computationally expensive.
1017     """
1018     return str(line).strip("\n")