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