src/black/nodes.py

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