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, then we need to add the length
 393                 # of the indent, prefix, and starting quotes. Ending quotes are
 394                 # handled later.
 395                 lines = docstring.splitlines()
 396                 last_line_length = len(lines[-1]) if docstring else 0
 397
 398                 if len(lines) == 1:
 399                     last_line_length += len(indent) + len(prefix) + quote_len
 400
 401                 # If adding closing quotes would cause the last line to exceed
 402                 # the maximum line length then put a line break before the
 403                 # closing quotes
 404                 if last_line_length + quote_len > self.mode.line_length:
 405                     leaf.value = prefix + quote + docstring + "\n" + indent + quote
 406                 else:
 407                     leaf.value = prefix + quote + docstring + quote
 408             else:
 409                 leaf.value = prefix + quote + docstring + quote
 410
 411         yield from self.visit_default(leaf)
 412
 413     def __post_init__(self) -> None:
 414         """You are in a twisty little maze of passages."""
 415         self.current_line = Line(mode=self.mode)
 416
 417         v = self.visit_stmt
 418         Ø: Set[str] = set()
 419         self.visit_assert_stmt = partial(v, keywords={"assert"}, parens={"assert", ","})
 420         self.visit_if_stmt = partial(
 421             v, keywords={"if", "else", "elif"}, parens={"if", "elif"}
 422         )
 423         self.visit_while_stmt = partial(v, keywords={"while", "else"}, parens={"while"})
 424         self.visit_for_stmt = partial(v, keywords={"for", "else"}, parens={"for", "in"})
 425         self.visit_try_stmt = partial(
 426             v, keywords={"try", "except", "else", "finally"}, parens=Ø
 427         )
 428         if self.mode.preview:
 429             self.visit_except_clause = partial(
 430                 v, keywords={"except"}, parens={"except"}
 431             )
 432             self.visit_with_stmt = partial(v, keywords={"with"}, parens={"with"})
 433         else:
 434             self.visit_except_clause = partial(v, keywords={"except"}, parens=Ø)
 435             self.visit_with_stmt = partial(v, keywords={"with"}, parens=Ø)
 436         self.visit_classdef = partial(v, keywords={"class"}, parens=Ø)
 437         self.visit_expr_stmt = partial(v, keywords=Ø, parens=ASSIGNMENTS)
 438         self.visit_return_stmt = partial(v, keywords={"return"}, parens={"return"})
 439         self.visit_import_from = partial(v, keywords=Ø, parens={"import"})
 440         self.visit_del_stmt = partial(v, keywords=Ø, parens={"del"})
 441         self.visit_async_funcdef = self.visit_async_stmt
 442         self.visit_decorated = self.visit_decorators
 443
 444         # PEP 634
 445         self.visit_match_stmt = self.visit_match_case
 446         self.visit_case_block = self.visit_match_case
 447
 448
 449 def transform_line(
 450     line: Line, mode: Mode, features: Collection[Feature] = ()
 451 ) -> Iterator[Line]:
 452     """Transform a `line`, potentially splitting it into many lines.
 453
 454     They should fit in the allotted `line_length` but might not be able to.
 455
 456     `features` are syntactical features that may be used in the output.
 457     """
 458     if line.is_comment:
 459         yield line
 460         return
 461
 462     line_str = line_to_string(line)
 463
 464     ll = mode.line_length
 465     sn = mode.string_normalization
 466     string_merge = StringMerger(ll, sn)
 467     string_paren_strip = StringParenStripper(ll, sn)
 468     string_split = StringSplitter(ll, sn)
 469     string_paren_wrap = StringParenWrapper(ll, sn)
 470
 471     transformers: List[Transformer]
 472     if (
 473         not line.contains_uncollapsable_type_comments()
 474         and not line.should_split_rhs
 475         and not line.magic_trailing_comma
 476         and (
 477             is_line_short_enough(line, line_length=mode.line_length, line_str=line_str)
 478             or line.contains_unsplittable_type_ignore()
 479         )
 480         and not (line.inside_brackets and line.contains_standalone_comments())
 481     ):
 482         # Only apply basic string preprocessing, since lines shouldn't be split here.
 483         if Preview.string_processing in mode:
 484             transformers = [string_merge, string_paren_strip]
 485         else:
 486             transformers = []
 487     elif line.is_def:
 488         transformers = [left_hand_split]
 489     else:
 490
 491         def _rhs(
 492             self: object, line: Line, features: Collection[Feature]
 493         ) -> Iterator[Line]:
 494             """Wraps calls to `right_hand_split`.
 495
 496             The calls increasingly `omit` right-hand trailers (bracket pairs with
 497             content), meaning the trailers get glued together to split on another
 498             bracket pair instead.
 499             """
 500             for omit in generate_trailers_to_omit(line, mode.line_length):
 501                 lines = list(
 502                     right_hand_split(line, mode.line_length, features, omit=omit)
 503                 )
 504                 # Note: this check is only able to figure out if the first line of the
 505                 # *current* transformation fits in the line length.  This is true only
 506                 # for simple cases.  All others require running more transforms via
 507                 # `transform_line()`.  This check doesn't know if those would succeed.
 508                 if is_line_short_enough(lines[0], line_length=mode.line_length):
 509                     yield from lines
 510                     return
 511
 512             # All splits failed, best effort split with no omits.
 513             # This mostly happens to multiline strings that are by definition
 514             # reported as not fitting a single line, as well as lines that contain
 515             # trailing commas (those have to be exploded).
 516             yield from right_hand_split(
 517                 line, line_length=mode.line_length, features=features
 518             )
 519
 520         # HACK: nested functions (like _rhs) compiled by mypyc don't retain their
 521         # __name__ attribute which is needed in `run_transformer` further down.
 522         # Unfortunately a nested class breaks mypyc too. So a class must be created
 523         # via type ... https://github.com/mypyc/mypyc/issues/884
 524         rhs = type("rhs", (), {"__call__": _rhs})()
 525
 526         if Preview.string_processing in mode:
 527             if line.inside_brackets:
 528                 transformers = [
 529                     string_merge,
 530                     string_paren_strip,
 531                     string_split,
 532                     delimiter_split,
 533                     standalone_comment_split,
 534                     string_paren_wrap,
 535                     rhs,
 536                 ]
 537             else:
 538                 transformers = [
 539                     string_merge,
 540                     string_paren_strip,
 541                     string_split,
 542                     string_paren_wrap,
 543                     rhs,
 544                 ]
 545         else:
 546             if line.inside_brackets:
 547                 transformers = [delimiter_split, standalone_comment_split, rhs]
 548             else:
 549                 transformers = [rhs]
 550     # It's always safe to attempt hugging of power operations and pretty much every line
 551     # could match.
 552     transformers.append(hug_power_op)
 553
 554     for transform in transformers:
 555         # We are accumulating lines in `result` because we might want to abort
 556         # mission and return the original line in the end, or attempt a different
 557         # split altogether.
 558         try:
 559             result = run_transformer(line, transform, mode, features, line_str=line_str)
 560         except CannotTransform:
 561             continue
 562         else:
 563             yield from result
 564             break
 565
 566     else:
 567         yield line
 568
 569
 570 class _BracketSplitComponent(Enum):
 571     head = auto()
 572     body = auto()
 573     tail = auto()
 574
 575
 576 def left_hand_split(line: Line, _features: Collection[Feature] = ()) -> Iterator[Line]:
 577     """Split line into many lines, starting with the first matching bracket pair.
 578
 579     Note: this usually looks weird, only use this for function definitions.
 580     Prefer RHS otherwise.  This is why this function is not symmetrical with
 581     :func:`right_hand_split` which also handles optional parentheses.
 582     """
 583     tail_leaves: List[Leaf] = []
 584     body_leaves: List[Leaf] = []
 585     head_leaves: List[Leaf] = []
 586     current_leaves = head_leaves
 587     matching_bracket: Optional[Leaf] = None
 588     for leaf in line.leaves:
 589         if (
 590             current_leaves is body_leaves
 591             and leaf.type in CLOSING_BRACKETS
 592             and leaf.opening_bracket is matching_bracket
 593             and isinstance(matching_bracket, Leaf)
 594         ):
 595             ensure_visible(leaf)
 596             ensure_visible(matching_bracket)
 597             current_leaves = tail_leaves if body_leaves else head_leaves
 598         current_leaves.append(leaf)
 599         if current_leaves is head_leaves:
 600             if leaf.type in OPENING_BRACKETS:
 601                 matching_bracket = leaf
 602                 current_leaves = body_leaves
 603     if not matching_bracket:
 604         raise CannotSplit("No brackets found")
 605
 606     head = bracket_split_build_line(
 607         head_leaves, line, matching_bracket, component=_BracketSplitComponent.head
 608     )
 609     body = bracket_split_build_line(
 610         body_leaves, line, matching_bracket, component=_BracketSplitComponent.body
 611     )
 612     tail = bracket_split_build_line(
 613         tail_leaves, line, matching_bracket, component=_BracketSplitComponent.tail
 614     )
 615     bracket_split_succeeded_or_raise(head, body, tail)
 616     for result in (head, body, tail):
 617         if result:
 618             yield result
 619
 620
 621 def right_hand_split(
 622     line: Line,
 623     line_length: int,
 624     features: Collection[Feature] = (),
 625     omit: Collection[LeafID] = (),
 626 ) -> Iterator[Line]:
 627     """Split line into many lines, starting with the last matching bracket pair.
 628
 629     If the split was by optional parentheses, attempt splitting without them, too.
 630     `omit` is a collection of closing bracket IDs that shouldn't be considered for
 631     this split.
 632
 633     Note: running this function modifies `bracket_depth` on the leaves of `line`.
 634     """
 635     tail_leaves: List[Leaf] = []
 636     body_leaves: List[Leaf] = []
 637     head_leaves: List[Leaf] = []
 638     current_leaves = tail_leaves
 639     opening_bracket: Optional[Leaf] = None
 640     closing_bracket: Optional[Leaf] = None
 641     for leaf in reversed(line.leaves):
 642         if current_leaves is body_leaves:
 643             if leaf is opening_bracket:
 644                 current_leaves = head_leaves if body_leaves else tail_leaves
 645         current_leaves.append(leaf)
 646         if current_leaves is tail_leaves:
 647             if leaf.type in CLOSING_BRACKETS and id(leaf) not in omit:
 648                 opening_bracket = leaf.opening_bracket
 649                 closing_bracket = leaf
 650                 current_leaves = body_leaves
 651     if not (opening_bracket and closing_bracket and head_leaves):
 652         # If there is no opening or closing_bracket that means the split failed and
 653         # all content is in the tail.  Otherwise, if `head_leaves` are empty, it means
 654         # the matching `opening_bracket` wasn't available on `line` anymore.
 655         raise CannotSplit("No brackets found")
 656
 657     tail_leaves.reverse()
 658     body_leaves.reverse()
 659     head_leaves.reverse()
 660     head = bracket_split_build_line(
 661         head_leaves, line, opening_bracket, component=_BracketSplitComponent.head
 662     )
 663     body = bracket_split_build_line(
 664         body_leaves, line, opening_bracket, component=_BracketSplitComponent.body
 665     )
 666     tail = bracket_split_build_line(
 667         tail_leaves, line, opening_bracket, component=_BracketSplitComponent.tail
 668     )
 669     bracket_split_succeeded_or_raise(head, body, tail)
 670     if (
 671         Feature.FORCE_OPTIONAL_PARENTHESES not in features
 672         # the opening bracket is an optional paren
 673         and opening_bracket.type == token.LPAR
 674         and not opening_bracket.value
 675         # the closing bracket is an optional paren
 676         and closing_bracket.type == token.RPAR
 677         and not closing_bracket.value
 678         # it's not an import (optional parens are the only thing we can split on
 679         # in this case; attempting a split without them is a waste of time)
 680         and not line.is_import
 681         # there are no standalone comments in the body
 682         and not body.contains_standalone_comments(0)
 683         # and we can actually remove the parens
 684         and can_omit_invisible_parens(body, line_length)
 685     ):
 686         omit = {id(closing_bracket), *omit}
 687         try:
 688             yield from right_hand_split(line, line_length, features=features, omit=omit)
 689             return
 690
 691         except CannotSplit as e:
 692             if not (
 693                 can_be_split(body)
 694                 or is_line_short_enough(body, line_length=line_length)
 695             ):
 696                 raise CannotSplit(
 697                     "Splitting failed, body is still too long and can't be split."
 698                 ) from e
 699
 700             elif head.contains_multiline_strings() or tail.contains_multiline_strings():
 701                 raise CannotSplit(
 702                     "The current optional pair of parentheses is bound to fail to"
 703                     " satisfy the splitting algorithm because the head or the tail"
 704                     " contains multiline strings which by definition never fit one"
 705                     " line."
 706                 ) from e
 707
 708     ensure_visible(opening_bracket)
 709     ensure_visible(closing_bracket)
 710     for result in (head, body, tail):
 711         if result:
 712             yield result
 713
 714
 715 def bracket_split_succeeded_or_raise(head: Line, body: Line, tail: Line) -> None:
 716     """Raise :exc:`CannotSplit` if the last left- or right-hand split failed.
 717
 718     Do nothing otherwise.
 719
 720     A left- or right-hand split is based on a pair of brackets. Content before
 721     (and including) the opening bracket is left on one line, content inside the
 722     brackets is put on a separate line, and finally content starting with and
 723     following the closing bracket is put on a separate line.
 724
 725     Those are called `head`, `body`, and `tail`, respectively. If the split
 726     produced the same line (all content in `head`) or ended up with an empty `body`
 727     and the `tail` is just the closing bracket, then it's considered failed.
 728     """
 729     tail_len = len(str(tail).strip())
 730     if not body:
 731         if tail_len == 0:
 732             raise CannotSplit("Splitting brackets produced the same line")
 733
 734         elif tail_len < 3:
 735             raise CannotSplit(
 736                 f"Splitting brackets on an empty body to save {tail_len} characters is"
 737                 " not worth it"
 738             )
 739
 740
 741 def bracket_split_build_line(
 742     leaves: List[Leaf],
 743     original: Line,
 744     opening_bracket: Leaf,
 745     *,
 746     component: _BracketSplitComponent,
 747 ) -> Line:
 748     """Return a new line with given `leaves` and respective comments from `original`.
 749
 750     If it's the head component, brackets will be tracked so trailing commas are
 751     respected.
 752
 753     If it's the body component, the result line is one-indented inside brackets and as
 754     such has its first leaf's prefix normalized and a trailing comma added when
 755     expected.
 756     """
 757     result = Line(mode=original.mode, depth=original.depth)
 758     if component is _BracketSplitComponent.body:
 759         result.inside_brackets = True
 760         result.depth += 1
 761         if leaves:
 762             # Since body is a new indent level, remove spurious leading whitespace.
 763             normalize_prefix(leaves[0], inside_brackets=True)
 764             # Ensure a trailing comma for imports and standalone function arguments, but
 765             # be careful not to add one after any comments or within type annotations.
 766             no_commas = (
 767                 original.is_def
 768                 and opening_bracket.value == "("
 769                 and not any(leaf.type == token.COMMA for leaf in leaves)
 770                 # In particular, don't add one within a parenthesized return annotation.
 771                 # Unfortunately the indicator we're in a return annotation (RARROW) may
 772                 # be defined directly in the parent node, the parent of the parent ...
 773                 # and so on depending on how complex the return annotation is.
 774                 # This isn't perfect and there's some false negatives but they are in
 775                 # contexts were a comma is actually fine.
 776                 and not any(
 777                     node.prev_sibling.type == RARROW
 778                     for node in (
 779                         leaves[0].parent,
 780                         getattr(leaves[0].parent, "parent", None),
 781                     )
 782                     if isinstance(node, Node) and isinstance(node.prev_sibling, Leaf)
 783                 )
 784             )
 785
 786             if original.is_import or no_commas:
 787                 for i in range(len(leaves) - 1, -1, -1):
 788                     if leaves[i].type == STANDALONE_COMMENT:
 789                         continue
 790
 791                     if leaves[i].type != token.COMMA:
 792                         new_comma = Leaf(token.COMMA, ",")
 793                         leaves.insert(i + 1, new_comma)
 794                     break
 795
 796     leaves_to_track: Set[LeafID] = set()
 797     if (
 798         Preview.handle_trailing_commas_in_head in original.mode
 799         and component is _BracketSplitComponent.head
 800     ):
 801         leaves_to_track = get_leaves_inside_matching_brackets(leaves)
 802     # Populate the line
 803     for leaf in leaves:
 804         result.append(
 805             leaf,
 806             preformatted=True,
 807             track_bracket=id(leaf) in leaves_to_track,
 808         )
 809         for comment_after in original.comments_after(leaf):
 810             result.append(comment_after, preformatted=True)
 811     if component is _BracketSplitComponent.body and should_split_line(
 812         result, opening_bracket
 813     ):
 814         result.should_split_rhs = True
 815     return result
 816
 817
 818 def dont_increase_indentation(split_func: Transformer) -> Transformer:
 819     """Normalize prefix of the first leaf in every line returned by `split_func`.
 820
 821     This is a decorator over relevant split functions.
 822     """
 823
 824     @wraps(split_func)
 825     def split_wrapper(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
 826         for split_line in split_func(line, features):
 827             normalize_prefix(split_line.leaves[0], inside_brackets=True)
 828             yield split_line
 829
 830     return split_wrapper
 831
 832
 833 @dont_increase_indentation
 834 def delimiter_split(line: Line, features: Collection[Feature] = ()) -> Iterator[Line]:
 835     """Split according to delimiters of the highest priority.
 836
 837     If the appropriate Features are given, the split will add trailing commas
 838     also in function signatures and calls that contain `*` and `**`.
 839     """
 840     try:
 841         last_leaf = line.leaves[-1]
 842     except IndexError:
 843         raise CannotSplit("Line empty") from None
 844
 845     bt = line.bracket_tracker
 846     try:
 847         delimiter_priority = bt.max_delimiter_priority(exclude={id(last_leaf)})
 848     except ValueError:
 849         raise CannotSplit("No delimiters found") from None
 850
 851     if delimiter_priority == DOT_PRIORITY:
 852         if bt.delimiter_count_with_priority(delimiter_priority) == 1:
 853             raise CannotSplit("Splitting a single attribute from its owner looks wrong")
 854
 855     current_line = Line(
 856         mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 857     )
 858     lowest_depth = sys.maxsize
 859     trailing_comma_safe = True
 860
 861     def append_to_line(leaf: Leaf) -> Iterator[Line]:
 862         """Append `leaf` to current line or to new line if appending impossible."""
 863         nonlocal current_line
 864         try:
 865             current_line.append_safe(leaf, preformatted=True)
 866         except ValueError:
 867             yield current_line
 868
 869             current_line = Line(
 870                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 871             )
 872             current_line.append(leaf)
 873
 874     for leaf in line.leaves:
 875         yield from append_to_line(leaf)
 876
 877         for comment_after in line.comments_after(leaf):
 878             yield from append_to_line(comment_after)
 879
 880         lowest_depth = min(lowest_depth, leaf.bracket_depth)
 881         if leaf.bracket_depth == lowest_depth:
 882             if is_vararg(leaf, within={syms.typedargslist}):
 883                 trailing_comma_safe = (
 884                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_DEF in features
 885                 )
 886             elif is_vararg(leaf, within={syms.arglist, syms.argument}):
 887                 trailing_comma_safe = (
 888                     trailing_comma_safe and Feature.TRAILING_COMMA_IN_CALL in features
 889                 )
 890
 891         leaf_priority = bt.delimiters.get(id(leaf))
 892         if leaf_priority == delimiter_priority:
 893             yield current_line
 894
 895             current_line = Line(
 896                 mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 897             )
 898     if current_line:
 899         if (
 900             trailing_comma_safe
 901             and delimiter_priority == COMMA_PRIORITY
 902             and current_line.leaves[-1].type != token.COMMA
 903             and current_line.leaves[-1].type != STANDALONE_COMMENT
 904         ):
 905             new_comma = Leaf(token.COMMA, ",")
 906             current_line.append(new_comma)
 907         yield current_line
 908
 909
 910 @dont_increase_indentation
 911 def standalone_comment_split(
 912     line: Line, features: Collection[Feature] = ()
 913 ) -> Iterator[Line]:
 914     """Split standalone comments from the rest of the line."""
 915     if not line.contains_standalone_comments(0):
 916         raise CannotSplit("Line does not have any standalone comments")
 917
 918     current_line = Line(
 919         mode=line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 920     )
 921
 922     def append_to_line(leaf: Leaf) -> Iterator[Line]:
 923         """Append `leaf` to current line or to new line if appending impossible."""
 924         nonlocal current_line
 925         try:
 926             current_line.append_safe(leaf, preformatted=True)
 927         except ValueError:
 928             yield current_line
 929
 930             current_line = Line(
 931                 line.mode, depth=line.depth, inside_brackets=line.inside_brackets
 932             )
 933             current_line.append(leaf)
 934
 935     for leaf in line.leaves:
 936         yield from append_to_line(leaf)
 937
 938         for comment_after in line.comments_after(leaf):
 939             yield from append_to_line(comment_after)
 940
 941     if current_line:
 942         yield current_line
 943
 944
 945 def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
 946     """Leave existing extra newlines if not `inside_brackets`. Remove everything
 947     else.
 948
 949     Note: don't use backslashes for formatting or you'll lose your voting rights.
 950     """
 951     if not inside_brackets:
 952         spl = leaf.prefix.split("#")
 953         if "\\" not in spl[0]:
 954             nl_count = spl[-1].count("\n")
 955             if len(spl) > 1:
 956                 nl_count -= 1
 957             leaf.prefix = "\n" * nl_count
 958             return
 959
 960     leaf.prefix = ""
 961
 962
 963 def normalize_invisible_parens(
 964     node: Node, parens_after: Set[str], *, preview: bool
 965 ) -> None:
 966     """Make existing optional parentheses invisible or create new ones.
 967
 968     `parens_after` is a set of string leaf values immediately after which parens
 969     should be put.
 970
 971     Standardizes on visible parentheses for single-element tuples, and keeps
 972     existing visible parentheses for other tuples and generator expressions.
 973     """
 974     for pc in list_comments(node.prefix, is_endmarker=False, preview=preview):
 975         if pc.value in FMT_OFF:
 976             # This `node` has a prefix with `# fmt: off`, don't mess with parens.
 977             return
 978     check_lpar = False
 979     for index, child in enumerate(list(node.children)):
 980         # Fixes a bug where invisible parens are not properly stripped from
 981         # assignment statements that contain type annotations.
 982         if isinstance(child, Node) and child.type == syms.annassign:
 983             normalize_invisible_parens(
 984                 child, parens_after=parens_after, preview=preview
 985             )
 986
 987         # Add parentheses around long tuple unpacking in assignments.
 988         if (
 989             index == 0
 990             and isinstance(child, Node)
 991             and child.type == syms.testlist_star_expr
 992         ):
 993             check_lpar = True
 994
 995         if check_lpar:
 996             if (
 997                 preview
 998                 and child.type == syms.atom
 999                 and node.type == syms.for_stmt
1000                 and isinstance(child.prev_sibling, Leaf)
1001                 and child.prev_sibling.type == token.NAME
1002                 and child.prev_sibling.value == "for"
1003             ):
1004                 if maybe_make_parens_invisible_in_atom(
1005                     child,
1006                     parent=node,
1007                     remove_brackets_around_comma=True,
1008                 ):
1009                     wrap_in_parentheses(node, child, visible=False)
1010             elif preview and isinstance(child, Node) and node.type == syms.with_stmt:
1011                 remove_with_parens(child, node)
1012             elif child.type == syms.atom:
1013                 if maybe_make_parens_invisible_in_atom(
1014                     child,
1015                     parent=node,
1016                 ):
1017                     wrap_in_parentheses(node, child, visible=False)
1018             elif is_one_tuple(child):
1019                 wrap_in_parentheses(node, child, visible=True)
1020             elif node.type == syms.import_from:
1021                 # "import from" nodes store parentheses directly as part of
1022                 # the statement
1023                 if is_lpar_token(child):
1024                     assert is_rpar_token(node.children[-1])
1025                     # make parentheses invisible
1026                     child.value = ""
1027                     node.children[-1].value = ""
1028                 elif child.type != token.STAR:
1029                     # insert invisible parentheses
1030                     node.insert_child(index, Leaf(token.LPAR, ""))
1031                     node.append_child(Leaf(token.RPAR, ""))
1032                 break
1033             elif (
1034                 index == 1
1035                 and child.type == token.STAR
1036                 and node.type == syms.except_clause
1037             ):
1038                 # In except* (PEP 654), the star is actually part of
1039                 # of the keyword. So we need to skip the insertion of
1040                 # invisible parentheses to work more precisely.
1041                 continue
1042
1043             elif not (isinstance(child, Leaf) and is_multiline_string(child)):
1044                 wrap_in_parentheses(node, child, visible=False)
1045
1046         comma_check = child.type == token.COMMA if preview else False
1047
1048         check_lpar = isinstance(child, Leaf) and (
1049             child.value in parens_after or comma_check
1050         )
1051
1052
1053 def remove_await_parens(node: Node) -> None:
1054     if node.children[0].type == token.AWAIT and len(node.children) > 1:
1055         if (
1056             node.children[1].type == syms.atom
1057             and node.children[1].children[0].type == token.LPAR
1058         ):
1059             if maybe_make_parens_invisible_in_atom(
1060                 node.children[1],
1061                 parent=node,
1062                 remove_brackets_around_comma=True,
1063             ):
1064                 wrap_in_parentheses(node, node.children[1], visible=False)
1065
1066             # Since await is an expression we shouldn't remove
1067             # brackets in cases where this would change
1068             # the AST due to operator precedence.
1069             # Therefore we only aim to remove brackets around
1070             # power nodes that aren't also await expressions themselves.
1071             # https://peps.python.org/pep-0492/#updated-operator-precedence-table
1072             # N.B. We've still removed any redundant nested brackets though :)
1073             opening_bracket = cast(Leaf, node.children[1].children[0])
1074             closing_bracket = cast(Leaf, node.children[1].children[-1])
1075             bracket_contents = cast(Node, node.children[1].children[1])
1076             if bracket_contents.type != syms.power:
1077                 ensure_visible(opening_bracket)
1078                 ensure_visible(closing_bracket)
1079             elif (
1080                 bracket_contents.type == syms.power
1081                 and bracket_contents.children[0].type == token.AWAIT
1082             ):
1083                 ensure_visible(opening_bracket)
1084                 ensure_visible(closing_bracket)
1085                 # If we are in a nested await then recurse down.
1086                 remove_await_parens(bracket_contents)
1087
1088
1089 def remove_with_parens(node: Node, parent: Node) -> None:
1090     """Recursively hide optional parens in `with` statements."""
1091     # Removing all unnecessary parentheses in with statements in one pass is a tad
1092     # complex as different variations of bracketed statements result in pretty
1093     # different parse trees:
1094     #
1095     # with (open("file")) as f:                       # this is an asexpr_test
1096     #     ...
1097     #
1098     # with (open("file") as f):                       # this is an atom containing an
1099     #     ...                                         # asexpr_test
1100     #
1101     # with (open("file")) as f, (open("file")) as f:  # this is asexpr_test, COMMA,
1102     #     ...                                         # asexpr_test
1103     #
1104     # with (open("file") as f, open("file") as f):    # an atom containing a
1105     #     ...                                         # testlist_gexp which then
1106     #                                                 # contains multiple asexpr_test(s)
1107     if node.type == syms.atom:
1108         if maybe_make_parens_invisible_in_atom(
1109             node,
1110             parent=parent,
1111             remove_brackets_around_comma=True,
1112         ):
1113             wrap_in_parentheses(parent, node, visible=False)
1114         if isinstance(node.children[1], Node):
1115             remove_with_parens(node.children[1], node)
1116     elif node.type == syms.testlist_gexp:
1117         for child in node.children:
1118             if isinstance(child, Node):
1119                 remove_with_parens(child, node)
1120     elif node.type == syms.asexpr_test and not any(
1121         leaf.type == token.COLONEQUAL for leaf in node.leaves()
1122     ):
1123         if maybe_make_parens_invisible_in_atom(
1124             node.children[0],
1125             parent=node,
1126             remove_brackets_around_comma=True,
1127         ):
1128             wrap_in_parentheses(node, node.children[0], visible=False)
1129
1130
1131 def maybe_make_parens_invisible_in_atom(
1132     node: LN,
1133     parent: LN,
1134     remove_brackets_around_comma: bool = False,
1135 ) -> bool:
1136     """If it's safe, make the parens in the atom `node` invisible, recursively.
1137     Additionally, remove repeated, adjacent invisible parens from the atom `node`
1138     as they are redundant.
1139
1140     Returns whether the node should itself be wrapped in invisible parentheses.
1141     """
1142     if (
1143         node.type != syms.atom
1144         or is_empty_tuple(node)
1145         or is_one_tuple(node)
1146         or (is_yield(node) and parent.type != syms.expr_stmt)
1147         or (
1148             # This condition tries to prevent removing non-optional brackets
1149             # around a tuple, however, can be a bit overzealous so we provide
1150             # and option to skip this check for `for` and `with` statements.
1151             not remove_brackets_around_comma
1152             and max_delimiter_priority_in_atom(node) >= COMMA_PRIORITY
1153         )
1154     ):
1155         return False
1156
1157     if is_walrus_assignment(node):
1158         if parent.type in [
1159             syms.annassign,
1160             syms.expr_stmt,
1161             syms.assert_stmt,
1162             syms.return_stmt,
1163             # these ones aren't useful to end users, but they do please fuzzers
1164             syms.for_stmt,
1165             syms.del_stmt,
1166         ]:
1167             return False
1168
1169     first = node.children[0]
1170     last = node.children[-1]
1171     if is_lpar_token(first) and is_rpar_token(last):
1172         middle = node.children[1]
1173         # make parentheses invisible
1174         first.value = ""
1175         last.value = ""
1176         maybe_make_parens_invisible_in_atom(
1177             middle,
1178             parent=parent,
1179             remove_brackets_around_comma=remove_brackets_around_comma,
1180         )
1181
1182         if is_atom_with_invisible_parens(middle):
1183             # Strip the invisible parens from `middle` by replacing
1184             # it with the child in-between the invisible parens
1185             middle.replace(middle.children[1])
1186
1187         return False
1188
1189     return True
1190
1191
1192 def should_split_line(line: Line, opening_bracket: Leaf) -> bool:
1193     """Should `line` be immediately split with `delimiter_split()` after RHS?"""
1194
1195     if not (opening_bracket.parent and opening_bracket.value in "[{("):
1196         return False
1197
1198     # We're essentially checking if the body is delimited by commas and there's more
1199     # than one of them (we're excluding the trailing comma and if the delimiter priority
1200     # is still commas, that means there's more).
1201     exclude = set()
1202     trailing_comma = False
1203     try:
1204         last_leaf = line.leaves[-1]
1205         if last_leaf.type == token.COMMA:
1206             trailing_comma = True
1207             exclude.add(id(last_leaf))
1208         max_priority = line.bracket_tracker.max_delimiter_priority(exclude=exclude)
1209     except (IndexError, ValueError):
1210         return False
1211
1212     return max_priority == COMMA_PRIORITY and (
1213         (line.mode.magic_trailing_comma and trailing_comma)
1214         # always explode imports
1215         or opening_bracket.parent.type in {syms.atom, syms.import_from}
1216     )
1217
1218
1219 def generate_trailers_to_omit(line: Line, line_length: int) -> Iterator[Set[LeafID]]:
1220     """Generate sets of closing bracket IDs that should be omitted in a RHS.
1221
1222     Brackets can be omitted if the entire trailer up to and including
1223     a preceding closing bracket fits in one line.
1224
1225     Yielded sets are cumulative (contain results of previous yields, too).  First
1226     set is empty, unless the line should explode, in which case bracket pairs until
1227     the one that needs to explode are omitted.
1228     """
1229
1230     omit: Set[LeafID] = set()
1231     if not line.magic_trailing_comma:
1232         yield omit
1233
1234     length = 4 * line.depth
1235     opening_bracket: Optional[Leaf] = None
1236     closing_bracket: Optional[Leaf] = None
1237     inner_brackets: Set[LeafID] = set()
1238     for index, leaf, leaf_length in line.enumerate_with_length(reversed=True):
1239         length += leaf_length
1240         if length > line_length:
1241             break
1242
1243         has_inline_comment = leaf_length > len(leaf.value) + len(leaf.prefix)
1244         if leaf.type == STANDALONE_COMMENT or has_inline_comment:
1245             break
1246
1247         if opening_bracket:
1248             if leaf is opening_bracket:
1249                 opening_bracket = None
1250             elif leaf.type in CLOSING_BRACKETS:
1251                 prev = line.leaves[index - 1] if index > 0 else None
1252                 if (
1253                     prev
1254                     and prev.type == token.COMMA
1255                     and leaf.opening_bracket is not None
1256                     and not is_one_sequence_between(
1257                         leaf.opening_bracket, leaf, line.leaves
1258                     )
1259                 ):
1260                     # Never omit bracket pairs with trailing commas.
1261                     # We need to explode on those.
1262                     break
1263
1264                 inner_brackets.add(id(leaf))
1265         elif leaf.type in CLOSING_BRACKETS:
1266             prev = line.leaves[index - 1] if index > 0 else None
1267             if prev and prev.type in OPENING_BRACKETS:
1268                 # Empty brackets would fail a split so treat them as "inner"
1269                 # brackets (e.g. only add them to the `omit` set if another
1270                 # pair of brackets was good enough.
1271                 inner_brackets.add(id(leaf))
1272                 continue
1273
1274             if closing_bracket:
1275                 omit.add(id(closing_bracket))
1276                 omit.update(inner_brackets)
1277                 inner_brackets.clear()
1278                 yield omit
1279
1280             if (
1281                 prev
1282                 and prev.type == token.COMMA
1283                 and leaf.opening_bracket is not None
1284                 and not is_one_sequence_between(leaf.opening_bracket, leaf, line.leaves)
1285             ):
1286                 # Never omit bracket pairs with trailing commas.
1287                 # We need to explode on those.
1288                 break
1289
1290             if leaf.value:
1291                 opening_bracket = leaf.opening_bracket
1292                 closing_bracket = leaf
1293
1294
1295 def run_transformer(
1296     line: Line,
1297     transform: Transformer,
1298     mode: Mode,
1299     features: Collection[Feature],
1300     *,
1301     line_str: str = "",
1302 ) -> List[Line]:
1303     if not line_str:
1304         line_str = line_to_string(line)
1305     result: List[Line] = []
1306     for transformed_line in transform(line, features):
1307         if str(transformed_line).strip("\n") == line_str:
1308             raise CannotTransform("Line transformer returned an unchanged result")
1309
1310         result.extend(transform_line(transformed_line, mode=mode, features=features))
1311
1312     if (
1313         transform.__class__.__name__ != "rhs"
1314         or not line.bracket_tracker.invisible
1315         or any(bracket.value for bracket in line.bracket_tracker.invisible)
1316         or line.contains_multiline_strings()
1317         or result[0].contains_uncollapsable_type_comments()
1318         or result[0].contains_unsplittable_type_ignore()
1319         or is_line_short_enough(result[0], line_length=mode.line_length)
1320         # If any leaves have no parents (which _can_ occur since
1321         # `transform(line)` potentially destroys the line's underlying node
1322         # structure), then we can't proceed. Doing so would cause the below
1323         # call to `append_leaves()` to fail.
1324         or any(leaf.parent is None for leaf in line.leaves)
1325     ):
1326         return result
1327
1328     line_copy = line.clone()
1329     append_leaves(line_copy, line, line.leaves)
1330     features_fop = set(features) | {Feature.FORCE_OPTIONAL_PARENTHESES}
1331     second_opinion = run_transformer(
1332         line_copy, transform, mode, features_fop, line_str=line_str
1333     )
1334     if all(
1335         is_line_short_enough(ln, line_length=mode.line_length) for ln in second_opinion
1336     ):
1337         result = second_opinion
1338     return result