src/black/nodes.py

   1 """
   2 blib2to3 Node/Leaf transformation-related utility functions.
   3 """
   4
   5 import sys
   6 from typing import (
   7     Collection,
   8     Generic,
   9     Iterator,
  10     List,
  11     Optional,
  12     Set,
  13     Tuple,
  14     TypeVar,
  15     Union,
  16 )
  17
  18 if sys.version_info >= (3, 8):
  19     from typing import Final
  20 else:
  21     from typing_extensions import Final
  22
  23 from mypy_extensions import mypyc_attr
  24
  25 # lib2to3 fork
  26 from blib2to3.pytree import Node, Leaf, type_repr
  27 from blib2to3 import pygram
  28 from blib2to3.pgen2 import token
  29
  30 from black.cache import CACHE_DIR
  31 from black.strings import has_triple_quotes
  32
  33
  34 pygram.initialize(CACHE_DIR)
  35 syms: Final = pygram.python_symbols
  36
  37
  38 # types
  39 T = TypeVar("T")
  40 LN = Union[Leaf, Node]
  41 LeafID = int
  42 NodeType = int
  43
  44
  45 WHITESPACE: Final = {token.DEDENT, token.INDENT, token.NEWLINE}
  46 STATEMENT: Final = {
  47     syms.if_stmt,
  48     syms.while_stmt,
  49     syms.for_stmt,
  50     syms.try_stmt,
  51     syms.except_clause,
  52     syms.with_stmt,
  53     syms.funcdef,
  54     syms.classdef,
  55     syms.match_stmt,
  56     syms.case_block,
  57 }
  58 STANDALONE_COMMENT: Final = 153
  59 token.tok_name[STANDALONE_COMMENT] = "STANDALONE_COMMENT"
  60 LOGIC_OPERATORS: Final = {"and", "or"}
  61 COMPARATORS: Final = {
  62     token.LESS,
  63     token.GREATER,
  64     token.EQEQUAL,
  65     token.NOTEQUAL,
  66     token.LESSEQUAL,
  67     token.GREATEREQUAL,
  68 }
  69 MATH_OPERATORS: Final = {
  70     token.VBAR,
  71     token.CIRCUMFLEX,
  72     token.AMPER,
  73     token.LEFTSHIFT,
  74     token.RIGHTSHIFT,
  75     token.PLUS,
  76     token.MINUS,
  77     token.STAR,
  78     token.SLASH,
  79     token.DOUBLESLASH,
  80     token.PERCENT,
  81     token.AT,
  82     token.TILDE,
  83     token.DOUBLESTAR,
  84 }
  85 STARS: Final = {token.STAR, token.DOUBLESTAR}
  86 VARARGS_SPECIALS: Final = STARS | {token.SLASH}
  87 VARARGS_PARENTS: Final = {
  88     syms.arglist,
  89     syms.argument,  # double star in arglist
  90     syms.trailer,  # single argument to call
  91     syms.typedargslist,
  92     syms.varargslist,  # lambdas
  93 }
  94 UNPACKING_PARENTS: Final = {
  95     syms.atom,  # single element of a list or set literal
  96     syms.dictsetmaker,
  97     syms.listmaker,
  98     syms.testlist_gexp,
  99     syms.testlist_star_expr,
 100     syms.subject_expr,
 101     syms.pattern,
 102 }
 103 TEST_DESCENDANTS: Final = {
 104     syms.test,
 105     syms.lambdef,
 106     syms.or_test,
 107     syms.and_test,
 108     syms.not_test,
 109     syms.comparison,
 110     syms.star_expr,
 111     syms.expr,
 112     syms.xor_expr,
 113     syms.and_expr,
 114     syms.shift_expr,
 115     syms.arith_expr,
 116     syms.trailer,
 117     syms.term,
 118     syms.power,
 119 }
 120 ASSIGNMENTS: Final = {
 121     "=",
 122     "+=",
 123     "-=",
 124     "*=",
 125     "@=",
 126     "/=",
 127     "%=",
 128     "&=",
 129     "|=",
 130     "^=",
 131     "<<=",
 132     ">>=",
 133     "**=",
 134     "//=",
 135 }
 136
 137 IMPLICIT_TUPLE: Final = {syms.testlist, syms.testlist_star_expr, syms.exprlist}
 138 BRACKET: Final = {
 139     token.LPAR: token.RPAR,
 140     token.LSQB: token.RSQB,
 141     token.LBRACE: token.RBRACE,
 142 }
 143 OPENING_BRACKETS: Final = set(BRACKET.keys())
 144 CLOSING_BRACKETS: Final = set(BRACKET.values())
 145 BRACKETS: Final = OPENING_BRACKETS | CLOSING_BRACKETS
 146 ALWAYS_NO_SPACE: Final = CLOSING_BRACKETS | {token.COMMA, STANDALONE_COMMENT}
 147
 148 RARROW = 55
 149
 150
 151 @mypyc_attr(allow_interpreted_subclasses=True)
 152 class Visitor(Generic[T]):
 153     """Basic lib2to3 visitor that yields things of type `T` on `visit()`."""
 154
 155     def visit(self, node: LN) -> Iterator[T]:
 156         """Main method to visit `node` and its children.
 157
 158         It tries to find a `visit_*()` method for the given `node.type`, like
 159         `visit_simple_stmt` for Node objects or `visit_INDENT` for Leaf objects.
 160         If no dedicated `visit_*()` method is found, chooses `visit_default()`
 161         instead.
 162
 163         Then yields objects of type `T` from the selected visitor.
 164         """
 165         if node.type < 256:
 166             name = token.tok_name[node.type]
 167         else:
 168             name = str(type_repr(node.type))
 169         # We explicitly branch on whether a visitor exists (instead of
 170         # using self.visit_default as the default arg to getattr) in order
 171         # to save needing to create a bound method object and so mypyc can
 172         # generate a native call to visit_default.
 173         visitf = getattr(self, f"visit_{name}", None)
 174         if visitf:
 175             yield from visitf(node)
 176         else:
 177             yield from self.visit_default(node)
 178
 179     def visit_default(self, node: LN) -> Iterator[T]:
 180         """Default `visit_*()` implementation. Recurses to children of `node`."""
 181         if isinstance(node, Node):
 182             for child in node.children:
 183                 yield from self.visit(child)
 184
 185
 186 def whitespace(leaf: Leaf, *, complex_subscript: bool) -> str:  # noqa: C901
 187     """Return whitespace prefix if needed for the given `leaf`.
 188
 189     `complex_subscript` signals whether the given leaf is part of a subscription
 190     which has non-trivial arguments, like arithmetic expressions or function calls.
 191     """
 192     NO: Final = ""
 193     SPACE: Final = " "
 194     DOUBLESPACE: Final = "  "
 195     t = leaf.type
 196     p = leaf.parent
 197     v = leaf.value
 198     if t in ALWAYS_NO_SPACE:
 199         return NO
 200
 201     if t == token.COMMENT:
 202         return DOUBLESPACE
 203
 204     assert p is not None, f"INTERNAL ERROR: hand-made leaf without parent: {leaf!r}"
 205     if t == token.COLON and p.type not in {
 206         syms.subscript,
 207         syms.subscriptlist,
 208         syms.sliceop,
 209     }:
 210         return NO
 211
 212     prev = leaf.prev_sibling
 213     if not prev:
 214         prevp = preceding_leaf(p)
 215         if not prevp or prevp.type in OPENING_BRACKETS:
 216             return NO
 217
 218         if t == token.COLON:
 219             if prevp.type == token.COLON:
 220                 return NO
 221
 222             elif prevp.type != token.COMMA and not complex_subscript:
 223                 return NO
 224
 225             return SPACE
 226
 227         if prevp.type == token.EQUAL:
 228             if prevp.parent:
 229                 if prevp.parent.type in {
 230                     syms.arglist,
 231                     syms.argument,
 232                     syms.parameters,
 233                     syms.varargslist,
 234                 }:
 235                     return NO
 236
 237                 elif prevp.parent.type == syms.typedargslist:
 238                     # A bit hacky: if the equal sign has whitespace, it means we
 239                     # previously found it's a typed argument.  So, we're using
 240                     # that, too.
 241                     return prevp.prefix
 242
 243         elif prevp.type in VARARGS_SPECIALS:
 244             if is_vararg(prevp, within=VARARGS_PARENTS | UNPACKING_PARENTS):
 245                 return NO
 246
 247         elif prevp.type == token.COLON:
 248             if prevp.parent and prevp.parent.type in {syms.subscript, syms.sliceop}:
 249                 return SPACE if complex_subscript else NO
 250
 251         elif (
 252             prevp.parent
 253             and prevp.parent.type == syms.factor
 254             and prevp.type in MATH_OPERATORS
 255         ):
 256             return NO
 257
 258         elif (
 259             prevp.type == token.RIGHTSHIFT
 260             and prevp.parent
 261             and prevp.parent.type == syms.shift_expr
 262             and prevp.prev_sibling
 263             and prevp.prev_sibling.type == token.NAME
 264             and prevp.prev_sibling.value == "print"  # type: ignore
 265         ):
 266             # Python 2 print chevron
 267             return NO
 268         elif prevp.type == token.AT and p.parent and p.parent.type == syms.decorator:
 269             # no space in decorators
 270             return NO
 271
 272     elif prev.type in OPENING_BRACKETS:
 273         return NO
 274
 275     if p.type in {syms.parameters, syms.arglist}:
 276         # untyped function signatures or calls
 277         if not prev or prev.type != token.COMMA:
 278             return NO
 279
 280     elif p.type == syms.varargslist:
 281         # lambdas
 282         if prev and prev.type != token.COMMA:
 283             return NO
 284
 285     elif p.type == syms.typedargslist:
 286         # typed function signatures
 287         if not prev:
 288             return NO
 289
 290         if t == token.EQUAL:
 291             if prev.type != syms.tname:
 292                 return NO
 293
 294         elif prev.type == token.EQUAL:
 295             # A bit hacky: if the equal sign has whitespace, it means we
 296             # previously found it's a typed argument.  So, we're using that, too.
 297             return prev.prefix
 298
 299         elif prev.type != token.COMMA:
 300             return NO
 301
 302     elif p.type == syms.tname:
 303         # type names
 304         if not prev:
 305             prevp = preceding_leaf(p)
 306             if not prevp or prevp.type != token.COMMA:
 307                 return NO
 308
 309     elif p.type == syms.trailer:
 310         # attributes and calls
 311         if t == token.LPAR or t == token.RPAR:
 312             return NO
 313
 314         if not prev:
 315             if t == token.DOT:
 316                 prevp = preceding_leaf(p)
 317                 if not prevp or prevp.type != token.NUMBER:
 318                     return NO
 319
 320             elif t == token.LSQB:
 321                 return NO
 322
 323         elif prev.type != token.COMMA:
 324             return NO
 325
 326     elif p.type == syms.argument:
 327         # single argument
 328         if t == token.EQUAL:
 329             return NO
 330
 331         if not prev:
 332             prevp = preceding_leaf(p)
 333             if not prevp or prevp.type == token.LPAR:
 334                 return NO
 335
 336         elif prev.type in {token.EQUAL} | VARARGS_SPECIALS:
 337             return NO
 338
 339     elif p.type == syms.decorator:
 340         # decorators
 341         return NO
 342
 343     elif p.type == syms.dotted_name:
 344         if prev:
 345             return NO
 346
 347         prevp = preceding_leaf(p)
 348         if not prevp or prevp.type == token.AT or prevp.type == token.DOT:
 349             return NO
 350
 351     elif p.type == syms.classdef:
 352         if t == token.LPAR:
 353             return NO
 354
 355         if prev and prev.type == token.LPAR:
 356             return NO
 357
 358     elif p.type in {syms.subscript, syms.sliceop}:
 359         # indexing
 360         if not prev:
 361             assert p.parent is not None, "subscripts are always parented"
 362             if p.parent.type == syms.subscriptlist:
 363                 return SPACE
 364
 365             return NO
 366
 367         elif not complex_subscript:
 368             return NO
 369
 370     elif p.type == syms.atom:
 371         if prev and t == token.DOT:
 372             # dots, but not the first one.
 373             return NO
 374
 375     elif p.type == syms.dictsetmaker:
 376         # dict unpacking
 377         if prev and prev.type == token.DOUBLESTAR:
 378             return NO
 379
 380     elif p.type in {syms.factor, syms.star_expr}:
 381         # unary ops
 382         if not prev:
 383             prevp = preceding_leaf(p)
 384             if not prevp or prevp.type in OPENING_BRACKETS:
 385                 return NO
 386
 387             prevp_parent = prevp.parent
 388             assert prevp_parent is not None
 389             if prevp.type == token.COLON and prevp_parent.type in {
 390                 syms.subscript,
 391                 syms.sliceop,
 392             }:
 393                 return NO
 394
 395             elif prevp.type == token.EQUAL and prevp_parent.type == syms.argument:
 396                 return NO
 397
 398         elif t in {token.NAME, token.NUMBER, token.STRING}:
 399             return NO
 400
 401     elif p.type == syms.import_from:
 402         if t == token.DOT:
 403             if prev and prev.type == token.DOT:
 404                 return NO
 405
 406         elif t == token.NAME:
 407             if v == "import":
 408                 return SPACE
 409
 410             if prev and prev.type == token.DOT:
 411                 return NO
 412
 413     elif p.type == syms.sliceop:
 414         return NO
 415
 416     return SPACE
 417
 418
 419 def preceding_leaf(node: Optional[LN]) -> Optional[Leaf]:
 420     """Return the first leaf that precedes `node`, if any."""
 421     while node:
 422         res = node.prev_sibling
 423         if res:
 424             if isinstance(res, Leaf):
 425                 return res
 426
 427             try:
 428                 return list(res.leaves())[-1]
 429
 430             except IndexError:
 431                 return None
 432
 433         node = node.parent
 434     return None
 435
 436
 437 def prev_siblings_are(node: Optional[LN], tokens: List[Optional[NodeType]]) -> bool:
 438     """Return if the `node` and its previous siblings match types against the provided
 439     list of tokens; the provided `node`has its type matched against the last element in
 440     the list.  `None` can be used as the first element to declare that the start of the
 441     list is anchored at the start of its parent's children."""
 442     if not tokens:
 443         return True
 444     if tokens[-1] is None:
 445         return node is None
 446     if not node:
 447         return False
 448     if node.type != tokens[-1]:
 449         return False
 450     return prev_siblings_are(node.prev_sibling, tokens[:-1])
 451
 452
 453 def last_two_except(leaves: List[Leaf], omit: Collection[LeafID]) -> Tuple[Leaf, Leaf]:
 454     """Return (penultimate, last) leaves skipping brackets in `omit` and contents."""
 455     stop_after: Optional[Leaf] = None
 456     last: Optional[Leaf] = None
 457     for leaf in reversed(leaves):
 458         if stop_after:
 459             if leaf is stop_after:
 460                 stop_after = None
 461             continue
 462
 463         if last:
 464             return leaf, last
 465
 466         if id(leaf) in omit:
 467             stop_after = leaf.opening_bracket
 468         else:
 469             last = leaf
 470     else:
 471         raise LookupError("Last two leaves were also skipped")
 472
 473
 474 def parent_type(node: Optional[LN]) -> Optional[NodeType]:
 475     """
 476     Returns:
 477         @node.parent.type, if @node is not None and has a parent.
 478             OR
 479         None, otherwise.
 480     """
 481     if node is None or node.parent is None:
 482         return None
 483
 484     return node.parent.type
 485
 486
 487 def child_towards(ancestor: Node, descendant: LN) -> Optional[LN]:
 488     """Return the child of `ancestor` that contains `descendant`."""
 489     node: Optional[LN] = descendant
 490     while node and node.parent != ancestor:
 491         node = node.parent
 492     return node
 493
 494
 495 def replace_child(old_child: LN, new_child: LN) -> None:
 496     """
 497     Side Effects:
 498         * If @old_child.parent is set, replace @old_child with @new_child in
 499         @old_child's underlying Node structure.
 500             OR
 501         * Otherwise, this function does nothing.
 502     """
 503     parent = old_child.parent
 504     if not parent:
 505         return
 506
 507     child_idx = old_child.remove()
 508     if child_idx is not None:
 509         parent.insert_child(child_idx, new_child)
 510
 511
 512 def container_of(leaf: Leaf) -> LN:
 513     """Return `leaf` or one of its ancestors that is the topmost container of it.
 514
 515     By "container" we mean a node where `leaf` is the very first child.
 516     """
 517     same_prefix = leaf.prefix
 518     container: LN = leaf
 519     while container:
 520         parent = container.parent
 521         if parent is None:
 522             break
 523
 524         if parent.children[0].prefix != same_prefix:
 525             break
 526
 527         if parent.type == syms.file_input:
 528             break
 529
 530         if parent.prev_sibling is not None and parent.prev_sibling.type in BRACKETS:
 531             break
 532
 533         container = parent
 534     return container
 535
 536
 537 def first_leaf_column(node: Node) -> Optional[int]:
 538     """Returns the column of the first leaf child of a node."""
 539     for child in node.children:
 540         if isinstance(child, Leaf):
 541             return child.column
 542     return None
 543
 544
 545 def first_child_is_arith(node: Node) -> bool:
 546     """Whether first child is an arithmetic or a binary arithmetic expression"""
 547     expr_types = {
 548         syms.arith_expr,
 549         syms.shift_expr,
 550         syms.xor_expr,
 551         syms.and_expr,
 552     }
 553     return bool(node.children and node.children[0].type in expr_types)
 554
 555
 556 def is_docstring(leaf: Leaf) -> bool:
 557     if prev_siblings_are(
 558         leaf.parent, [None, token.NEWLINE, token.INDENT, syms.simple_stmt]
 559     ):
 560         return True
 561
 562     # Multiline docstring on the same line as the `def`.
 563     if prev_siblings_are(leaf.parent, [syms.parameters, token.COLON, syms.simple_stmt]):
 564         # `syms.parameters` is only used in funcdefs and async_funcdefs in the Python
 565         # grammar. We're safe to return True without further checks.
 566         return True
 567
 568     return False
 569
 570
 571 def is_empty_tuple(node: LN) -> bool:
 572     """Return True if `node` holds an empty tuple."""
 573     return (
 574         node.type == syms.atom
 575         and len(node.children) == 2
 576         and node.children[0].type == token.LPAR
 577         and node.children[1].type == token.RPAR
 578     )
 579
 580
 581 def is_one_tuple(node: LN) -> bool:
 582     """Return True if `node` holds a tuple with one element, with or without parens."""
 583     if node.type == syms.atom:
 584         gexp = unwrap_singleton_parenthesis(node)
 585         if gexp is None or gexp.type != syms.testlist_gexp:
 586             return False
 587
 588         return len(gexp.children) == 2 and gexp.children[1].type == token.COMMA
 589
 590     return (
 591         node.type in IMPLICIT_TUPLE
 592         and len(node.children) == 2
 593         and node.children[1].type == token.COMMA
 594     )
 595
 596
 597 def is_one_tuple_between(opening: Leaf, closing: Leaf, leaves: List[Leaf]) -> bool:
 598     """Return True if content between `opening` and `closing` looks like a one-tuple."""
 599     if opening.type != token.LPAR and closing.type != token.RPAR:
 600         return False
 601
 602     depth = closing.bracket_depth + 1
 603     for _opening_index, leaf in enumerate(leaves):
 604         if leaf is opening:
 605             break
 606
 607     else:
 608         raise LookupError("Opening paren not found in `leaves`")
 609
 610     commas = 0
 611     _opening_index += 1
 612     for leaf in leaves[_opening_index:]:
 613         if leaf is closing:
 614             break
 615
 616         bracket_depth = leaf.bracket_depth
 617         if bracket_depth == depth and leaf.type == token.COMMA:
 618             commas += 1
 619             if leaf.parent and leaf.parent.type in {
 620                 syms.arglist,
 621                 syms.typedargslist,
 622             }:
 623                 commas += 1
 624                 break
 625
 626     return commas < 2
 627
 628
 629 def is_walrus_assignment(node: LN) -> bool:
 630     """Return True iff `node` is of the shape ( test := test )"""
 631     inner = unwrap_singleton_parenthesis(node)
 632     return inner is not None and inner.type == syms.namedexpr_test
 633
 634
 635 def is_simple_decorator_trailer(node: LN, last: bool = False) -> bool:
 636     """Return True iff `node` is a trailer valid in a simple decorator"""
 637     return node.type == syms.trailer and (
 638         (
 639             len(node.children) == 2
 640             and node.children[0].type == token.DOT
 641             and node.children[1].type == token.NAME
 642         )
 643         # last trailer can be an argument-less parentheses pair
 644         or (
 645             last
 646             and len(node.children) == 2
 647             and node.children[0].type == token.LPAR
 648             and node.children[1].type == token.RPAR
 649         )
 650         # last trailer can be arguments
 651         or (
 652             last
 653             and len(node.children) == 3
 654             and node.children[0].type == token.LPAR
 655             # and node.children[1].type == syms.argument
 656             and node.children[2].type == token.RPAR
 657         )
 658     )
 659
 660
 661 def is_simple_decorator_expression(node: LN) -> bool:
 662     """Return True iff `node` could be a 'dotted name' decorator
 663
 664     This function takes the node of the 'namedexpr_test' of the new decorator
 665     grammar and test if it would be valid under the old decorator grammar.
 666
 667     The old grammar was: decorator: @ dotted_name [arguments] NEWLINE
 668     The new grammar is : decorator: @ namedexpr_test NEWLINE
 669     """
 670     if node.type == token.NAME:
 671         return True
 672     if node.type == syms.power:
 673         if node.children:
 674             return (
 675                 node.children[0].type == token.NAME
 676                 and all(map(is_simple_decorator_trailer, node.children[1:-1]))
 677                 and (
 678                     len(node.children) < 2
 679                     or is_simple_decorator_trailer(node.children[-1], last=True)
 680                 )
 681             )
 682     return False
 683
 684
 685 def is_yield(node: LN) -> bool:
 686     """Return True if `node` holds a `yield` or `yield from` expression."""
 687     if node.type == syms.yield_expr:
 688         return True
 689
 690     if node.type == token.NAME and node.value == "yield":  # type: ignore
 691         return True
 692
 693     if node.type != syms.atom:
 694         return False
 695
 696     if len(node.children) != 3:
 697         return False
 698
 699     lpar, expr, rpar = node.children
 700     if lpar.type == token.LPAR and rpar.type == token.RPAR:
 701         return is_yield(expr)
 702
 703     return False
 704
 705
 706 def is_vararg(leaf: Leaf, within: Set[NodeType]) -> bool:
 707     """Return True if `leaf` is a star or double star in a vararg or kwarg.
 708
 709     If `within` includes VARARGS_PARENTS, this applies to function signatures.
 710     If `within` includes UNPACKING_PARENTS, it applies to right hand-side
 711     extended iterable unpacking (PEP 3132) and additional unpacking
 712     generalizations (PEP 448).
 713     """
 714     if leaf.type not in VARARGS_SPECIALS or not leaf.parent:
 715         return False
 716
 717     p = leaf.parent
 718     if p.type == syms.star_expr:
 719         # Star expressions are also used as assignment targets in extended
 720         # iterable unpacking (PEP 3132).  See what its parent is instead.
 721         if not p.parent:
 722             return False
 723
 724         p = p.parent
 725
 726     return p.type in within
 727
 728
 729 def is_multiline_string(leaf: Leaf) -> bool:
 730     """Return True if `leaf` is a multiline string that actually spans many lines."""
 731     return has_triple_quotes(leaf.value) and "\n" in leaf.value
 732
 733
 734 def is_stub_suite(node: Node) -> bool:
 735     """Return True if `node` is a suite with a stub body."""
 736     if (
 737         len(node.children) != 4
 738         or node.children[0].type != token.NEWLINE
 739         or node.children[1].type != token.INDENT
 740         or node.children[3].type != token.DEDENT
 741     ):
 742         return False
 743
 744     return is_stub_body(node.children[2])
 745
 746
 747 def is_stub_body(node: LN) -> bool:
 748     """Return True if `node` is a simple statement containing an ellipsis."""
 749     if not isinstance(node, Node) or node.type != syms.simple_stmt:
 750         return False
 751
 752     if len(node.children) != 2:
 753         return False
 754
 755     child = node.children[0]
 756     return (
 757         child.type == syms.atom
 758         and len(child.children) == 3
 759         and all(leaf == Leaf(token.DOT, ".") for leaf in child.children)
 760     )
 761
 762
 763 def is_atom_with_invisible_parens(node: LN) -> bool:
 764     """Given a `LN`, determines whether it's an atom `node` with invisible
 765     parens. Useful in dedupe-ing and normalizing parens.
 766     """
 767     if isinstance(node, Leaf) or node.type != syms.atom:
 768         return False
 769
 770     first, last = node.children[0], node.children[-1]
 771     return (
 772         isinstance(first, Leaf)
 773         and first.type == token.LPAR
 774         and first.value == ""
 775         and isinstance(last, Leaf)
 776         and last.type == token.RPAR
 777         and last.value == ""
 778     )
 779
 780
 781 def is_empty_par(leaf: Leaf) -> bool:
 782     return is_empty_lpar(leaf) or is_empty_rpar(leaf)
 783
 784
 785 def is_empty_lpar(leaf: Leaf) -> bool:
 786     return leaf.type == token.LPAR and leaf.value == ""
 787
 788
 789 def is_empty_rpar(leaf: Leaf) -> bool:
 790     return leaf.type == token.RPAR and leaf.value == ""
 791
 792
 793 def is_import(leaf: Leaf) -> bool:
 794     """Return True if the given leaf starts an import statement."""
 795     p = leaf.parent
 796     t = leaf.type
 797     v = leaf.value
 798     return bool(
 799         t == token.NAME
 800         and (
 801             (v == "import" and p and p.type == syms.import_name)
 802             or (v == "from" and p and p.type == syms.import_from)
 803         )
 804     )
 805
 806
 807 def is_type_comment(leaf: Leaf, suffix: str = "") -> bool:
 808     """Return True if the given leaf is a special comment.
 809     Only returns true for type comments for now."""
 810     t = leaf.type
 811     v = leaf.value
 812     return t in {token.COMMENT, STANDALONE_COMMENT} and v.startswith("# type:" + suffix)
 813
 814
 815 def wrap_in_parentheses(parent: Node, child: LN, *, visible: bool = True) -> None:
 816     """Wrap `child` in parentheses.
 817
 818     This replaces `child` with an atom holding the parentheses and the old
 819     child.  That requires moving the prefix.
 820
 821     If `visible` is False, the leaves will be valueless (and thus invisible).
 822     """
 823     lpar = Leaf(token.LPAR, "(" if visible else "")
 824     rpar = Leaf(token.RPAR, ")" if visible else "")
 825     prefix = child.prefix
 826     child.prefix = ""
 827     index = child.remove() or 0
 828     new_child = Node(syms.atom, [lpar, child, rpar])
 829     new_child.prefix = prefix
 830     parent.insert_child(index, new_child)
 831
 832
 833 def unwrap_singleton_parenthesis(node: LN) -> Optional[LN]:
 834     """Returns `wrapped` if `node` is of the shape ( wrapped ).
 835
 836     Parenthesis can be optional. Returns None otherwise"""
 837     if len(node.children) != 3:
 838         return None
 839
 840     lpar, wrapped, rpar = node.children
 841     if not (lpar.type == token.LPAR and rpar.type == token.RPAR):
 842         return None
 843
 844     return wrapped
 845
 846
 847 def ensure_visible(leaf: Leaf) -> None:
 848     """Make sure parentheses are visible.
 849
 850     They could be invisible as part of some statements (see
 851     :func:`normalize_invisible_parens` and :func:`visit_import_from`).
 852     """
 853     if leaf.type == token.LPAR:
 854         leaf.value = "("
 855     elif leaf.type == token.RPAR:
 856         leaf.value = ")"