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

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