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.
4 from dataclasses import dataclass, field
18 from black.brackets import COMMA_PRIORITY, DOT_PRIORITY, BracketTracker
19 from black.mode import Mode, Preview
20 from black.nodes import (
29 is_one_sequence_between,
31 is_type_ignore_comment,
32 is_with_or_async_with_stmt,
37 from black.strings import str_width
38 from blib2to3.pgen2 import token
39 from blib2to3.pytree import Leaf, Node
45 LN = Union[Leaf, Node]
50 """Holds leaves and comments. Can be printed with `str(line)`."""
52 mode: Mode = field(repr=False)
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
63 self, leaf: Leaf, preformatted: bool = False, track_bracket: bool = False
65 """Add a new `leaf` to the end of the line.
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.
72 Inline comments are put aside.
74 has_value = leaf.type in BRACKETS or bool(leaf.value.strip())
78 if token.COLON == leaf.type and self.is_class_paren_empty:
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(
85 complex_subscript=self.is_complex_subscript(leaf),
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)
98 def append_safe(self, leaf: Leaf, preformatted: bool = False) -> None:
99 """Like :func:`append()` but disallow invalid standalone comment structure.
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.
104 if self.bracket_tracker.depth == 0:
106 raise ValueError("cannot append to standalone comments")
108 if self.leaves and leaf.type == STANDALONE_COMMENT:
110 "cannot append standalone comments to a populated line"
113 self.append(leaf, preformatted=preformatted)
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
121 def is_decorator(self) -> bool:
122 """Is this line a decorator?"""
123 return bool(self) and self.leaves[0].type == token.AT
126 def is_import(self) -> bool:
127 """Is this an import line?"""
128 return bool(self) and is_import(self.leaves[0])
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])
136 def is_class(self) -> bool:
137 """Is this line a class definition?"""
140 and self.leaves[0].type == token.NAME
141 and self.leaves[0].value == "class"
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)
152 def is_def(self) -> bool:
153 """Is this a function definition? (Also returns True for async defs.)"""
155 first_leaf = self.leaves[0]
160 second_leaf: Optional[Leaf] = self.leaves[1]
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"
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)
178 def is_class_paren_empty(self) -> bool:
179 """Is this a class with no base classes but using parentheses?
181 Those are unnecessary and should be removed.
185 and len(self.leaves) == 4
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 == ")"
194 def is_triple_quoted_string(self) -> bool:
195 """Is the line a triple quoted string?"""
196 if not self or self.leaves[0].type != token.STRING:
198 value = self.leaves[0].value
199 if value.startswith(('"""', "'''")):
201 if Preview.accept_raw_docstrings in self.mode and value.startswith(
202 ("r'''", 'r"""', "R'''", 'R"""')
208 def opens_block(self) -> bool:
209 """Does this line open a new level of indentation."""
210 if len(self.leaves) == 0:
212 return self.leaves[-1].type == token.COLON
214 def is_fmt_pass_converted(
215 self, *, first_leaf_matches: Optional[Callable[[Leaf], bool]] = None
217 """Is this line converted from fmt off/skip code?
219 If first_leaf_matches is not None, it only returns True if the first
220 leaf of converted code matches.
222 if len(self.leaves) != 1:
224 leaf = self.leaves[0]
226 leaf.type != STANDALONE_COMMENT
227 or leaf.fmt_pass_converted_first_leaf is None
230 return first_leaf_matches is None or first_leaf_matches(
231 leaf.fmt_pass_converted_first_leaf
234 def contains_standalone_comments(self, depth_limit: int = sys.maxsize) -> bool:
235 """If so, needs to be split before emitting."""
236 for leaf in self.leaves:
237 if leaf.type == STANDALONE_COMMENT and leaf.bracket_depth <= depth_limit:
242 def contains_implicit_multiline_string_with_comments(self) -> bool:
243 """Chck if we have an implicit multiline string with comments on the line"""
244 for leaf_type, leaf_group_iterator in itertools.groupby(
245 self.leaves, lambda leaf: leaf.type
247 if leaf_type != token.STRING:
249 leaf_list = list(leaf_group_iterator)
250 if len(leaf_list) == 1:
252 for leaf in leaf_list:
253 if self.comments_after(leaf):
257 def contains_uncollapsable_type_comments(self) -> bool:
260 last_leaf = self.leaves[-1]
261 ignored_ids.add(id(last_leaf))
262 if last_leaf.type == token.COMMA or (
263 last_leaf.type == token.RPAR and not last_leaf.value
265 # When trailing commas or optional parens are inserted by Black for
266 # consistency, comments after the previous last element are not moved
267 # (they don't have to, rendering will still be correct). So we ignore
268 # trailing commas and invisible.
269 last_leaf = self.leaves[-2]
270 ignored_ids.add(id(last_leaf))
274 # A type comment is uncollapsable if it is attached to a leaf
275 # that isn't at the end of the line (since that could cause it
276 # to get associated to a different argument) or if there are
277 # comments before it (since that could cause it to get hidden
280 for leaf_id, comments in self.comments.items():
281 for comment in comments:
282 if is_type_comment(comment):
284 not is_type_ignore_comment(comment)
285 and leaf_id not in ignored_ids
293 def contains_unsplittable_type_ignore(self) -> bool:
297 # If a 'type: ignore' is attached to the end of a line, we
298 # can't split the line, because we can't know which of the
299 # subexpressions the ignore was meant to apply to.
301 # We only want this to apply to actual physical lines from the
302 # original source, though: we don't want the presence of a
303 # 'type: ignore' at the end of a multiline expression to
304 # justify pushing it all onto one line. Thus we
305 # (unfortunately) need to check the actual source lines and
306 # only report an unsplittable 'type: ignore' if this line was
307 # one line in the original code.
309 # Grab the first and last line numbers, skipping generated leaves
310 first_line = next((leaf.lineno for leaf in self.leaves if leaf.lineno != 0), 0)
312 (leaf.lineno for leaf in reversed(self.leaves) if leaf.lineno != 0), 0
315 if first_line == last_line:
316 # We look at the last two leaves since a comma or an
317 # invisible paren could have been added at the end of the
319 for node in self.leaves[-2:]:
320 for comment in self.comments.get(id(node), []):
321 if is_type_ignore_comment(comment):
326 def contains_multiline_strings(self) -> bool:
327 return any(is_multiline_string(leaf) for leaf in self.leaves)
329 def has_magic_trailing_comma(
330 self, closing: Leaf, ensure_removable: bool = False
332 """Return True if we have a magic trailing comma, that is when:
333 - there's a trailing comma here
334 - it's not a one-tuple
335 - it's not a single-element subscript
336 Additionally, if ensure_removable:
337 - it's not from square bracket indexing
338 (specifically, single-element square bracket indexing)
341 closing.type in CLOSING_BRACKETS
343 and self.leaves[-1].type == token.COMMA
347 if closing.type == token.RBRACE:
350 if closing.type == token.RSQB:
353 and closing.parent.type == syms.trailer
354 and closing.opening_bracket
355 and is_one_sequence_between(
356 closing.opening_bracket,
359 brackets=(token.LSQB, token.RSQB),
364 if not ensure_removable:
367 comma = self.leaves[-1]
368 if comma.parent is None:
371 comma.parent.type != syms.subscriptlist
372 or closing.opening_bracket is None
373 or not is_one_sequence_between(
374 closing.opening_bracket,
377 brackets=(token.LSQB, token.RSQB),
384 if closing.opening_bracket is not None and not is_one_sequence_between(
385 closing.opening_bracket, closing, self.leaves
391 def append_comment(self, comment: Leaf) -> bool:
392 """Add an inline or standalone comment to the line."""
394 comment.type == STANDALONE_COMMENT
395 and self.bracket_tracker.any_open_brackets()
400 if comment.type != token.COMMENT:
404 comment.type = STANDALONE_COMMENT
408 last_leaf = self.leaves[-1]
410 last_leaf.type == token.RPAR
411 and not last_leaf.value
413 and len(list(last_leaf.parent.leaves())) <= 3
414 and not is_type_comment(comment)
416 # Comments on an optional parens wrapping a single leaf should belong to
417 # the wrapped node except if it's a type comment. Pinning the comment like
418 # this avoids unstable formatting caused by comment migration.
419 if len(self.leaves) < 2:
420 comment.type = STANDALONE_COMMENT
424 last_leaf = self.leaves[-2]
425 self.comments.setdefault(id(last_leaf), []).append(comment)
428 def comments_after(self, leaf: Leaf) -> List[Leaf]:
429 """Generate comments that should appear directly after `leaf`."""
430 return self.comments.get(id(leaf), [])
432 def remove_trailing_comma(self) -> None:
433 """Remove the trailing comma and moves the comments attached to it."""
434 trailing_comma = self.leaves.pop()
435 trailing_comma_comments = self.comments.pop(id(trailing_comma), [])
436 self.comments.setdefault(id(self.leaves[-1]), []).extend(
437 trailing_comma_comments
440 def is_complex_subscript(self, leaf: Leaf) -> bool:
441 """Return True iff `leaf` is part of a slice with non-trivial exprs."""
442 open_lsqb = self.bracket_tracker.get_open_lsqb()
443 if open_lsqb is None:
446 subscript_start = open_lsqb.next_sibling
448 if isinstance(subscript_start, Node):
449 if subscript_start.type == syms.listmaker:
452 if subscript_start.type == syms.subscriptlist:
453 subscript_start = child_towards(subscript_start, leaf)
454 return subscript_start is not None and any(
455 n.type in TEST_DESCENDANTS for n in subscript_start.pre_order()
458 def enumerate_with_length(
459 self, reversed: bool = False
460 ) -> Iterator[Tuple[Index, Leaf, int]]:
461 """Return an enumeration of leaves with their length.
463 Stops prematurely on multiline strings and standalone comments.
466 Callable[[Sequence[Leaf]], Iterator[Tuple[Index, Leaf]]],
467 enumerate_reversed if reversed else enumerate,
469 for index, leaf in op(self.leaves):
470 length = len(leaf.prefix) + len(leaf.value)
471 if "\n" in leaf.value:
472 return # Multiline strings, we can't continue.
474 for comment in self.comments_after(leaf):
475 length += len(comment.value)
477 yield index, leaf, length
479 def clone(self) -> "Line":
483 inside_brackets=self.inside_brackets,
484 should_split_rhs=self.should_split_rhs,
485 magic_trailing_comma=self.magic_trailing_comma,
488 def __str__(self) -> str:
489 """Render the line."""
493 indent = " " * self.depth
494 leaves = iter(self.leaves)
496 res = f"{first.prefix}{indent}{first.value}"
499 for comment in itertools.chain.from_iterable(self.comments.values()):
504 def __bool__(self) -> bool:
505 """Return True if the line has leaves or comments."""
506 return bool(self.leaves or self.comments)
511 """Intermediate split result from a right hand split."""
516 opening_bracket: Leaf
517 closing_bracket: Leaf
522 """Class that holds information about a block of formatted lines.
524 This is introduced so that the EmptyLineTracker can look behind the standalone
525 comments and adjust their empty lines for class or def lines.
529 previous_block: Optional["LinesBlock"]
532 content_lines: List[str] = field(default_factory=list)
535 def all_lines(self) -> List[str]:
536 empty_line = str(Line(mode=self.mode))
538 [empty_line * self.before] + self.content_lines + [empty_line * self.after]
543 class EmptyLineTracker:
544 """Provides a stateful method that returns the number of potential extra
545 empty lines needed before and after the currently processed line.
547 Note: this tracker works on lines that haven't been split yet. It assumes
548 the prefix of the first leaf consists of optional newlines. Those newlines
549 are consumed by `maybe_empty_lines()` and included in the computation.
553 previous_line: Optional[Line] = None
554 previous_block: Optional[LinesBlock] = None
555 previous_defs: List[Line] = field(default_factory=list)
556 semantic_leading_comment: Optional[LinesBlock] = None
558 def maybe_empty_lines(self, current_line: Line) -> LinesBlock:
559 """Return the number of extra empty lines before and after the `current_line`.
561 This is for separating `def`, `async def` and `class` with extra empty
562 lines (two on module-level).
564 before, after = self._maybe_empty_lines(current_line)
565 previous_after = self.previous_block.after if self.previous_block else 0
567 # Black should not insert empty lines at the beginning
570 if self.previous_line is None
571 else before - previous_after
574 Preview.module_docstring_newlines in current_line.mode
575 and self.previous_block
576 and self.previous_block.previous_block is None
577 and len(self.previous_block.original_line.leaves) == 1
578 and self.previous_block.original_line.is_triple_quoted_string
584 previous_block=self.previous_block,
585 original_line=current_line,
590 # Maintain the semantic_leading_comment state.
591 if current_line.is_comment:
592 if self.previous_line is None or (
593 not self.previous_line.is_decorator
594 # `or before` means this comment already has an empty line before
595 and (not self.previous_line.is_comment or before)
596 and (self.semantic_leading_comment is None or before)
598 self.semantic_leading_comment = block
599 # `or before` means this decorator already has an empty line before
600 elif not current_line.is_decorator or before:
601 self.semantic_leading_comment = None
603 self.previous_line = current_line
604 self.previous_block = block
607 def _maybe_empty_lines(self, current_line: Line) -> Tuple[int, int]:
609 if current_line.depth == 0:
610 max_allowed = 1 if self.mode.is_pyi else 2
611 if current_line.leaves:
612 # Consume the first leaf's extra newlines.
613 first_leaf = current_line.leaves[0]
614 before = first_leaf.prefix.count("\n")
615 before = min(before, max_allowed)
616 first_leaf.prefix = ""
620 user_had_newline = bool(before)
621 depth = current_line.depth
624 while self.previous_defs and self.previous_defs[-1].depth >= depth:
625 previous_def = self.previous_defs.pop()
627 if previous_def is not None:
628 assert self.previous_line is not None
630 if depth and not current_line.is_def and self.previous_line.is_def:
631 # Empty lines between attributes and methods should be preserved.
632 before = 1 if user_had_newline else 0
634 Preview.blank_line_after_nested_stub_class in self.mode
635 and previous_def.is_class
636 and not previous_def.is_stub_class
648 and previous_def.depth
649 and current_line.leaves[-1].type == token.COLON
651 current_line.leaves[0].value
652 not in ("with", "try", "for", "while", "if", "match")
655 # We shouldn't add two newlines between an indented function and
656 # a dependent non-indented clause. This is to avoid issues with
657 # conditional function definitions that are technically top-level
658 # and therefore get two trailing newlines, but look weird and
659 # inconsistent when they're followed by elif, else, etc. This is
660 # worse because these functions only get *one* preceding newline
666 if current_line.is_decorator or current_line.is_def or current_line.is_class:
667 return self._maybe_empty_lines_for_class_or_def(
668 current_line, before, user_had_newline
673 and self.previous_line.is_import
674 and not current_line.is_import
675 and not current_line.is_fmt_pass_converted(first_leaf_matches=is_import)
676 and depth == self.previous_line.depth
678 return (before or 1), 0
682 and self.previous_line.is_class
683 and current_line.is_triple_quoted_string
685 if Preview.no_blank_line_before_class_docstring in current_line.mode:
689 if self.previous_line and self.previous_line.opens_block:
693 def _maybe_empty_lines_for_class_or_def( # noqa: C901
694 self, current_line: Line, before: int, user_had_newline: bool
695 ) -> Tuple[int, int]:
696 if not current_line.is_decorator:
697 self.previous_defs.append(current_line)
698 if self.previous_line is None:
699 # Don't insert empty lines before the first line in the file.
702 if self.previous_line.is_decorator:
703 if self.mode.is_pyi and current_line.is_stub_class:
704 # Insert an empty line after a decorated stub class
709 if self.previous_line.depth < current_line.depth and (
710 self.previous_line.is_class or self.previous_line.is_def
714 comment_to_add_newlines: Optional[LinesBlock] = None
716 self.previous_line.is_comment
717 and self.previous_line.depth == current_line.depth
720 slc = self.semantic_leading_comment
723 and slc.previous_block is not None
724 and not slc.previous_block.original_line.is_class
725 and not slc.previous_block.original_line.opens_block
728 comment_to_add_newlines = slc
733 if current_line.is_class or self.previous_line.is_class:
734 if self.previous_line.depth < current_line.depth:
736 elif self.previous_line.depth > current_line.depth:
738 elif current_line.is_stub_class and self.previous_line.is_stub_class:
739 # No blank line between classes with an empty body
743 # Remove case `self.previous_line.depth > current_line.depth` below when
744 # this becomes stable.
746 # Don't inspect the previous line if it's part of the body of the previous
747 # statement in the same level, we always want a blank line if there's
748 # something with a body preceding.
750 Preview.blank_line_between_nested_and_def_stub_file in current_line.mode
751 and self.previous_line.depth > current_line.depth
755 current_line.is_def or current_line.is_decorator
756 ) and not self.previous_line.is_def:
757 if current_line.depth:
758 # In classes empty lines between attributes and methods should
760 newlines = min(1, before)
762 # Blank line between a block of functions (maybe with preceding
763 # decorators) and a block of non-functions
765 elif self.previous_line.depth > current_line.depth:
770 newlines = 1 if current_line.depth else 2
771 # If a user has left no space after a dummy implementation, don't insert
772 # new lines. This is useful for instance for @overload or Protocols.
774 Preview.dummy_implementations in self.mode
775 and self.previous_line.is_stub_def
776 and not user_had_newline
779 if comment_to_add_newlines is not None:
780 previous_block = comment_to_add_newlines.previous_block
781 if previous_block is not None:
782 comment_to_add_newlines.before = (
783 max(comment_to_add_newlines.before, newlines) - previous_block.after
789 def enumerate_reversed(sequence: Sequence[T]) -> Iterator[Tuple[Index, T]]:
790 """Like `reversed(enumerate(sequence))` if that were possible."""
791 index = len(sequence) - 1
792 for element in reversed(sequence):
793 yield (index, element)
798 new_line: Line, old_line: Line, leaves: List[Leaf], preformatted: bool = False
801 Append leaves (taken from @old_line) to @new_line, making sure to fix the
802 underlying Node structure where appropriate.
804 All of the leaves in @leaves are duplicated. The duplicates are then
805 appended to @new_line and used to replace their originals in the underlying
806 Node structure. Any comments attached to the old leaves are reattached to
810 set(@leaves) is a subset of set(@old_line.leaves).
812 for old_leaf in leaves:
813 new_leaf = Leaf(old_leaf.type, old_leaf.value)
814 replace_child(old_leaf, new_leaf)
815 new_line.append(new_leaf, preformatted=preformatted)
817 for comment_leaf in old_line.comments_after(old_leaf):
818 new_line.append(comment_leaf, preformatted=True)
821 def is_line_short_enough( # noqa: C901
822 line: Line, *, mode: Mode, line_str: str = ""
824 """For non-multiline strings, return True if `line` is no longer than `line_length`.
825 For multiline strings, looks at the context around `line` to determine
826 if it should be inlined or split up.
827 Uses the provided `line_str` rendering, if any, otherwise computes a new one.
830 line_str = line_to_string(line)
832 width = str_width if mode.preview else len
834 if Preview.multiline_string_handling not in mode:
836 width(line_str) <= mode.line_length
837 and "\n" not in line_str # multiline strings
838 and not line.contains_standalone_comments()
841 if line.contains_standalone_comments():
843 if "\n" not in line_str:
844 # No multiline strings (MLS) present
845 return width(line_str) <= mode.line_length
847 first, *_, last = line_str.split("\n")
848 if width(first) > mode.line_length or width(last) > mode.line_length:
851 # Traverse the AST to examine the context of the multiline string (MLS),
852 # tracking aspects such as depth and comma existence,
853 # to determine whether to split the MLS or keep it together.
854 # Depth (which is based on the existing bracket_depth concept)
855 # is needed to determine nesting level of the MLS.
856 # Includes special case for trailing commas.
857 commas: List[int] = [] # tracks number of commas per depth level
858 multiline_string: Optional[Leaf] = None
859 # store the leaves that contain parts of the MLS
860 multiline_string_contexts: List[LN] = []
862 max_level_to_update: Union[int, float] = math.inf # track the depth of the MLS
863 for i, leaf in enumerate(line.leaves):
864 if max_level_to_update == math.inf:
865 had_comma: Optional[int] = None
866 if leaf.bracket_depth + 1 > len(commas):
868 elif leaf.bracket_depth + 1 < len(commas):
869 had_comma = commas.pop()
871 had_comma is not None
872 and multiline_string is not None
873 and multiline_string.bracket_depth == leaf.bracket_depth + 1
875 # Have left the level with the MLS, stop tracking commas
876 max_level_to_update = leaf.bracket_depth
878 # MLS was in parens with at least one comma - force split
881 if leaf.bracket_depth <= max_level_to_update and leaf.type == token.COMMA:
882 # Ignore non-nested trailing comma
883 # directly after MLS/MLS-containing expression
884 ignore_ctxs: List[Optional[LN]] = [None]
885 ignore_ctxs += multiline_string_contexts
886 if not (leaf.prev_sibling in ignore_ctxs and i == len(line.leaves) - 1):
887 commas[leaf.bracket_depth] += 1
888 if max_level_to_update != math.inf:
889 max_level_to_update = min(max_level_to_update, leaf.bracket_depth)
891 if is_multiline_string(leaf):
892 if len(multiline_string_contexts) > 0:
893 # >1 multiline string cannot fit on a single line - force split
895 multiline_string = leaf
897 # fetch the leaf components of the MLS in the AST
898 while str(ctx) in line_str:
899 multiline_string_contexts.append(ctx)
900 if ctx.parent is None:
904 # May not have a triple-quoted multiline string at all,
905 # in case of a regular string with embedded newlines and line continuations
906 if len(multiline_string_contexts) == 0:
909 return all(val == 0 for val in commas)
912 def can_be_split(line: Line) -> bool:
913 """Return False if the line cannot be split *for sure*.
915 This is not an exhaustive search but a cheap heuristic that we can use to
916 avoid some unfortunate formattings (mostly around wrapping unsplittable code
917 in unnecessary parentheses).
923 if leaves[0].type == token.STRING and leaves[1].type == token.DOT:
927 for leaf in leaves[-2::-1]:
928 if leaf.type in OPENING_BRACKETS:
929 if next.type not in CLOSING_BRACKETS:
933 elif leaf.type == token.DOT:
935 elif leaf.type == token.NAME:
936 if not (next.type == token.DOT or next.type in OPENING_BRACKETS):
939 elif leaf.type not in CLOSING_BRACKETS:
942 if dot_count > 1 and call_count > 1:
948 def can_omit_invisible_parens(
952 """Does `rhs.body` have a shape safe to reformat without optional parens around it?
954 Returns True for only a subset of potentially nice looking formattings but
955 the point is to not return false positives that end up producing lines that
959 bt = line.bracket_tracker
960 if not bt.delimiters:
961 # Without delimiters the optional parentheses are useless.
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.
970 if delimiter_count == 1:
972 Preview.wrap_multiple_context_managers_in_parens in line.mode
973 and max_priority == COMMA_PRIORITY
974 and rhs.head.is_with_or_async_with_stmt
976 # For two context manager with statements, the optional parentheses read
977 # better. In this case, `rhs.body` is the context managers part of
978 # the with statement. `rhs.head` is the `with (` part on the previous
981 # Otherwise it may also read better, but we don't do it today and requires
982 # careful considerations for all possible cases. See
983 # https://github.com/psf/black/issues/2156.
985 if max_priority == DOT_PRIORITY:
986 # A single stranded method call doesn't require optional parentheses.
989 assert len(line.leaves) >= 2, "Stranded delimiter"
991 # With a single delimiter, omit if the expression starts or ends with
993 first = line.leaves[0]
994 second = line.leaves[1]
995 if first.type in OPENING_BRACKETS and second.type not in CLOSING_BRACKETS:
996 if _can_omit_opening_paren(line, first=first, line_length=line_length):
999 # Note: we are not returning False here because a line might have *both*
1000 # a leading opening bracket and a trailing closing bracket. If the
1001 # opening bracket doesn't match our rule, maybe the closing will.
1003 penultimate = line.leaves[-2]
1004 last = line.leaves[-1]
1007 last.type == token.RPAR
1008 or last.type == token.RBRACE
1010 # don't use indexing for omitting optional parentheses;
1012 last.type == token.RSQB
1014 and last.parent.type != syms.trailer
1017 if penultimate.type in OPENING_BRACKETS:
1018 # Empty brackets don't help.
1021 if is_multiline_string(first):
1022 # Additional wrapping of a multiline string in this situation is
1026 if _can_omit_closing_paren(line, last=last, line_length=line_length):
1032 def _can_omit_opening_paren(line: Line, *, first: Leaf, line_length: int) -> bool:
1033 """See `can_omit_invisible_parens`."""
1035 length = 4 * line.depth
1037 for _index, leaf, leaf_length in line.enumerate_with_length():
1038 if leaf.type in CLOSING_BRACKETS and leaf.opening_bracket is first:
1041 length += leaf_length
1042 if length > line_length:
1045 if leaf.type in OPENING_BRACKETS:
1046 # There are brackets we can further split on.
1050 # checked the entire string and line length wasn't exceeded
1051 if len(line.leaves) == _index + 1:
1057 def _can_omit_closing_paren(line: Line, *, last: Leaf, line_length: int) -> bool:
1058 """See `can_omit_invisible_parens`."""
1059 length = 4 * line.depth
1060 seen_other_brackets = False
1061 for _index, leaf, leaf_length in line.enumerate_with_length():
1062 length += leaf_length
1063 if leaf is last.opening_bracket:
1064 if seen_other_brackets or length <= line_length:
1067 elif leaf.type in OPENING_BRACKETS:
1068 # There are brackets we can further split on.
1069 seen_other_brackets = True
1074 def line_to_string(line: Line) -> str:
1075 """Returns the string representation of @line.
1077 WARNING: This is known to be computationally expensive.
1079 return str(line).strip("\n")