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