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