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

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