src/black/lines.py

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