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