]> 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:

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