]> git.madduck.net Git - etc/vim.git/blob - src/black/lines.py

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

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