src/black/linegen.py

   1 """
   2 Generating lines of code.
   3 """
   4 import sys
   5 from enum import Enum, auto
   6 from functools import partial, wraps
   7 from typing import Collection, Iterator, List, Optional, Set, Union, cast
   8
   9 from black.brackets import (
  10     COMMA_PRIORITY,
  11     DOT_PRIORITY,
  12     get_leaves_inside_matching_brackets,
  13     max_delimiter_priority_in_atom,
  14 )
  15 from black.comments import FMT_OFF, generate_comments, list_comments
  16 from black.lines import (
  17     Line,
  18     append_leaves,
  19     can_be_split,
  20     can_omit_invisible_parens,
  21     is_line_short_enough,
  22     line_to_string,
  23 )
  24 from black.mode import Feature, Mode, Preview
  25 from black.nodes import (
  26     ASSIGNMENTS,
  27     CLOSING_BRACKETS,
  28     OPENING_BRACKETS,
  29     RARROW,
  30     STANDALONE_COMMENT,
  31     STATEMENT,
  32     WHITESPACE,
  33     Visitor,
  34     ensure_visible,
  35     is_arith_like,
  36     is_atom_with_invisible_parens,
  37     is_docstring,
  38     is_empty_tuple,
  39     is_lpar_token,
  40     is_multiline_string,
  41     is_name_token,
  42     is_one_sequence_between,
  43     is_one_tuple,
  44     is_rpar_token,
  45     is_stub_body,
  46     is_stub_suite,
  47     is_vararg,
  48     is_walrus_assignment,
  49     is_yield,
  50     syms,
  51     wrap_in_parentheses,
  52 )
  53 from black.numerics import normalize_numeric_literal
  54 from black.strings import (
  55     fix_docstring,
  56     get_string_prefix,
  57     normalize_string_prefix,
  58     normalize_string_quotes,
  59 )
  60 from black.trans import (
  61     CannotTransform,
  62     StringMerger,
  63     StringParenStripper,
  64     StringParenWrapper,
  65     StringSplitter,
  66     Transformer,
  67     hug_power_op,
  68 )
  69 from blib2to3.pgen2 import token
  70 from blib2to3.pytree import Leaf, Node
  71
  72 # types
  73 LeafID = int
  74 LN = Union[Leaf, Node]
  75
  76
  77 class CannotSplit(CannotTransform):
  78     """A readable split that fits the allotted line length is impossible."""
  79
  80
  81 # This isn't a dataclass because @dataclass + Generic breaks mypyc.
  82 # See also https://github.com/mypyc/mypyc/issues/827.
  83 class LineGenerator(Visitor[Line]):
  84     """Generates reformatted Line objects.  Empty lines are not emitted.
  85
  86     Note: destroys the tree it's visiting by mutating prefixes of its leaves
  87     in ways that will no longer stringify to valid Python code on the tree.
  88     """
  89
  90     def __init__(self, mode: Mode) -> None:
  91         self.mode = mode
  92         self.current_line: Line
  93         self.__post_init__()
  94
  95     def line(self, indent: int = 0) -> Iterator[Line]:
  96         """Generate a line.
  97
  98         If the line is empty, only emit if it makes sense.
  99         If the line is too long, split it first and then generate.
 100
 101         If any lines were generated, set up a new current_line.
 102         """
 103         if not self.current_line:
 104             self.current_line.depth += indent
 105             return  # Line is empty, don't emit. Creating a new one unnecessary.
 106
 107         complete_line = self.current_line
 108         self.current_line = Line(mode=self.mode, depth=complete_line.depth + indent)
 109         yield complete_line
 110
 111     def visit_default(self, node: LN) -> Iterator[Line]:
 112         """Default `visit_*()` implementation. Recurses to children of `node`."""
 113         if isinstance(node, Leaf):
 114             any_open_brackets = self.current_line.bracket_tracker.any_open_brackets()
 115             for comment in generate_comments(node, preview=self.mode.preview):
 116                 if any_open_brackets:
 117                     # any comment within brackets is subject to splitting
 118                     self.current_line.append(comment)
 119                 elif comment.type == token.COMMENT:
 120                     # regular trailing comment
 121                     self.current_line.append(comment)
 122                     yield from self.line()
 123
 124                 else:
 125                     # regular standalone comment
 126                     yield from self.line()
 127
 128                     self.current_line.append(comment)
 129                     yield from self.line()
 130
 131             normalize_prefix(node, inside_brackets=any_open_brackets)
 132             if self.mode.string_normalization and node.type == token.STRING:
 133                 node.value = normalize_string_prefix(node.value)
 134                 node.value = normalize_string_quotes(node.value)
 135             if node.type == token.NUMBER:
 136                 normalize_numeric_literal(node)
 137             if node.type not in WHITESPACE:
 138                 self.current_line.append(node)
 139         yield from super().visit_default(node)
 140
 141     def visit_INDENT(self, node: Leaf) -> Iterator[Line]:
 142         """Increase indentation level, maybe yield a line."""
 143         # In blib2to3 INDENT never holds comments.
 144         yield from self.line(+1)
 145         yield from self.visit_default(node)
 146
 147     def visit_DEDENT(self, node: Leaf) -> Iterator[Line]:
 148         """Decrease indentation level, maybe yield a line."""
 149         # The current line might still wait for trailing comments.  At DEDENT time
 150         # there won't be any (they would be prefixes on the preceding NEWLINE).
 151         # Emit the line then.
 152         yield from self.line()
 153
 154         # While DEDENT has no value, its prefix may contain standalone comments
 155         # that belong to the current indentation level.  Get 'em.
 156         yield from self.visit_default(node)
 157
 158         # Finally, emit the dedent.
 159         yield from self.line(-1)
 160
 161     def visit_stmt(
 162         self, node: Node, keywords: Set[str], parens: Set[str]
 163     ) -> Iterator[Line]:
 164         """Visit a statement.
 165
 166         This implementation is shared for `if`, `while`, `for`, `try`, `except`,
 167         `def`, `with`, `class`, `assert`, and assignments.
 168
 169         The relevant Python language `keywords` for a given statement will be
 170         NAME leaves within it. This methods puts those on a separate line.
 171
 172         `parens` holds a set of string leaf values immediately after which
 173         invisible parens should be put.
 174         """
 175         normalize_invisible_parens(node, parens_after=parens, preview=self.mode.preview)
 176         for child in node.children:
 177             if is_name_token(child) and child.value in keywords:
 178                 yield from self.line()
 179
 180             yield from self.visit(child)
 181
 182     def visit_funcdef(self, node: Node) -> Iterator[Line]:
 183         """Visit function definition."""
 184         if Preview.annotation_parens not in self.mode:
 185             yield from self.visit_stmt(node, keywords={"def"}, parens=set())
 186         else:
 187             yield from self.line()
 188
 189             # Remove redundant brackets around return type annotation.
 190             is_return_annotation = False
 191             for child in node.children:
 192                 if child.type == token.RARROW:
 193                     is_return_annotation = True
 194                 elif is_return_annotation:
 195                     if child.type == syms.atom and child.children[0].type == token.LPAR:
 196                         if maybe_make_parens_invisible_in_atom(
 197                             child,
 198                             parent=node,
 199                             remove_brackets_around_comma=False,
 200                         ):
 201                             wrap_in_parentheses(node, child, visible=False)
 202                     else:
 203                         wrap_in_parentheses(node, child, visible=False)
 204                     is_return_annotation = False
 205
 206             for child in node.children:
 207                 yield from self.visit(child)
 208
 209     def visit_match_case(self, node: Node) -> Iterator[Line]:
 210         """Visit either a match or case statement."""
 211         normalize_invisible_parens(node, parens_after=set(), preview=self.mode.preview)
 212
 213         yield from self.line()
 214         for child in node.children:
 215             yield from self.visit(child)
 216
 217     def visit_suite(self, node: Node) -> Iterator[Line]:
 218         """Visit a suite."""
 219         if self.mode.is_pyi and is_stub_suite(node):
 220             yield from self.visit(node.children[2])
 221         else:
 222             yield from self.visit_default(node)
 223
 224     def visit_simple_stmt(self, node: Node) -> Iterator[Line]:
 225         """Visit a statement without nested statements."""
 226         prev_type: Optional[int] = None
 227         for child in node.children:
 228             if (prev_type is None or prev_type == token.SEMI) and is_arith_like(child):
 229                 wrap_in_parentheses(node, child, visible=False)
 230             prev_type = child.type
 231
 232         is_suite_like = node.parent and node.parent.type in STATEMENT
 233         if is_suite_like:
 234             if self.mode.is_pyi and is_stub_body(node):
 235                 yield from self.visit_default(node)
 236             else:
 237                 yield from self.line(+1)
 238                 yield from self.visit_default(node)
 239                 yield from self.line(-1)
 240
 241         else:
 242             if (
 243                 not self.mode.is_pyi
 244                 or not node.parent
 245                 or not is_stub_suite(node.parent)
 246             ):
 247                 yield from self.line()
 248             yield from self.visit_default(node)
 249
 250     def visit_async_stmt(self, node: Node) -> Iterator[Line]:
 251         """Visit `async def`, `async for`, `async with`."""
 252         yield from self.line()
 253
 254         children = iter(node.children)
 255         for child in children:
 256             yield from self.visit(child)
 257
 258             if child.type == token.ASYNC or child.type == STANDALONE_COMMENT:
 259                 # STANDALONE_COMMENT happens when `# fmt: skip` is applied on the async
 260                 # line.
 261                 break
 262
 263         internal_stmt = next(children)
 264         for child in internal_stmt.children:
 265             yield from self.visit(child)
 266
 267     def visit_decorators(self, node: Node) -> Iterator[Line]:
 268         """Visit decorators."""
 269         for child in node.children:
 270             yield from self.line()
 271             yield from self.visit(child)
 272
 273     def visit_power(self, node: Node) -> Iterator[Line]:
 274         for idx, leaf in enumerate(node.children[:-1]):
 275             next_leaf = node.children[idx + 1]
 276
 277             if not isinstance(leaf, Leaf):
 278                 continue
 279
 280             value = leaf.value.lower()
 281             if (
 282                 leaf.type == token.NUMBER
 283                 and next_leaf.type == syms.trailer
 284                 # Ensure that we are in an attribute trailer
 285                 and next_leaf.children[0].type == token.DOT
 286                 # It shouldn't wrap hexadecimal, binary and octal literals
 287                 and not value.startswith(("0x", "0b", "0o"))
 288                 # It shouldn't wrap complex literals
 289                 and "j" not in value
 290             ):
 291                 wrap_in_parentheses(node, leaf)
 292
 293         if Preview.remove_redundant_parens in self.mode:
 294             remove_await_parens(node)
 295
 296         yield from self.visit_default(node)
 297
 298     def visit_SEMI(self, leaf: Leaf) -> Iterator[Line]:
 299         """Remove a semicolon and put the other statement on a separate line."""
 300         yield from self.line()
 301
 302     def visit_ENDMARKER(self, leaf: Leaf) -> Iterator[Line]:
 303         """End of file. Process outstanding comments and end with a newline."""
 304         yield from self.visit_default(leaf)
 305         yield from self.line()
 306
 307     def visit_STANDALONE_COMMENT(self, leaf: Leaf) -> Iterator[Line]:
 308         if not self.current_line.bracket_tracker.any_open_brackets():
 309             yield from self.line()
 310         yield from self.visit_default(leaf)
 311
 312     def visit_factor(self, node: Node) -> Iterator[Line]:
 313         """Force parentheses between a unary op and a binary power:
 314
 315         -2 ** 8 -> -(2 ** 8)
 316         """
 317         _operator, operand = node.children
 318         if (
 319             operand.type == syms.power
 320             and len(operand.children) == 3
 321             and operand.children[1].type == token.DOUBLESTAR
 322         ):
 323             lpar = Leaf(token.LPAR, "(")
 324             rpar = Leaf(token.RPAR, ")")
 325             index = operand.remove() or 0
 326             node.insert_child(index, Node(syms.atom, [lpar, operand, rpar]))
 327         yield from self.visit_default(node)
 328
 329     def visit_STRING(self, leaf: Leaf) -> Iterator[Line]:
 330         if is_docstring(leaf) and "\\\n" not in leaf.value:
 331             # We're ignoring docstrings with backslash newline escapes because changing
 332             # indentation of those changes the AST representation of the code.
 333             if Preview.normalize_docstring_quotes_and_prefixes_properly in self.mode:
 334                 # There was a bug where --skip-string-normalization wouldn't stop us
 335                 # from normalizing docstring prefixes. To maintain stability, we can
 336                 # only address this buggy behaviour while the preview style is enabled.
 337                 if self.mode.string_normalization:
 338                     docstring = normalize_string_prefix(leaf.value)
 339                     # visit_default() does handle string normalization for us, but
 340                     # since this method acts differently depending on quote style (ex.
 341                     # see padding logic below), there's a possibility for unstable
 342                     # formatting as visit_default() is called *after*. To avoid a
 343                     # situation where this function formats a docstring differently on
 344                     # the second pass, normalize it early.
 345                     docstring = normalize_string_quotes(docstring)
 346                 else:
 347                     docstring = leaf.value
 348             else:
 349                 # ... otherwise, we'll keep the buggy behaviour >.<
 350                 docstring = normalize_string_prefix(leaf.value)
 351             prefix = get_string_prefix(docstring)
 352             docstring = docstring[len(prefix) :]  # Remove the prefix
 353             quote_char = docstring[0]
 354             # A natural way to remove the outer quotes is to do:
 355             #   docstring = docstring.strip(quote_char)
 356             # but that breaks on """""x""" (which is '""x').
 357             # So we actually need to remove the first character and the next two
 358             # characters but only if they are the same as the first.
 359             quote_len = 1 if docstring[1] != quote_char else 3
 360             docstring = docstring[quote_len:-quote_len]
 361             docstring_started_empty = not docstring
 362             indent = " " * 4 * self.current_line.depth
 363
 364             if is_multiline_string(leaf):
 365                 docstring = fix_docstring(docstring, indent)
 366             else:
 367                 docstring = docstring.strip()
 368
 369             if docstring:
 370                 # Add some padding if the docstring starts / ends with a quote mark.
 371                 if docstring[0] == quote_char:
 372                     docstring = " " + docstring
 373                 if docstring[-1] == quote_char:
 374                     docstring += " "
 375                 if docstring[-1] == "\\":
 376                     backslash_count = len(docstring) - len(docstring.rstrip("\\"))
 377                     if backslash_count % 2:
 378                         # Odd number of tailing backslashes, add some padding to
 379                         # avoid escaping the closing string quote.
 380                         docstring += " "
 381             elif not docstring_started_empty:
 382                 docstring = " "
 383
 384             # We could enforce triple quotes at this point.
 385             quote = quote_char * quote_len
 386
 387             # It's invalid to put closing single-character quotes on a new line.
 388             if Preview.long_docstring_quotes_on_newline in self.mode and quote_len == 3:
 389                 # We need to find the length of the last line of the docstring
 390                 # to find if we can add the closing quotes to the line without
 391                 # exceeding the maximum line length.
 392                 # If docstring is one line, we don't put the closing quotes on a
 393                 # separate line because it looks ugly (#3320).
 394                 lines = docstring.splitlines()
 395                 last_line_length = len(lines[-1]) if docstring else 0
 396
 397                 # If adding closing quotes would cause the last line to exceed
 398                 # the maximum line length then put a line break before the
 399                 # closing quotes
 400                 if (
 401                     len(lines) > 1
 402                     and last_line_length + quote_len > self.mode.line_length
 403                 ):
 404                     leaf.value = prefix + quote + docstring + "\n" + indent + quote
 405                 else:
 406                     leaf.value = prefix + quote + docstring + quote
 407             else:
 408                 leaf.value = prefix + quote + docstring + quote
 409
 410         yield from self.visit_default(leaf)
 411
 412     def __post_init__(self) -> None:
 413         """You are in a twisty little maze of passages."""
 414         self.current_line = Line(mode=self.mode)
 415
 416         v = self.visit_stmt
 417         Ø: Set[str] = set()
 418         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
 419         self.visit_if_stmt = partial(
 420             v, keywords={"if", "else", "elif"}, parens={"if", "elif"}
 421         )
 422         self.visit_while_stmt = partial(v, keywords={"while", "else"}, parens={"while"})
 423         self.visit_for_stmt = partial(v, keywords={"for", "else"}, parens={"for", "in"})
 424         self.visit_try_stmt = partial(
 425             v, keywords={"try", "except", "else", "finally"}, parens=Ø
 426         )
 427         if self.mode.preview:
 428             self.visit_except_clause = partial(
 429                 v, keywords={"except"}, parens={"except"}
 430             )
 431             self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
 432         else:
 433             self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
 434             self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
 435         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
 436         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
 437         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
 438         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
 439         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
 440         self.visit_async_funcdef = self.visit_async_stmt
 441         self.visit_decorated = self.visit_decorators
 442
 443         # PEP 634
 444         self.visit_match_stmt = self.visit_match_case
 445         self.visit_case_block = self.visit_match_case
 446
 447
 448 def transform_line(
 449     line: Line, mode: Mode, features: Collection[Feature] = ()
 450 ) -> Iterator[Line]:
 451     """Transform a `line`, potentially splitting it into many lines.
 452
 453     They should fit in the allotted `line_length` but might not be able to.
 454
 455     `features` are syntactical features that may be used in the output.
 456     """
 457     if line.is_comment:
 458         yield line
 459         return
 460
 461     line_str = line_to_string(line)
 462
 463     ll = mode.line_length
 464     sn = mode.string_normalization
 465     string_merge = StringMerger(ll, sn)
 466     string_paren_strip = StringParenStripper(ll, sn)
 467     string_split = StringSplitter(ll, sn)
 468     string_paren_wrap = StringParenWrapper(ll, sn)
 469
 470     transformers: List[Transformer]
 471     if (
 472         not line.contains_uncollapsable_type_comments()
 473         and not line.should_split_rhs
 474         and not line.magic_trailing_comma
 475         and (
 476             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
 477             or line.contains_unsplittable_type_ignore()
 478         )
 479         and not (line.inside_brackets and line.contains_standalone_comments())
 480     ):
 481         # Only apply basic string preprocessing, since lines shouldn't be split here.
 482         if Preview.string_processing in mode:
 483             transformers = [string_merge, string_paren_strip]
 484         else:
 485             transformers = []
 486     elif line.is_def:
 487         transformers = [left_hand_split]
 488     else:
 489
 490         def _rhs(
 491             self: object, line: Line, features: Collection[Feature]
 492         ) -> Iterator[Line]:
 493             """Wraps calls to `right_hand_split`.
 494
 495             The calls increasingly `omit` right-hand trailers (bracket pairs with
 496             content), meaning the trailers get glued together to split on another
 497             bracket pair instead.
 498             """
 499             for omit in generate_trailers_to_omit(line, mode.line_length):
 500                 lines = list(
 501                     right_hand_split(line, mode.line_length, features, omit=omit)
 502                 )
 503                 # Note: this check is only able to figure out if the first line of the
 504                 # *current* transformation fits in the line length.  This is true only
 505                 # for simple cases.  All others require running more transforms via
 506                 # `transform_line()`.  This check doesn't know if those would succeed.
 507                 if is_line_short_enough(lines[0], line_length=mode.line_length):
 508                     yield from lines
 509                     return
 510
 511             # All splits failed, best effort split with no omits.
 512             # This mostly happens to multiline strings that are by definition
 513             # reported as not fitting a single line, as well as lines that contain
 514             # trailing commas (those have to be exploded).
 515             yield from right_hand_split(
 516                 line, line_length=mode.line_length, features=features
 517             )
 518
 519         # HACK: nested functions (like _rhs) compiled by mypyc don't retain their
 520         # __name__ attribute which is needed in `run_transformer` further down.
 521         # Unfortunately a nested class breaks mypyc too. So a class must be created
 522         # via type ... https://github.com/mypyc/mypyc/issues/884
 523         rhs = type("rhs", (), {"__call__": _rhs})()
 524
 525         if Preview.string_processing in mode:
 526             if line.inside_brackets:
 527                 transformers = [
 528                     string_merge,
 529                     string_paren_strip,
 530                     string_split,
 531                     delimiter_split,
 532                     standalone_comment_split,
 533                     string_paren_wrap,
 534                     rhs,
 535                 ]
 536             else:
 537                 transformers = [
 538                     string_merge,
 539                     string_paren_strip,
 540                     string_split,
 541                     string_paren_wrap,
 542                     rhs,
 543                 ]
 544         else:
 545             if line.inside_brackets:
 546                 transformers = [delimiter_split, standalone_comment_split, rhs]
 547             else:
 548                 transformers = [rhs]
 549     # It's always safe to attempt hugging of power operations and pretty much every line
 550     # could match.
 551     transformers.append(hug_power_op)
 552
 553     for transform in transformers:
 554         # We are accumulating lines in `result` because we might want to abort
 555         # mission and return the original line in the end, or attempt a different
 556         # split altogether.
 557         try:
 558             result = run_transformer(line, transform, mode, features, line_str=line_str)
 559         except CannotTransform:
 560             continue
 561         else:
 562             yield from result
 563             break
 564
 565     else:
 566         yield line
 567
 568
 569 class _BracketSplitComponent(Enum):
 570     head = auto()
 571     body = auto()
 572     tail = auto()
 573
 574
 575 def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
 576     """Split line into many lines, starting with the first matching bracket pair.
 577
 578     Note: this usually looks weird, only use this for function definitions.
 579     Prefer RHS otherwise.  This is why this function is not symmetrical with
 580     :func:`right_hand_split` which also handles optional parentheses.
 581     """
 582     tail_leaves: List[Leaf] = []
 583     body_leaves: List[Leaf] = []
 584     head_leaves: List[Leaf] = []
 585     current_leaves = head_leaves
 586     matching_bracket: Optional[Leaf] = None
 587     for leaf in line.leaves:
 588         if (
 589             current_leaves is body_leaves
 590             and leaf.type in CLOSING_BRACKETS
 591             and leaf.opening_bracket is matching_bracket
 592             and isinstance(matching_bracket, Leaf)
 593         ):
 594             ensure_visible(leaf)
 595             ensure_visible(matching_bracket)
 596             current_leaves = tail_leaves if body_leaves else head_leaves
 597         current_leaves.append(leaf)
 598         if current_leaves is head_leaves:
 599             if leaf.type in OPENING_BRACKETS:
 600                 matching_bracket = leaf
 601                 current_leaves = body_leaves
 602     if not matching_bracket:
 603         raise CannotSplit("No brackets found")
 604
 605     head = bracket_split_build_line(
 606         head_leaves, line, matching_bracket, component=_BracketSplitComponent.head
 607     )
 608     body = bracket_split_build_line(
 609         body_leaves, line, matching_bracket, component=_BracketSplitComponent.body
 610     )
 611     tail = bracket_split_build_line(
 612         tail_leaves, line, matching_bracket, component=_BracketSplitComponent.tail
 613     )
 614     bracket_split_succeeded_or_raise(head, body, tail)
 615     for result in (head, body, tail):
 616         if result:
 617             yield result
 618
 619
 620 def right_hand_split(
 621     line: Line,
 622     line_length: int,
 623     features: Collection[Feature] = (),
 624     omit: Collection[LeafID] = (),
 625 ) -> Iterator[Line]:
 626     """Split line into many lines, starting with the last matching bracket pair.
 627
 628     If the split was by optional parentheses, attempt splitting without them, too.
 629     `omit` is a collection of closing bracket IDs that shouldn't be considered for
 630     this split.
 631
 632     Note: running this function modifies `bracket_depth` on the leaves of `line`.
 633     """
 634     tail_leaves: List[Leaf] = []
 635     body_leaves: List[Leaf] = []
 636     head_leaves: List[Leaf] = []
 637     current_leaves = tail_leaves
 638     opening_bracket: Optional[Leaf] = None
 639     closing_bracket: Optional[Leaf] = None
 640     for leaf in reversed(line.leaves):
 641         if current_leaves is body_leaves:
 642             if leaf is opening_bracket:
 643                 current_leaves = head_leaves if body_leaves else tail_leaves
 644         current_leaves.append(leaf)
 645         if current_leaves is tail_leaves:
 646             if leaf.type in CLOSING_BRACKETS and id(leaf) not in omit:
 647                 opening_bracket = leaf.opening_bracket
 648                 closing_bracket = leaf
 649                 current_leaves = body_leaves
 650     if not (opening_bracket and closing_bracket and head_leaves):
 651         # If there is no opening or closing_bracket that means the split failed and
 652         # all content is in the tail.  Otherwise, if `head_leaves` are empty, it means
 653         # the matching `opening_bracket` wasn't available on `line` anymore.
 654         raise CannotSplit("No brackets found")
 655
 656     tail_leaves.reverse()
 657     body_leaves.reverse()
 658     head_leaves.reverse()
 659     head = bracket_split_build_line(
 660         head_leaves, line, opening_bracket, component=_BracketSplitComponent.head
 661     )
 662     body = bracket_split_build_line(
 663         body_leaves, line, opening_bracket, component=_BracketSplitComponent.body
 664     )
 665     tail = bracket_split_build_line(
 666         tail_leaves, line, opening_bracket, component=_BracketSplitComponent.tail
 667     )
 668     bracket_split_succeeded_or_raise(head, body, tail)
 669     if (
 670         Feature.FORCE_OPTIONAL_PARENTHESES not in features
 671         # the opening bracket is an optional paren
 672         and opening_bracket.type == token.LPAR
 673         and not opening_bracket.value
 674         # the closing bracket is an optional paren
 675         and closing_bracket.type == token.RPAR
 676         and not closing_bracket.value
 677         # it's not an import (optional parens are the only thing we can split on
 678         # in this case; attempting a split without them is a waste of time)
 679         and not line.is_import
 680         # there are no standalone comments in the body
 681         and not body.contains_standalone_comments(0)
 682         # and we can actually remove the parens
 683         and can_omit_invisible_parens(body, line_length)
 684     ):
 685         omit = {id(closing_bracket), *omit}
 686         try:
 687             yield from right_hand_split(line, line_length, features=features, omit=omit)
 688             return
 689
 690         except CannotSplit as e:
 691             if not (
 692                 can_be_split(body)
 693                 or is_line_short_enough(body, line_length=line_length)
 694             ):
 695                 raise CannotSplit(
 696                     "Splitting failed, body is still too long and can't be split."
 697                 ) from e
 698
 699             elif head.contains_multiline_strings() or tail.contains_multiline_strings():
 700                 raise CannotSplit(
 701                     "The current optional pair of parentheses is bound to fail to"
 702                     " satisfy the splitting algorithm because the head or the tail"
 703                     " contains multiline strings which by definition never fit one"
 704                     " line."
 705                 ) from e
 706
 707     ensure_visible(opening_bracket)
 708     ensure_visible(closing_bracket)
 709     for result in (head, body, tail):
 710         if result:
 711             yield result
 712
 713
 714 def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
 715     """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
 716
 717     Do nothing otherwise.
 718
 719     A left- or right-hand split is based on a pair of brackets. Content before
 720     (and including) the opening bracket is left on one line, content inside the
 721     brackets is put on a separate line, and finally content starting with and
 722     following the closing bracket is put on a separate line.
 723
 724     Those are called `head`, `body`, and `tail`, respectively. If the split
 725     produced the same line (all content in `head`) or ended up with an empty `body`
 726     and the `tail` is just the closing bracket, then it's considered failed.
 727     """
 728     tail_len = len(str(tail).strip())
 729     if not body:
 730         if tail_len == 0:
 731             raise CannotSplit("Splitting brackets produced the same line")
 732
 733         elif tail_len < 3:
 734             raise CannotSplit(
 735                 f"Splitting brackets on an empty body to save {tail_len} characters is"
 736                 " not worth it"
 737             )
 738
 739
 740 def bracket_split_build_line(
 741     leaves: List[Leaf],
 742     original: Line,
 743     opening_bracket: Leaf,
 744     *,
 745     component: _BracketSplitComponent,
 746 ) -> Line:
 747     """Return a new line with given `leaves` and respective comments from `original`.
 748
 749     If it's the head component, brackets will be tracked so trailing commas are
 750     respected.
 751
 752     If it's the body component, the result line is one-indented inside brackets and as
 753     such has its first leaf's prefix normalized and a trailing comma added when
 754     expected.
 755     """
 756     result = Line(mode=original.mode, depth=original.depth)
 757     if component is _BracketSplitComponent.body:
 758         result.inside_brackets = True
 759         result.depth += 1
 760         if leaves:
 761             # Since body is a new indent level, remove spurious leading whitespace.
 762             normalize_prefix(leaves[0], inside_brackets=True)
 763             # Ensure a trailing comma for imports and standalone function arguments, but
 764             # be careful not to add one after any comments or within type annotations.
 765             no_commas = (
 766                 original.is_def
 767                 and opening_bracket.value == "("
 768                 and not any(leaf.type == token.COMMA for leaf in leaves)
 769                 # In particular, don't add one within a parenthesized return annotation.
 770                 # Unfortunately the indicator we're in a return annotation (RARROW) may
 771                 # be defined directly in the parent node, the parent of the parent ...
 772                 # and so on depending on how complex the return annotation is.
 773                 # This isn't perfect and there's some false negatives but they are in
 774                 # contexts were a comma is actually fine.
 775                 and not any(
 776                     node.prev_sibling.type == RARROW
 777                     for node in (
 778                         leaves[0].parent,
 779                         getattr(leaves[0].parent, "parent", None),
 780                     )
 781                     if isinstance(node, Node) and isinstance(node.prev_sibling, Leaf)
 782                 )
 783             )
 784
 785             if original.is_import or no_commas:
 786                 for i in range(len(leaves) - 1, -1, -1):
 787                     if leaves[i].type == STANDALONE_COMMENT:
 788                         continue
 789
 790                     if leaves[i].type != token.COMMA:
 791                         new_comma = Leaf(token.COMMA, ",")
 792                         leaves.insert(i + 1, new_comma)
 793                     break
 794
 795     leaves_to_track: Set[LeafID] = set()
 796     if (
 797         Preview.handle_trailing_commas_in_head in original.mode
 798         and component is _BracketSplitComponent.head
 799     ):
 800         leaves_to_track = get_leaves_inside_matching_brackets(leaves)
 801     # Populate the line
 802     for leaf in leaves:
 803         result.append(
 804             leaf,
 805             preformatted=True,
 806             track_bracket=id(leaf) in leaves_to_track,
 807         )
 808         for comment_after in original.comments_after(leaf):
 809             result.append(comment_after, preformatted=True)
 810     if component is _BracketSplitComponent.body and should_split_line(
 811         result, opening_bracket
 812     ):
 813         result.should_split_rhs = True
 814     return result
 815
 816
 817 def dont_increase_indentation(split_func: Transformer) -> Transformer:
 818     """Normalize prefix of the first leaf in every line returned by `split_func`.
 819
 820     This is a decorator over relevant split functions.
 821     """
 822
 823     @wraps(split_func)
 824     def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
 825         for split_line in split_func(line, features):
 826             normalize_prefix(split_line.leaves[0], inside_brackets=True)
 827             yield split_line
 828
 829     return split_wrapper
 830
 831
 832 @dont_increase_indentation
 833 def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
 834     """Split according to delimiters of the highest priority.
 835
 836     If the appropriate Features are given, the split will add trailing commas
 837     also in function signatures and calls that contain `*` and `**`.
 838     """
 839     try:
 840         last_leaf = line.leaves[-1]
 841     except IndexError:
 842         raise CannotSplit("Line empty") from None
 843
 844     bt = line.bracket_tracker
 845     try:
 846         delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
 847     except ValueError:
 848         raise CannotSplit("No delimiters found") from None
 849
 850     if delimiter_priority == DOT_PRIORITY:
 851         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
 852             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
 853
 854     current_line = Line(
 855         mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 856     )
 857     lowest_depth = sys.maxsize
 858     trailing_comma_safe = True
 859
 860     def append_to_line(leaf: Leaf) -> Iterator[Line]:
 861         """Append `leaf` to current line or to new line if appending impossible."""
 862         nonlocal current_line
 863         try:
 864             current_line.append_safe(leaf, preformatted=True)
 865         except ValueError:
 866             yield current_line
 867
 868             current_line = Line(
 869                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 870             )
 871             current_line.append(leaf)
 872
 873     for leaf in line.leaves:
 874         yield from append_to_line(leaf)
 875
 876         for comment_after in line.comments_after(leaf):
 877             yield from append_to_line(comment_after)
 878
 879         lowest_depth = min(lowest_depth, leaf.bracket_depth)
 880         if leaf.bracket_depth == lowest_depth:
 881             if is_vararg(leaf, within={syms.typedargslist}):
 882                 trailing_comma_safe = (
 883                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
 884                 )
 885             elif is_vararg(leaf, within={syms.arglist, syms.argument}):
 886                 trailing_comma_safe = (
 887                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
 888                 )
 889
 890         leaf_priority = bt.delimiters.get(id(leaf))
 891         if leaf_priority == delimiter_priority:
 892             yield current_line
 893
 894             current_line = Line(
 895                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 896             )
 897     if current_line:
 898         if (
 899             trailing_comma_safe
 900             and delimiter_priority == COMMA_PRIORITY
 901             and current_line.leaves[-1].type != token.COMMA
 902             and current_line.leaves[-1].type != STANDALONE_COMMENT
 903         ):
 904             new_comma = Leaf(token.COMMA, ",")
 905             current_line.append(new_comma)
 906         yield current_line
 907
 908
 909 @dont_increase_indentation
 910 def standalone_comment_split(
 911     line: Line, features: Collection[Feature] = ()
 912 ) -> Iterator[Line]:
 913     """Split standalone comments from the rest of the line."""
 914     if not line.contains_standalone_comments(0):
 915         raise CannotSplit("Line does not have any standalone comments")
 916
 917     current_line = Line(
 918         mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 919     )
 920
 921     def append_to_line(leaf: Leaf) -> Iterator[Line]:
 922         """Append `leaf` to current line or to new line if appending impossible."""
 923         nonlocal current_line
 924         try:
 925             current_line.append_safe(leaf, preformatted=True)
 926         except ValueError:
 927             yield current_line
 928
 929             current_line = Line(
 930                 line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 931             )
 932             current_line.append(leaf)
 933
 934     for leaf in line.leaves:
 935         yield from append_to_line(leaf)
 936
 937         for comment_after in line.comments_after(leaf):
 938             yield from append_to_line(comment_after)
 939
 940     if current_line:
 941         yield current_line
 942
 943
 944 def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
 945     """Leave existing extra newlines if not `inside_brackets`. Remove everything
 946     else.
 947
 948     Note: don't use backslashes for formatting or you'll lose your voting rights.
 949     """
 950     if not inside_brackets:
 951         spl = leaf.prefix.split("#")
 952         if "\\" not in spl[0]:
 953             nl_count = spl[-1].count("\n")
 954             if len(spl) > 1:
 955                 nl_count -= 1
 956             leaf.prefix = "\n" * nl_count
 957             return
 958
 959     leaf.prefix = ""
 960
 961
 962 def normalize_invisible_parens(
 963     node: Node, parens_after: Set[str], *, preview: bool
 964 ) -> None:
 965     """Make existing optional parentheses invisible or create new ones.
 966
 967     `parens_after` is a set of string leaf values immediately after which parens
 968     should be put.
 969
 970     Standardizes on visible parentheses for single-element tuples, and keeps
 971     existing visible parentheses for other tuples and generator expressions.
 972     """
 973     for pc in list_comments(node.prefix, is_endmarker=False, preview=preview):
 974         if pc.value in FMT_OFF:
 975             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
 976             return
 977     check_lpar = False
 978     for index, child in enumerate(list(node.children)):
 979         # Fixes a bug where invisible parens are not properly stripped from
 980         # assignment statements that contain type annotations.
 981         if isinstance(child, Node) and child.type == syms.annassign:
 982             normalize_invisible_parens(
 983                 child, parens_after=parens_after, preview=preview
 984             )
 985
 986         # Add parentheses around long tuple unpacking in assignments.
 987         if (
 988             index == 0
 989             and isinstance(child, Node)
 990             and child.type == syms.testlist_star_expr
 991         ):
 992             check_lpar = True
 993
 994         if check_lpar:
 995             if (
 996                 preview
 997                 and child.type == syms.atom
 998                 and node.type == syms.for_stmt
 999                 and isinstance(child.prev_sibling, Leaf)
1000                 and child.prev_sibling.type == token.NAME
1001                 and child.prev_sibling.value == "for"
1002             ):
1003                 if maybe_make_parens_invisible_in_atom(
1004                     child,
1005                     parent=node,
1006                     remove_brackets_around_comma=True,
1007                 ):
1008                     wrap_in_parentheses(node, child, visible=False)
1009             elif preview and isinstance(child, Node) and node.type == syms.with_stmt:
1010                 remove_with_parens(child, node)
1011             elif child.type == syms.atom:
1012                 if maybe_make_parens_invisible_in_atom(
1013                     child,
1014                     parent=node,
1015                 ):
1016                     wrap_in_parentheses(node, child, visible=False)
1017             elif is_one_tuple(child):
1018                 wrap_in_parentheses(node, child, visible=True)
1019             elif node.type == syms.import_from:
1020                 # "import from" nodes store parentheses directly as part of
1021                 # the statement
1022                 if is_lpar_token(child):
1023                     assert is_rpar_token(node.children[-1])
1024                     # make parentheses invisible
1025                     child.value = ""
1026                     node.children[-1].value = ""
1027                 elif child.type != token.STAR:
1028                     # insert invisible parentheses
1029                     node.insert_child(index, Leaf(token.LPAR, ""))
1030                     node.append_child(Leaf(token.RPAR, ""))
1031                 break
1032             elif (
1033                 index == 1
1034                 and child.type == token.STAR
1035                 and node.type == syms.except_clause
1036             ):
1037                 # In except* (PEP 654), the star is actually part of
1038                 # of the keyword. So we need to skip the insertion of
1039                 # invisible parentheses to work more precisely.
1040                 continue
1041
1042             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
1043                 wrap_in_parentheses(node, child, visible=False)
1044
1045         comma_check = child.type == token.COMMA if preview else False
1046
1047         check_lpar = isinstance(child, Leaf) and (
1048             child.value in parens_after or comma_check
1049         )
1050
1051
1052 def remove_await_parens(node: Node) -> None:
1053     if node.children[0].type == token.AWAIT and len(node.children) > 1:
1054         if (
1055             node.children[1].type == syms.atom
1056             and node.children[1].children[0].type == token.LPAR
1057         ):
1058             if maybe_make_parens_invisible_in_atom(
1059                 node.children[1],
1060                 parent=node,
1061                 remove_brackets_around_comma=True,
1062             ):
1063                 wrap_in_parentheses(node, node.children[1], visible=False)
1064
1065             # Since await is an expression we shouldn't remove
1066             # brackets in cases where this would change
1067             # the AST due to operator precedence.
1068             # Therefore we only aim to remove brackets around
1069             # power nodes that aren't also await expressions themselves.
1070             # https://peps.python.org/pep-0492/#updated-operator-precedence-table
1071             # N.B. We've still removed any redundant nested brackets though :)
1072             opening_bracket = cast(Leaf, node.children[1].children[0])
1073             closing_bracket = cast(Leaf, node.children[1].children[-1])
1074             bracket_contents = cast(Node, node.children[1].children[1])
1075             if bracket_contents.type != syms.power:
1076                 ensure_visible(opening_bracket)
1077                 ensure_visible(closing_bracket)
1078             elif (
1079                 bracket_contents.type == syms.power
1080                 and bracket_contents.children[0].type == token.AWAIT
1081             ):
1082                 ensure_visible(opening_bracket)
1083                 ensure_visible(closing_bracket)
1084                 # If we are in a nested await then recurse down.
1085                 remove_await_parens(bracket_contents)
1086
1087
1088 def remove_with_parens(node: Node, parent: Node) -> None:
1089     """Recursively hide optional parens in `with` statements."""
1090     # Removing all unnecessary parentheses in with statements in one pass is a tad
1091     # complex as different variations of bracketed statements result in pretty
1092     # different parse trees:
1093     #
1094     # with (open("file")) as f:                       # this is an asexpr_test
1095     #     ...
1096     #
1097     # with (open("file") as f):                       # this is an atom containing an
1098     #     ...                                         # asexpr_test
1099     #
1100     # with (open("file")) as f, (open("file")) as f:  # this is asexpr_test, COMMA,
1101     #     ...                                         # asexpr_test
1102     #
1103     # with (open("file") as f, open("file") as f):    # an atom containing a
1104     #     ...                                         # testlist_gexp which then
1105     #                                                 # contains multiple asexpr_test(s)
1106     if node.type == syms.atom:
1107         if maybe_make_parens_invisible_in_atom(
1108             node,
1109             parent=parent,
1110             remove_brackets_around_comma=True,
1111         ):
1112             wrap_in_parentheses(parent, node, visible=False)
1113         if isinstance(node.children[1], Node):
1114             remove_with_parens(node.children[1], node)
1115     elif node.type == syms.testlist_gexp:
1116         for child in node.children:
1117             if isinstance(child, Node):
1118                 remove_with_parens(child, node)
1119     elif node.type == syms.asexpr_test and not any(
1120         leaf.type == token.COLONEQUAL for leaf in node.leaves()
1121     ):
1122         if maybe_make_parens_invisible_in_atom(
1123             node.children[0],
1124             parent=node,
1125             remove_brackets_around_comma=True,
1126         ):
1127             wrap_in_parentheses(node, node.children[0], visible=False)
1128
1129
1130 def maybe_make_parens_invisible_in_atom(
1131     node: LN,
1132     parent: LN,
1133     remove_brackets_around_comma: bool = False,
1134 ) -> bool:
1135     """If it's safe, make the parens in the atom `node` invisible, recursively.
1136     Additionally, remove repeated, adjacent invisible parens from the atom `node`
1137     as they are redundant.
1138
1139     Returns whether the node should itself be wrapped in invisible parentheses.
1140     """
1141     if (
1142         node.type != syms.atom
1143         or is_empty_tuple(node)
1144         or is_one_tuple(node)
1145         or (is_yield(node) and parent.type != syms.expr_stmt)
1146         or (
1147             # This condition tries to prevent removing non-optional brackets
1148             # around a tuple, however, can be a bit overzealous so we provide
1149             # and option to skip this check for `for` and `with` statements.
1150             not remove_brackets_around_comma
1151             and max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
1152         )
1153     ):
1154         return False
1155
1156     if is_walrus_assignment(node):
1157         if parent.type in [
1158             syms.annassign,
1159             syms.expr_stmt,
1160             syms.assert_stmt,
1161             syms.return_stmt,
1162             # these ones aren't useful to end users, but they do please fuzzers
1163             syms.for_stmt,
1164             syms.del_stmt,
1165         ]:
1166             return False
1167
1168     first = node.children[0]
1169     last = node.children[-1]
1170     if is_lpar_token(first) and is_rpar_token(last):
1171         middle = node.children[1]
1172         # make parentheses invisible
1173         first.value = ""
1174         last.value = ""
1175         maybe_make_parens_invisible_in_atom(
1176             middle,
1177             parent=parent,
1178             remove_brackets_around_comma=remove_brackets_around_comma,
1179         )
1180
1181         if is_atom_with_invisible_parens(middle):
1182             # Strip the invisible parens from `middle` by replacing
1183             # it with the child in-between the invisible parens
1184             middle.replace(middle.children[1])
1185
1186         return False
1187
1188     return True
1189
1190
1191 def should_split_line(line: Line, opening_bracket: Leaf) -> bool:
1192     """Should `line` be immediately split with `delimiter_split()` after RHS?"""
1193
1194     if not (opening_bracket.parent and opening_bracket.value in "[{("):
1195         return False
1196
1197     # We're essentially checking if the body is delimited by commas and there's more
1198     # than one of them (we're excluding the trailing comma and if the delimiter priority
1199     # is still commas, that means there's more).
1200     exclude = set()
1201     trailing_comma = False
1202     try:
1203         last_leaf = line.leaves[-1]
1204         if last_leaf.type == token.COMMA:
1205             trailing_comma = True
1206             exclude.add(id(last_leaf))
1207         max_priority = line.bracket_tracker.max_delimiter_priority(exclude=exclude)
1208     except (IndexError, ValueError):
1209         return False
1210
1211     return max_priority == COMMA_PRIORITY and (
1212         (line.mode.magic_trailing_comma and trailing_comma)
1213         # always explode imports
1214         or opening_bracket.parent.type in {syms.atom, syms.import_from}
1215     )
1216
1217
1218 def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[LeafID]]:
1219     """Generate sets of closing bracket IDs that should be omitted in a RHS.
1220
1221     Brackets can be omitted if the entire trailer up to and including
1222     a preceding closing bracket fits in one line.
1223
1224     Yielded sets are cumulative (contain results of previous yields, too).  First
1225     set is empty, unless the line should explode, in which case bracket pairs until
1226     the one that needs to explode are omitted.
1227     """
1228
1229     omit: Set[LeafID] = set()
1230     if not line.magic_trailing_comma:
1231         yield omit
1232
1233     length = 4 * line.depth
1234     opening_bracket: Optional[Leaf] = None
1235     closing_bracket: Optional[Leaf] = None
1236     inner_brackets: Set[LeafID] = set()
1237     for index, leaf, leaf_length in line.enumerate_with_length(reversed=True):
1238         length += leaf_length
1239         if length > line_length:
1240             break
1241
1242         has_inline_comment = leaf_length > len(leaf.value) + len(leaf.prefix)
1243         if leaf.type == STANDALONE_COMMENT or has_inline_comment:
1244             break
1245
1246         if opening_bracket:
1247             if leaf is opening_bracket:
1248                 opening_bracket = None
1249             elif leaf.type in CLOSING_BRACKETS:
1250                 prev = line.leaves[index - 1] if index > 0 else None
1251                 if (
1252                     prev
1253                     and prev.type == token.COMMA
1254                     and leaf.opening_bracket is not None
1255                     and not is_one_sequence_between(
1256                         leaf.opening_bracket, leaf, line.leaves
1257                     )
1258                 ):
1259                     # Never omit bracket pairs with trailing commas.
1260                     # We need to explode on those.
1261                     break
1262
1263                 inner_brackets.add(id(leaf))
1264         elif leaf.type in CLOSING_BRACKETS:
1265             prev = line.leaves[index - 1] if index > 0 else None
1266             if prev and prev.type in OPENING_BRACKETS:
1267                 # Empty brackets would fail a split so treat them as "inner"
1268                 # brackets (e.g. only add them to the `omit` set if another
1269                 # pair of brackets was good enough.
1270                 inner_brackets.add(id(leaf))
1271                 continue
1272
1273             if closing_bracket:
1274                 omit.add(id(closing_bracket))
1275                 omit.update(inner_brackets)
1276                 inner_brackets.clear()
1277                 yield omit
1278
1279             if (
1280                 prev
1281                 and prev.type == token.COMMA
1282                 and leaf.opening_bracket is not None
1283                 and not is_one_sequence_between(leaf.opening_bracket, leaf, line.leaves)
1284             ):
1285                 # Never omit bracket pairs with trailing commas.
1286                 # We need to explode on those.
1287                 break
1288
1289             if leaf.value:
1290                 opening_bracket = leaf.opening_bracket
1291                 closing_bracket = leaf
1292
1293
1294 def run_transformer(
1295     line: Line,
1296     transform: Transformer,
1297     mode: Mode,
1298     features: Collection[Feature],
1299     *,
1300     line_str: str = "",
1301 ) -> List[Line]:
1302     if not line_str:
1303         line_str = line_to_string(line)
1304     result: List[Line] = []
1305     for transformed_line in transform(line, features):
1306         if str(transformed_line).strip("\n") == line_str:
1307             raise CannotTransform("Line transformer returned an unchanged result")
1308
1309         result.extend(transform_line(transformed_line, mode=mode, features=features))
1310
1311     if (
1312         transform.__class__.__name__ != "rhs"
1313         or not line.bracket_tracker.invisible
1314         or any(bracket.value for bracket in line.bracket_tracker.invisible)
1315         or line.contains_multiline_strings()
1316         or result[0].contains_uncollapsable_type_comments()
1317         or result[0].contains_unsplittable_type_ignore()
1318         or is_line_short_enough(result[0], line_length=mode.line_length)
1319         # If any leaves have no parents (which _can_ occur since
1320         # `transform(line)` potentially destroys the line's underlying node
1321         # structure), then we can't proceed. Doing so would cause the below
1322         # call to `append_leaves()` to fail.
1323         or any(leaf.parent is None for leaf in line.leaves)
1324     ):
1325         return result
1326
1327     line_copy = line.clone()
1328     append_leaves(line_copy, line, line.leaves)
1329     features_fop = set(features) | {Feature.FORCE_OPTIONAL_PARENTHESES}
1330     second_opinion = run_transformer(
1331         line_copy, transform, mode, features_fop, line_str=line_str
1332     )
1333     if all(
1334         is_line_short_enough(ln, line_length=mode.line_length) for ln in second_opinion
1335     ):
1336         result = second_opinion
1337     return result