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