# Copyright (c) Meta Platforms, Inc. and affiliates. # # This source code is licensed under the MIT license found in the # LICENSE file in the root directory of this source tree. from inspect import ismethod, signature from typing import ( Any, Callable, cast, Dict, get_type_hints, List, Optional, Sequence, Set, Tuple, Type, Union, ) import libcst as cst from libcst import CSTTransformer, CSTVisitor from libcst._types import CSTNodeT from libcst.matchers._decorators import ( CONSTRUCTED_LEAVE_MATCHER_ATTR, CONSTRUCTED_VISIT_MATCHER_ATTR, VISIT_NEGATIVE_MATCHER_ATTR, VISIT_POSITIVE_MATCHER_ATTR, ) from libcst.matchers._matcher_base import ( AllOf, AtLeastN, AtMostN, BaseMatcherNode, extract, extractall, findall, matches, MatchIfTrue, MatchMetadata, MatchMetadataIfTrue, OneOf, replace, ) from libcst.matchers._return_types import TYPED_FUNCTION_RETURN_MAPPING try: # PEP 604 unions, in Python 3.10+ from types import UnionType except ImportError: # We use this for isinstance; no annotation will be an instance of this class UnionType: pass CONCRETE_METHODS: Set[str] = { *{f"visit_{cls.__name__}" for cls in TYPED_FUNCTION_RETURN_MAPPING}, *{f"leave_{cls.__name__}" for cls in TYPED_FUNCTION_RETURN_MAPPING}, } def is_property(obj: object, attr_name: str) -> bool: """Check if obj.attr is a property without evaluating it.""" return isinstance(getattr(type(obj), attr_name, None), property) # pyre-ignore We don't care about Any here, its not exposed. def _match_decorator_unpickler(kwargs: Any) -> "MatchDecoratorMismatch": return MatchDecoratorMismatch(**kwargs) class MatchDecoratorMismatch(Exception): def __init__(self, func: str, message: str) -> None: super().__init__(f"Invalid function signature for {func}: {message}") self.func = func self.message = message def __reduce__( self, ) -> Tuple[Callable[..., "MatchDecoratorMismatch"], Tuple[object, ...]]: return ( _match_decorator_unpickler, ({"func": self.func, "message": self.message},), ) def _get_possible_match_classes(matcher: BaseMatcherNode) -> List[Type[cst.CSTNode]]: if isinstance(matcher, (OneOf, AllOf)): return [getattr(cst, m.__class__.__name__) for m in matcher.options] else: return [getattr(cst, matcher.__class__.__name__)] def _annotation_is_union(annotation: object) -> bool: return ( isinstance(annotation, UnionType) or getattr(annotation, "__origin__", None) is Union ) def _get_possible_annotated_classes(annotation: object) -> List[Type[object]]: if _annotation_is_union(annotation): return getattr(annotation, "__args__", []) else: return [cast(Type[object], annotation)] def _get_valid_leave_annotations_for_classes( classes: Sequence[Type[cst.CSTNode]], ) -> Set[Type[object]]: retval: Set[Type[object]] = set() for cls in classes: # Look up the leave annotation for each class, combine them so we get a list of # all possible valid return annotations. Its not really possible for us (or # pyre) to fully enforce return types given the presence of OneOf/AllOf matchers, so # we do the best we can by taking a union of all valid return annotations. retval.update( _get_possible_annotated_classes(TYPED_FUNCTION_RETURN_MAPPING[cls]) ) return retval def _verify_return_annotation( possible_match_classes: Sequence[Type[cst.CSTNode]], # pyre-ignore We only care that meth is callable. meth: Callable[..., Any], decorator_name: str, *, expected_none: bool, ) -> None: type_hints = get_type_hints(meth) if expected_none: # Simply look for any annotation at all and if it exists, verify that # it is "None". if type_hints.get("return", type(None)) is not type(None): # noqa: E721 raise MatchDecoratorMismatch( meth.__qualname__, f"@{decorator_name} should only decorate functions that do " + "not return.", ) else: if "return" not in type_hints: # Can't check this, type annotation not supplied. return possible_annotated_classes = _get_possible_annotated_classes( type_hints["return"] ) possible_returns = _get_valid_leave_annotations_for_classes( possible_match_classes ) # Look at the union of specified return annotation, make sure that # they are all subclasses of the original leave_ return # annotations. This catches when somebody tries to return a new node # that we know can't fit where the existing node was in the tree. for ret in possible_annotated_classes: for annotation in possible_returns: if issubclass(ret, annotation): # This annotation is a superclass of the possible match, # so we know that the types are correct. break else: # The current ret was not a subclass of any of the annotated # return types. raise MatchDecoratorMismatch( meth.__qualname__, f"@{decorator_name} decorated function cannot return " + f"the type {ret.__name__}.", ) def _verify_parameter_annotations( possible_match_classes: Sequence[Type[cst.CSTNode]], # pyre-ignore We only care that meth is callable. meth: Callable[..., Any], decorator_name: str, *, expected_param_count: int, ) -> None: # First, verify that the number of parameters is sane. meth_signature = signature(meth) if len(meth_signature.parameters) != expected_param_count: raise MatchDecoratorMismatch( meth.__qualname__, f"@{decorator_name} should decorate functions which take " + f"{expected_param_count} parameter" + ("s" if expected_param_count > 1 else ""), ) # Finally, for each parameter, make sure that the annotation includes # each of the classes that might appear given the match string. This # can be done in the simple case by just specifying the correct cst node # type. For complex matches that use OneOf/AllOf, this could be a base class # that encompases all possible matches, or a union. params = [v for k, v in get_type_hints(meth).items() if k != "return"] for param in params: # Go through each possible matcher, and make sure that the annotation # for types is a superclass of each matcher. possible_annotated_classes = _get_possible_annotated_classes(param) for match in possible_match_classes: for annotation in possible_annotated_classes: if issubclass(match, annotation): # This annotation is a superclass of the possible match, # so we know that the types are correct. break else: # The current match was not a subclass of any of the annotated # types. raise MatchDecoratorMismatch( meth.__qualname__, f"@{decorator_name} can be called with {match.__name__} " + "but the decorated function parameter annotations do " + "not include this type.", ) def _check_types( # pyre-ignore We don't care about the type of sequence, just that its callable. decoratormap: Dict[BaseMatcherNode, Sequence[Callable[..., Any]]], decorator_name: str, *, expected_param_count: int, expected_none_return: bool, ) -> None: for matcher, methods in decoratormap.items(): # Given the matcher class we have, get the list of possible cst nodes that # could be passed to the functionis we wrap. possible_match_classes = _get_possible_match_classes(matcher) has_invalid_top_level = any( isinstance(m, (AtLeastN, AtMostN, MatchIfTrue)) for m in possible_match_classes ) # Now, loop through each function we wrap and verify that the type signature # is valid. for meth in methods: # First thing first, make sure this isn't wrapping an inner class. if not ismethod(meth): raise MatchDecoratorMismatch( meth.__qualname__, "Matcher decorators should only be used on methods of " + "MatcherDecoratableTransformer or " + "MatcherDecoratableVisitor", ) if has_invalid_top_level: raise MatchDecoratorMismatch( meth.__qualname__, "The root matcher in a matcher decorator cannot be an " + "AtLeastN, AtMostN or MatchIfTrue matcher", ) # Now, check that the return annotation is valid. _verify_return_annotation( possible_match_classes, meth, decorator_name, expected_none=expected_none_return, ) # Finally, check that the parameter annotations are valid. _verify_parameter_annotations( possible_match_classes, meth, decorator_name, expected_param_count=expected_param_count, ) def _gather_matchers(obj: object) -> Dict[BaseMatcherNode, Optional[cst.CSTNode]]: """ Set of gating matchers that we need to track and evaluate. We use these in conjunction with the call_if_inside and call_if_not_inside decorators to determine whether to call a visit/leave function. """ visit_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]] = {} for attr_name in dir(obj): if not is_property(obj, attr_name): func = getattr(obj, attr_name) for matcher in getattr(func, VISIT_POSITIVE_MATCHER_ATTR, []): visit_matchers[cast(BaseMatcherNode, matcher)] = None for matcher in getattr(func, VISIT_NEGATIVE_MATCHER_ATTR, []): visit_matchers[cast(BaseMatcherNode, matcher)] = None return visit_matchers def _assert_not_concrete( decorator_name: str, func: Callable[[cst.CSTNode], None] ) -> None: if func.__name__ in CONCRETE_METHODS: raise MatchDecoratorMismatch( func.__qualname__, f"@{decorator_name} should not decorate functions that are concrete " + "visit or leave methods.", ) def _gather_constructed_visit_funcs( obj: object, ) -> Dict[BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]]]: constructed_visitors: Dict[ BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]] ] = {} for funcname in dir(obj): if is_property(obj, funcname): continue possible_func = getattr(obj, funcname) if not ismethod(possible_func): continue func = cast(Callable[[cst.CSTNode], None], possible_func) matchers = getattr(func, CONSTRUCTED_VISIT_MATCHER_ATTR, []) if matchers: # Make sure that we aren't accidentally putting a @visit on a visit_Node. _assert_not_concrete("visit", func) for matcher in matchers: casted_matcher = cast(BaseMatcherNode, matcher) constructed_visitors[casted_matcher] = ( *constructed_visitors.get(casted_matcher, ()), func, ) return constructed_visitors # pyre-ignore: There is no reasonable way to type this, so ignore the Any type. This # is because the leave_* methods have a different signature depending on whether they # are in a MatcherDecoratableTransformer or a MatcherDecoratableVisitor. def _gather_constructed_leave_funcs( obj: object, ) -> Dict[BaseMatcherNode, Sequence[Callable[..., Any]]]: constructed_visitors: Dict[ BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]] ] = {} for funcname in dir(obj): if is_property(obj, funcname): continue possible_func = getattr(obj, funcname) if not ismethod(possible_func): continue func = cast(Callable[[cst.CSTNode], None], possible_func) matchers = getattr(func, CONSTRUCTED_LEAVE_MATCHER_ATTR, []) if matchers: # Make sure that we aren't accidentally putting a @leave on a leave_Node. _assert_not_concrete("leave", func) for matcher in matchers: casted_matcher = cast(BaseMatcherNode, matcher) constructed_visitors[casted_matcher] = ( *constructed_visitors.get(casted_matcher, ()), func, ) return constructed_visitors def _visit_matchers( matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]], node: cst.CSTNode, metadata_resolver: cst.MetadataDependent, ) -> Dict[BaseMatcherNode, Optional[cst.CSTNode]]: new_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]] = {} for matcher, existing_node in matchers.items(): # We don't care about visiting matchers that are already true. if existing_node is None and matches( node, matcher, metadata_resolver=metadata_resolver ): # This node matches! Remember which node it was so we can # cancel it later. new_matchers[matcher] = node else: new_matchers[matcher] = existing_node return new_matchers def _leave_matchers( matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]], node: cst.CSTNode ) -> Dict[BaseMatcherNode, Optional[cst.CSTNode]]: new_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]] = {} for matcher, existing_node in matchers.items(): if node is existing_node: # This node matches, so we are no longer inside it. new_matchers[matcher] = None else: # We aren't leaving this node. new_matchers[matcher] = existing_node return new_matchers def _all_positive_matchers_true( all_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]], obj: object ) -> bool: requested_matchers = getattr(obj, VISIT_POSITIVE_MATCHER_ATTR, []) for matcher in requested_matchers: if all_matchers[matcher] is None: # The passed in object has been decorated with a matcher that isn't # active. return False return True def _all_negative_matchers_false( all_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]], obj: object ) -> bool: requested_matchers = getattr(obj, VISIT_NEGATIVE_MATCHER_ATTR, []) for matcher in requested_matchers: if all_matchers[matcher] is not None: # The passed in object has been decorated with a matcher that is active. return False return True def _should_allow_visit( all_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]], obj: object ) -> bool: return _all_positive_matchers_true( all_matchers, obj ) and _all_negative_matchers_false(all_matchers, obj) def _visit_constructed_funcs( visit_funcs: Dict[BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]]], all_matchers: Dict[BaseMatcherNode, Optional[cst.CSTNode]], node: cst.CSTNode, metadata_resolver: cst.MetadataDependent, ) -> None: for matcher, visit_funcs in visit_funcs.items(): if matches(node, matcher, metadata_resolver=metadata_resolver): for visit_func in visit_funcs: if _should_allow_visit(all_matchers, visit_func): visit_func(node) class MatcherDecoratableTransformer(CSTTransformer): """ This class provides all of the features of a :class:`libcst.CSTTransformer`, and additionally supports various decorators to control when methods get called when traversing a tree. Use this instead of a :class:`libcst.CSTTransformer` if you wish to do more powerful decorator-based visiting. """ def __init__(self) -> None: CSTTransformer.__init__(self) self.__matchers: Optional[Dict[BaseMatcherNode, Optional[cst.CSTNode]]] = None # Mapping of matchers to functions. If in the course of visiting the tree, # a node matches one of these matchers, the corresponding function will be # called as if it was a visit_* method. self._extra_visit_funcs: Dict[ BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]] ] = _gather_constructed_visit_funcs(self) # Mapping of matchers to functions. If in the course of leaving the tree, # a node matches one of these matchers, the corresponding function will be # called as if it was a leave_* method. self._extra_leave_funcs: Dict[ BaseMatcherNode, Sequence[ Callable[ [cst.CSTNode, cst.CSTNode], Union[cst.CSTNode, cst.RemovalSentinel] ] ], ] = _gather_constructed_leave_funcs(self) # Make sure visit/leave functions constructed with @visit and @leave decorators # have correct type annotations. _check_types( self._extra_visit_funcs, "visit", expected_param_count=1, expected_none_return=True, ) _check_types( self._extra_leave_funcs, "leave", expected_param_count=2, expected_none_return=False, ) @property def _matchers(self) -> Dict[BaseMatcherNode, Optional[cst.CSTNode]]: if self.__matchers is None: self.__matchers = _gather_matchers(self) return self.__matchers @_matchers.setter def _matchers(self, value: Dict[BaseMatcherNode, Optional[cst.CSTNode]]) -> None: self.__matchers = value def on_visit(self, node: cst.CSTNode) -> bool: # First, evaluate any matchers that we have which we are not inside already. self._matchers = _visit_matchers(self._matchers, node, self) # Now, call any visitors that were hooked using a visit decorator. _visit_constructed_funcs(self._extra_visit_funcs, self._matchers, node, self) # Now, evaluate whether this current function has any matchers it requires. if not _should_allow_visit( self._matchers, getattr(self, f"visit_{type(node).__name__}", None) ): # We shouldn't visit this directly. However, we should continue # visiting its children. return True # Either the visit_func doesn't exist, we have no matchers, or we passed all # matchers. In either case, just call the superclass behavior. return CSTTransformer.on_visit(self, node) def on_leave( self, original_node: CSTNodeT, updated_node: CSTNodeT ) -> Union[CSTNodeT, cst.RemovalSentinel]: # First, evaluate whether this current function has a decorator on it. if _should_allow_visit( self._matchers, getattr(self, f"leave_{type(original_node).__name__}", None) ): retval = CSTTransformer.on_leave(self, original_node, updated_node) else: retval = updated_node # Now, call any visitors that were hooked using a leave decorator. for matcher, leave_funcs in reversed(list(self._extra_leave_funcs.items())): if not self.matches(original_node, matcher): continue for leave_func in leave_funcs: if _should_allow_visit(self._matchers, leave_func) and isinstance( retval, cst.CSTNode ): retval = leave_func(original_node, retval) # Now, see if we have any matchers we should deactivate. self._matchers = _leave_matchers(self._matchers, original_node) # pyre-ignore The return value of on_leave is subtly wrong in that we can # actually return any value that passes this node's parent's constructor # validation. Fixing this is beyond the scope of this file, and would involve # forcing a lot of ensure_type() checks across the codebase. return retval def on_visit_attribute(self, node: cst.CSTNode, attribute: str) -> None: # Evaluate whether this current function has a decorator on it. if _should_allow_visit( self._matchers, getattr(self, f"visit_{type(node).__name__}_{attribute}", None), ): # Either the visit_func doesn't exist, we have no matchers, or we passed all # matchers. In either case, just call the superclass behavior. return CSTTransformer.on_visit_attribute(self, node, attribute) def on_leave_attribute(self, original_node: cst.CSTNode, attribute: str) -> None: # Evaluate whether this current function has a decorator on it. if _should_allow_visit( self._matchers, getattr(self, f"leave_{type(original_node).__name__}_{attribute}", None), ): # Either the visit_func doesn't exist, we have no matchers, or we passed all # matchers. In either case, just call the superclass behavior. CSTTransformer.on_leave_attribute(self, original_node, attribute) def matches( self, node: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: BaseMatcherNode, ) -> bool: """ A convenience method to call :func:`~libcst.matchers.matches` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.matches` as it is identical to this function. """ return matches(node, matcher, metadata_resolver=self) def findall( self, tree: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: Union[ BaseMatcherNode, MatchIfTrue[cst.CSTNode], MatchMetadata, MatchMetadataIfTrue, ], ) -> Sequence[cst.CSTNode]: """ A convenience method to call :func:`~libcst.matchers.findall` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.findall` as it is identical to this function. """ return findall(tree, matcher, metadata_resolver=self) def extract( self, node: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: BaseMatcherNode, ) -> Optional[Dict[str, Union[cst.CSTNode, Sequence[cst.CSTNode]]]]: """ A convenience method to call :func:`~libcst.matchers.extract` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.extract` as it is identical to this function. """ return extract(node, matcher, metadata_resolver=self) def extractall( self, tree: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: Union[ BaseMatcherNode, MatchIfTrue[cst.CSTNode], MatchMetadata, MatchMetadataIfTrue, ], ) -> Sequence[Dict[str, Union[cst.CSTNode, Sequence[cst.CSTNode]]]]: """ A convenience method to call :func:`~libcst.matchers.extractall` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.extractall` as it is identical to this function. """ return extractall(tree, matcher, metadata_resolver=self) def replace( self, tree: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: Union[ BaseMatcherNode, MatchIfTrue[cst.CSTNode], MatchMetadata, MatchMetadataIfTrue, ], replacement: Union[ cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode, Callable[ [cst.CSTNode, Dict[str, Union[cst.CSTNode, Sequence[cst.CSTNode]]]], Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], ], ], ) -> Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode]: """ A convenience method to call :func:`~libcst.matchers.replace` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.replace` as it is identical to this function. """ return replace(tree, matcher, replacement, metadata_resolver=self) class MatcherDecoratableVisitor(CSTVisitor): """ This class provides all of the features of a :class:`libcst.CSTVisitor`, and additionally supports various decorators to control when methods get called when traversing a tree. Use this instead of a :class:`libcst.CSTVisitor` if you wish to do more powerful decorator-based visiting. """ def __init__(self) -> None: CSTVisitor.__init__(self) self.__matchers: Optional[Dict[BaseMatcherNode, Optional[cst.CSTNode]]] = None # Mapping of matchers to functions. If in the course of visiting the tree, # a node matches one of these matchers, the corresponding function will be # called as if it was a visit_* method. self._extra_visit_funcs: Dict[ BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]] ] = _gather_constructed_visit_funcs(self) # Mapping of matchers to functions. If in the course of leaving the tree, # a node matches one of these matchers, the corresponding function will be # called as if it was a leave_* method. self._extra_leave_funcs: Dict[ BaseMatcherNode, Sequence[Callable[[cst.CSTNode], None]] ] = _gather_constructed_leave_funcs(self) # Make sure visit/leave functions constructed with @visit and @leave decorators # have correct type annotations. _check_types( self._extra_visit_funcs, "visit", expected_param_count=1, expected_none_return=True, ) _check_types( self._extra_leave_funcs, "leave", expected_param_count=1, expected_none_return=True, ) @property def _matchers(self) -> Dict[BaseMatcherNode, Optional[cst.CSTNode]]: if self.__matchers is None: self.__matchers = _gather_matchers(self) return self.__matchers @_matchers.setter def _matchers(self, value: Dict[BaseMatcherNode, Optional[cst.CSTNode]]) -> None: self.__matchers = value def on_visit(self, node: cst.CSTNode) -> bool: # First, evaluate any matchers that we have which we are not inside already. self._matchers = _visit_matchers(self._matchers, node, self) # Now, call any visitors that were hooked using a visit decorator. _visit_constructed_funcs(self._extra_visit_funcs, self._matchers, node, self) # Now, evaluate whether this current function has a decorator on it. if not _should_allow_visit( self._matchers, getattr(self, f"visit_{type(node).__name__}", None) ): # We shouldn't visit this directly. However, we should continue # visiting its children. return True # Either the visit_func doesn't exist, we have no matchers, or we passed all # matchers. In either case, just call the superclass behavior. return CSTVisitor.on_visit(self, node) def on_leave(self, original_node: cst.CSTNode) -> None: # First, evaluate whether this current function has a decorator on it. if _should_allow_visit( self._matchers, getattr(self, f"leave_{type(original_node).__name__}", None) ): CSTVisitor.on_leave(self, original_node) # Now, call any visitors that were hooked using a leave decorator. for matcher, leave_funcs in reversed(list(self._extra_leave_funcs.items())): if not self.matches(original_node, matcher): continue for leave_func in leave_funcs: if _should_allow_visit(self._matchers, leave_func): leave_func(original_node) # Now, see if we have any matchers we should deactivate. self._matchers = _leave_matchers(self._matchers, original_node) def on_visit_attribute(self, node: cst.CSTNode, attribute: str) -> None: # Evaluate whether this current function has a decorator on it. if _should_allow_visit( self._matchers, getattr(self, f"visit_{type(node).__name__}_{attribute}", None), ): # Either the visit_func doesn't exist, we have no matchers, or we passed all # matchers. In either case, just call the superclass behavior. return CSTVisitor.on_visit_attribute(self, node, attribute) def on_leave_attribute(self, original_node: cst.CSTNode, attribute: str) -> None: # Evaluate whether this current function has a decorator on it. if _should_allow_visit( self._matchers, getattr(self, f"leave_{type(original_node).__name__}_{attribute}", None), ): # Either the visit_func doesn't exist, we have no matchers, or we passed all # matchers. In either case, just call the superclass behavior. CSTVisitor.on_leave_attribute(self, original_node, attribute) def matches( self, node: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: BaseMatcherNode, ) -> bool: """ A convenience method to call :func:`~libcst.matchers.matches` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.matches` as it is identical to this function. """ return matches(node, matcher, metadata_resolver=self) def findall( self, tree: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: Union[ BaseMatcherNode, MatchIfTrue[cst.CSTNode], MatchMetadata, MatchMetadataIfTrue, ], ) -> Sequence[cst.CSTNode]: """ A convenience method to call :func:`~libcst.matchers.findall` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.findall` as it is identical to this function. """ return findall(tree, matcher, metadata_resolver=self) def extract( self, node: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: BaseMatcherNode, ) -> Optional[Dict[str, Union[cst.CSTNode, Sequence[cst.CSTNode]]]]: """ A convenience method to call :func:`~libcst.matchers.extract` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.extract` as it is identical to this function. """ return extract(node, matcher, metadata_resolver=self) def extractall( self, tree: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: Union[ BaseMatcherNode, MatchIfTrue[cst.CSTNode], MatchMetadata, MatchMetadataIfTrue, ], ) -> Sequence[Dict[str, Union[cst.CSTNode, Sequence[cst.CSTNode]]]]: """ A convenience method to call :func:`~libcst.matchers.extractall` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.extractall` as it is identical to this function. """ return extractall(tree, matcher, metadata_resolver=self) def replace( self, tree: Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], matcher: Union[ BaseMatcherNode, MatchIfTrue[cst.CSTNode], MatchMetadata, MatchMetadataIfTrue, ], replacement: Union[ cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode, Callable[ [cst.CSTNode, Dict[str, Union[cst.CSTNode, Sequence[cst.CSTNode]]]], Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode], ], ], ) -> Union[cst.MaybeSentinel, cst.RemovalSentinel, cst.CSTNode]: """ A convenience method to call :func:`~libcst.matchers.replace` without requiring an explicit parameter for metadata. Since our instance is an instance of :class:`libcst.MetadataDependent`, we work as a metadata resolver. Please see documentation for :func:`~libcst.matchers.replace` as it is identical to this function. """ return replace(tree, matcher, replacement, metadata_resolver=self)