o DDi4@szddlZddlZddlZddlmZddlmZmZddl m Z m Z ddl m Z mZmZmZmZmZmZmZmZmZmZmZmZmZmZddlZddlmZddlm Z m!Z!m"Z"ddl#m$Z$Gdd d e Z%ed d d Z&ed d d Z'edddZ(edZ)edZ*ededdZ+ededdZ,e-Z.GdddeZ/GdddZ0de%fddZ1Gdddee+e0Z2Gdddee&e0Z3Gdd d ee&e0Z4Gd!d"d"ee&Z5Gd#d$d$ee&Z6Gd%d&d&ee'Z7d'ee8ee8fde7e8fd(d)Z9Gd*d+d+Z:Gd,d-d-e:Z;Gd.d/d/e:Ze%j?fd4ee&e%fde>ee&e%ffd5d6Z@Gd7d8d8ee&e=ZAe%j?fd4ee&e%fdeAee&e%ffd9d:ZBd;e)de)fde8de)fd?d@ZDd4ee0e=e7ejEe:e%fdeFfdAdBZGed dCGdDdEdEZHdFeee!ejEfdGeee0e=e7ejEe:e%fdHe ejIejEge-fdeHfdIdJZJeee!ejEe8eFfZKeee0e%e8eFfZLdKeeKeeKfd4eeLeeLfdHe ejIejEge-fdeee8eejEeejEfffdLdMZMdKejEdNee:e4e:e3e:e5e:e6e:fdHe ejIejEge-fdeee8eejEeejEfffdOdPZNdKejEd4ee0e7ejEe:e5ee0e7ejEe:fe6ee0e7ejEe:ffdHe ejIejEge-fdeee8eejEeejEfffdQdRZOdKee!ejEfd4ee0e7ejEe:e5ee0e7ejEe:fe6ee0e7ejEe:ffdHe ejIejEge-fdeee8eejEeejEfffdSdTZPde ejIejEge-ffdUdVZQdWejRde ejIejEge-ffdXdYZSdZejTde ejIejEge-ffd[d\ZUdd]dKee!e"ejEfd4e0d^eeejRejTfdeee8eejEeejEfffd_d`ZVdd]dKee!e"ejEfd4e0d^eeejRejTfdeFfdadbZWGdcddddejXZYdd]deee!e"ejEejTfd4ee0e7ejEe:e5ee0e7ejEe:ffd^eeejRejTfdeeejEeee8eejEeejEffffdfdgZZdd]deee!e"ejEejTfd4ee0e7ejEe:fd^eeejRejTfdeejEfdhdiZ[dd]deee!e"ejEejTfd4ee0e7ejEe:fd^eeejRejTfdeee8eejEeejEfffdjdkZ\Gdldmdmej]Z^dd]deee!e"ejEejTfd4ee0e7ejEe:fdnee!e"ejEe ejEee8eejEeejEffgee!e"ejEfffd^eeejRejTfdee!e"ejEff dodpZ_dS)qN)ABCMeta) dataclassfields)autoEnum)CallablecastDictGenericIteratorListMappingNoReturnOptionalPatternSequenceTupleTypeTypeVarUnion)FlattenSentinel MaybeSentinelRemovalSentinel) LazyValuec@s$eZdZdZeZdefddZdS)DoNotCareSentinelaJ A sentinel that is used in matcher classes to indicate that a caller does not care what this value is. We recommend that you do not use this directly, and instead use the :func:`DoNotCare` helper. You do not need to use this for concrete matcher attributes since :func:`DoNotCare` is already the default. returncCsdS)Nz DoNotCare()selfrrV/var/www/Datamplify/venv/lib/python3.10/site-packages/libcst/matchers/_matcher_base.py__repr__/szDoNotCareSentinel.__repr__N)__name__ __module__ __qualname____doc__rDEFAULTstrr rrrrr$sr _MatcherTT) covariant _MatchIfTrueT_BaseMatcherNodeSelfTBaseMatcherNode)bound _OtherNodeT_MetadataValueT _MatcherTypeT_OtherNodeMatcherTypeTc@s&eZdZdZdedddfddZdS) AbstractBaseMatcherNodeMetaz Metaclass that all matcher nodes uses. Allows chaining 2 node type together with an bitwise-or operator to produce an :class:`TypeOf` matcher. noder+rzTypeOf[Type[BaseMatcherNode]]cC t||SN)TypeOf)rr2rrr__or__I z"AbstractBaseMatcherNodeMeta.__or__N)r!r"r#r$rr6rrrrr1Asr1c@sNeZdZdZdededdfddZdededdfd d Zdedd fd d ZdS)r+an Base class that all concrete matchers subclass from. :class:`OneOf` and :class:`AllOf` also subclass from this in order to allow them to be used in any place that a concrete matcher is allowed. This means that, for example, you can call :func:`matches` with a concrete matcher, or a :class:`OneOf` with several concrete matchers as options. rotherrz0OneOf[Union[_BaseMatcherNodeSelfT, _OtherNodeT]]cCr3r4OneOfrr8rrrr6W zBaseMatcherNode.__or__z0AllOf[Union[_BaseMatcherNodeSelfT, _OtherNodeT]]cCr3r4AllOfr;rrr__and__\r<zBaseMatcherNode.__and__r*cCttt|Sr4)rr* _InverseOfrrrr __invert__azBaseMatcherNode.__invert__N) r!r"r#r$r*r-r6r?rBrrrrr+Ms"   rcCstjS)a8 Used when you want to match exactly one node, but you do not care what node it is. Useful inside sequences such as a :class:`libcst.matchers.Call`'s args attribte. You do not need to use this for concrete matcher attributes since :func:`DoNotCare` is already the default. For example, the following matcher would match against any function calls with three arguments, regardless of the arguments themselves and regardless of the function name that we were calling:: m.Call(args=[m.DoNotCare(), m.DoNotCare(), m.DoNotCare()]) )rr%rrrr DoNotCarees rDc@seZdZdZdeedfddfddZedefdd Z ede e fd d Z d e d e de fddZdeddfddZdedefddZdddZdefddZdS)r5a Matcher that matches any one of the given types. Useful when you want to work with trees where a common property might belong to more than a single type. For example, if you want either a binary operation or a boolean operation where the left side has a name ``foo``:: m.TypeOf(m.BinaryOperation, m.BooleanOperation)(left = m.Name("foo")) Or you could use the shorthand, like:: (m.BinaryOperation | m.BooleanOperation)(left = m.Name("foo")) Also :class:`TypeOf` matchers can be used with initalizing in the default state of other node matchers (without passing any extra patterns):: m.Name | m.SimpleString The will be equal to:: m.OneOf(m.Name(), m.SimpleString()) optionszTypeOf[_MatcherTypeT]rNcGs\g}|D]}t|tr|jrtd||jq||qd|_dif|_t ||_dS)Nz:Cannot chain an uninitalized TypeOf with an initalized oneFr) isinstancer5 initalized Exceptionextend _raw_optionsappend _initalized _call_itemstuplerrEactual_optionsoptionrrr__init__s   zTypeOf.__init__cC|jSr4)rLrrrrrGszTypeOf.initalizedccs0|jD]}|j\}}||i|}|VqdSr4)rJrM)rrQargskwargsmatcher_patternrrrrEs   zTypeOf.optionsrTrUcOsd|_||f|_|SNT)rLrM)rrTrUrrr__call__s zTypeOf.__call__r8z4TypeOf[Union[_MatcherTypeT, _OtherNodeMatcherTypeT]]cCsttttf||Sr4)r5rr/r0r;rrrr6z TypeOf.__or__cCs&t|j|j}}td|d|)Nz.TypeError: unsupported operand type(s) for &: z and )typer! TypeError)rr8leftrightrrrr?szTypeOf.__and__AllOf[BaseMatcherNode]cCsttt|jSr4)r>map DoesNotMatchrErrrrrBszTypeOf.__invert__cCs*ddd|jD}d|d|jdS)N, cs|]}t|VqdSr4repr).0rQrrr z"TypeOf.__repr__..zTypeOf(z, initalized = ))joinrJrG)rtypesrrrr szTypeOf.__repr__)rr^)r!r"r#r$rr/rRpropertyboolrGr r+rEobjectrXr0r6rr?rBr&r rrrrr5us   r5c@s|eZdZdZdeedfddfddZedeefdd Z d e dd fd d Z d e de fddZ dddZdefddZdS)r:a Matcher that matches any one of its options. Useful when you want to match against one of several options for a single node. You can also construct a :class:`OneOf` matcher by using Python's bitwise or operator with concrete matcher classes. For example, you could match against ``True``/``False`` like:: m.OneOf(m.Name("True"), m.Name("False")) Or you could use the shorthand, like:: m.Name("True") | m.Name("False") rEOneOf[_MatcherT]rNcGsTg}|D]}t|trtdt|ttfr||jq||qt||_ dSN*Cannot use AllOf and OneOf in combination!) rFr>rHr:r5rIrErKrN_optionsrOrrrrRs  zOneOf.__init__cCrS)z The normalized list of options that we can choose from to satisfy a :class:`OneOf` matcher. If any of these matchers are true, the :class:`OneOf` matcher will also be considered a match. rqrrrrrEz OneOf.optionsr8$OneOf[Union[_MatcherT, _OtherNodeT]]cCr3r4r9r;rrrr6r7z OneOf.__or__cCtdrorHr;rrrr?z OneOf.__and__AllOf[_MatcherT]cCtdd|jDS)NcSg|]}t|qSrr`remrrr z$OneOf.__invert__..)r>rqrrrrrBzOneOf.__invert__cCdddd|jDdS)NzOneOf(racSrzrrcreorrrr~rz"OneOf.__repr__..rhrirqrrrrr zOneOf.__repr__)rrx)r!r"r#r$rr'rRrkrrEr-r6rr?rBr&r rrrrr:s   r:c@s|eZdZdZdeedfddfddZedeefdd Z d e de fd d Z d e dd fddZ dddZdefddZdS)r>a Matcher that matches all of its options. Useful when you want to match against a concrete matcher and a :class:`MatchIfTrue` at the same time. Also useful when you want to match against a concrete matcher and a :func:`DoesNotMatch` at the same time. You can also construct a :class:`AllOf` matcher by using Python's bitwise and operator with concrete matcher classes. For example, you could match against ``True`` in a roundabout way like:: m.AllOf(m.Name(), m.Name("True")) Or you could use the shorthand, like:: m.Name() & m.Name("True") Similar to :class:`OneOf`, this can be used in place of any concrete matcher. Real-world cases where :class:`AllOf` is useful are hard to come by but they are still provided for the limited edge cases in which they make sense. In the example above, we are redundantly matching against any LibCST :class:`~libcst.Name` node as well as LibCST :class:`~libcst.Name` nodes that have the ``value`` of ``True``. We could drop the first option entirely and get the same result. Often, if you are using a :class:`AllOf`, you can refactor your code to be simpler. For example, the following matches any function call to ``foo``, and any function call which takes zero arguments:: m.AllOf(m.Call(func=m.Name("foo")), m.Call(args=())) This could be refactored into the following equivalent concrete matcher:: m.Call(func=m.Name("foo"), args=()) rErxrNcGsbg}|D]%}t|trtdt|trtdt|tr$||jq||qt||_ dS)Nrpz+Cannot use AllOf and TypeOf in combination!) rFr:rHr5r>rIrErKrNrqrOrrrrRs    zAllOf.__init__cCrS)z The normalized list of options that we can choose from to satisfy a :class:`AllOf` matcher. If all of these matchers are true, the :class:`AllOf` matcher will also be considered a match. rrrrrrrE*rsz AllOf.optionsr8cCrurorvr;rrrr64rwz AllOf.__or__$AllOf[Union[_MatcherT, _OtherNodeT]]cCr3r4r=r;rrrr?7r7z AllOf.__and__rncCry)NcSrzrr{r|rrrr~<rz$AllOf.__invert__..)r:rqrrrrrB:rzAllOf.__invert__cCr)NzAllOf(racSrzrrcrrrrr~?rz"AllOf.__repr__..rhrrrrrr >rzAllOf.__repr__)rrn)r!r"r#r$rr'rRrkrrEr-rr6r?rBr&r rrrrr>s%   r>c@seZdZdZdeddfddZedefddZd edd fd d Z d edd fddZ de de fddZ defddZde fddZdS)rAaq Matcher that inverts the match result of its child. You can also construct a :class:`_InverseOf` matcher by using Python's bitwise invert operator with concrete matcher classes or any special matcher. Note that you should refrain from constructing a :class:`_InverseOf` directly, and should instead use the :func:`DoesNotMatch` helper function. For example, the following matches against any identifier that isn't ``True``/``False``:: m.DoesNotMatch(m.OneOf(m.Name("True"), m.Name("False"))) Or you could use the shorthand, like: ~(m.Name("True") | m.Name("False")) matcherrNcC ||_dSr4_matcher)rrrrrrRVr7z_InverseOf.__init__cCrS)z The matcher that we will evaluate and invert. If this matcher is true, then :class:`_InverseOf` will be considered not a match, and vice-versa. rrrrrrYz_InverseOf.matcherr8rtcCtttttft||Sr4rr:rr'r-r;rrrr6bz_InverseOf.__or__rcCrr4)rr>rr'r-r;rrrr?grz_InverseOf.__and__keycC t|j|Sr4getattrrrrrrr __getattr__l z_InverseOf.__getattr__cCrSr4rrrrrrBrsz_InverseOf.__invert__cCdt|jdS)Nz DoesNotMatch(rh)rdrrrrrr uz_InverseOf.__repr__)r!r"r#r$r'rRrkrr-r6r?r&rmrrBr rrrrrABsrAc@seZdZdZdededdfddZedefdd Zedefd d Z d e dd fddZ d e ddfddZ dede fddZdddZdefddZdS)_ExtractMatchingNodea Transparent pass-through matcher that captures the node which matches its children, making it available to the caller of :func:`extract` or :func:`extractall`. Note that you should refrain from constructing a :class:`_ExtractMatchingNode` directly, and should instead use the :func:`SaveMatchedNode` helper function. For example, the following will match against any binary operation whose left and right operands are not integers, saving those expressions for later inspection. If used inside :func:`extract` or :func:`extractall`, the resulting dictionary will contain the keys ``left_operand`` and ``right_operand``. m.BinaryOperation( left=m.SaveMatchedNode( m.DoesNotMatch(m.Integer()), "left_operand", ), right=m.SaveMatchedNode( m.DoesNotMatch(m.Integer()), "right_operand", ), ) rnamerNcC||_||_dSr4)r_name)rrrrrrrRs z_ExtractMatchingNode.__init__cCrS)z The matcher that we will evaluate and capture matching LibCST nodes for. If this matcher is true, then :class:`_ExtractMatchingNode` will be considered a match and will save the node which matched. rrrrrrrsz_ExtractMatchingNode.matchercCrS)z The name we will call our captured LibCST node inside the resulting dictionary returned by :func:`extract` or :func:`extractall`. )rrrrrrrz_ExtractMatchingNode.namer8rtcCrr4rr;rrrr6rz_ExtractMatchingNode.__or__rcCru)NzlCannot use AllOf with SavedMatchedNode children! Instead, you should use SaveMatchedNode(AllOf(options...)).rvr;rrrr?sz_ExtractMatchingNode.__and__rcCrr4rrrrrrrz _ExtractMatchingNode.__getattr__r'cCru)NzeCannot invert a SaveMatchedNode. Instead you should wrap SaveMatchedNode around your inversion itselfrvrrrrrBsz_ExtractMatchingNode.__invert__cCdt|jdt|jdS)NzSaveMatchedNode(matcher=z, name=rh)rdrrrrrrr sz_ExtractMatchingNode.__repr__)rr')r!r"r#r$r'r&rRrkrrr-r6r?rmrrBr rrrrrys  rc@seZdZUdZeegefed<deegefddfddZe deegeffdd Z d e dd fd d Z d e ddfddZ dddZdefddZdS) MatchIfTruea Matcher that matches if its child callable returns ``True``. The child callable should take one argument which is the attribute on the LibCST node we are trying to match against. This is useful if you want to do complex logic to determine if an attribute should match or not. One example of this is the :func:`MatchRegex` matcher build on top of :class:`MatchIfTrue` which takes a regular expression and matches any string attribute where a regex match is found. For example, to match on any identifier spelled with the letter ``e``:: m.Name(value=m.MatchIfTrue(lambda value: "e" in value)) This can be used in place of any concrete matcher as long as it is not the root matcher. Calling :func:`matches` directly on a :class:`MatchIfTrue` is redundant since you can just call the child callable directly with the node you are passing to :func:`matches`. _funcfuncrNcCrr4r)rrrrrrRr7zMatchIfTrue.__init__cCrS)z The function that we will call with a LibCST node in order to determine if we match. If the function returns ``True`` then we consider ourselves to be a match. rrrrrrrszMatchIfTrue.funcr8z5OneOf[Union[MatchIfTrue[_MatchIfTrueT], _OtherNodeT]]cCr3r4r9r;rrrr6r<zMatchIfTrue.__or__z5AllOf[Union[MatchIfTrue[_MatchIfTrueT], _OtherNodeT]]cCr3r4r=r;rrrr?r<zMatchIfTrue.__and__MatchIfTrue[_MatchIfTrueT]cstfddS)Nc | Sr4rvalrrr z(MatchIfTrue.__invert__..)rrrrrrBszMatchIfTrue.__invert__cCr)Nz MatchIfTrue(rh)rdrrrrrr rzMatchIfTrue.__repr__)rr)r!r"r#r$rr)rl__annotations__rRrkrr-r6r?rBr&r rrrrrs$    rregexcsdtdtffdd }t|S)a Used as a convenience wrapper to :class:`MatchIfTrue` which allows for matching a string attribute against a regex. ``regex`` can be any regular expression string or a compiled ``Pattern``. This uses Python's re module under the hood and is compatible with syntax documented on `docs.python.org `_. For example, to match against any identifier that is at least one character long and only contains alphabetical characters:: m.Name(value=m.MatchRegex(r'[A-Za-z]+')) This can be used in place of any string literal when constructing a concrete matcher. valuercst|tr tt|SdS)NF)rFr&rlre fullmatch)rrrr _match_funcs zMatchRegex.._match_func)rmrlr)rrrrr MatchRegexsrc@eZdZdZdS)_BaseMetadataMatcherz7 Class that's only around for typing purposes. Nr!r"r#r$rrrrrsrc@seZdZdZdeejededdfddZe dej fdd Z e de fd d Z d edd fddZd eddfddZdddZdefddZdS) MatchMetadataa Matcher that looks up the metadata on the current node using the provided metadata provider and compares the value on the node against the value provided to :class:`MatchMetadata`. If the metadata provider is unresolved, a :class:`LookupError` exeption will be raised and ask you to provide a :class:`~libcst.metadata.MetadataWrapper`. If the metadata value does not exist for a particular node, :class:`MatchMetadata` will be considered not a match. For example, to match against any function call which has one parameter which is used in a load expression context:: m.Call( args=[ m.Arg( m.MatchMetadata( meta.ExpressionContextProvider, meta.ExpressionContext.LOAD, ) ) ] ) To match against any :class:`~libcst.Name` node for the identifier ``foo`` which is the target of an assignment:: m.Name( value="foo", metadata=m.MatchMetadata( meta.ExpressionContextProvider, meta.ExpressionContext.STORE, ) ) This can be used in place of any concrete matcher as long as it is not the root matcher. Calling :func:`matches` directly on a :class:`MatchMetadata` is redundant since you can just check the metadata on the root node that you are passing to :func:`matches`. rrrNcCrr4)_key_value)rrrrrrrRO zMatchMetadata.__init__cCrS)a The metadata provider that we will use to fetch values when identifying whether a node matches this matcher. We compare the value returned from the metadata provider to the value provided in ``value`` when determining a match. rrrrrrWrszMatchMetadata.keycCrS)z The value that we will compare against the return from the metadata provider for each node when determining a match. )rrrrrr`rzMatchMetadata.valuer8z(OneOf[Union[MatchMetadata, _OtherNodeT]]cCr3r4r9r;rrrr6ir7zMatchMetadata.__or__z(AllOf[Union[MatchMetadata, _OtherNodeT]]cCr3r4r=r;rrrr?lr7zMatchMetadata.__and__cCr@r4)rrrArrrrrBoszMatchMetadata.__invert__cCr)NzMatchMetadata(key=z, value=rh)rdrrrrrrr trzMatchMetadata.__repr__)rr)r!r"r#r$rmetaBaseMetadataProviderr.rRrk ProviderTrrmrr-r6r?rBr&r rrrrr&s"(   rc@seZdZdZdeejedeege fddfddZ e dej fdd Z e deege ffd d Zd edd fddZd eddfddZdddZdefddZdS)MatchMetadataIfTruea5 Matcher that looks up the metadata on the current node using the provided metadata provider and passes it to a callable which can inspect the metadata further, returning ``True`` if the matcher should be considered a match. If the metadata provider is unresolved, a :class:`LookupError` exeption will be raised and ask you to provide a :class:`~libcst.metadata.MetadataWrapper`. If the metadata value does not exist for a particular node, :class:`MatchMetadataIfTrue` will be considered not a match. For example, to match against any arg whose qualified name might be ``typing.Dict``:: m.Call( args=[ m.Arg( m.MatchMetadataIfTrue( meta.QualifiedNameProvider, lambda qualnames: any(n.name == "typing.Dict" for n in qualnames) ) ) ] ) To match against any :class:`~libcst.Name` node for the identifier ``foo`` as long as that identifier is found at the beginning of an unindented line:: m.Name( value="foo", metadata=m.MatchMetadataIfTrue( meta.PositionProvider, lambda position: position.start.column == 0, ) ) This can be used in place of any concrete matcher as long as it is not the root matcher. Calling :func:`matches` directly on a :class:`MatchMetadataIfTrue` is redundant since you can just check the metadata on the root node that you are passing to :func:`matches`. rrrNcCrr4)rr)rrrrrrrRrzMatchMetadataIfTrue.__init__cCrS)z The metadata provider that we will use to fetch values when identifying whether a node matches this matcher. We pass the value returned from the metadata provider to the callable given to us in ``func``. rrrrrrrszMatchMetadataIfTrue.keycCrS)z The function that we will call with a value retrieved from the metadata provider provided in ``key``. If the function returns ``True`` then we consider ourselves to be a match. rrrrrrrszMatchMetadataIfTrue.funcr8z.OneOf[Union[MatchMetadataIfTrue, _OtherNodeT]]cCr3r4r9r;rrrr6r<zMatchMetadataIfTrue.__or__z.AllOf[Union[MatchMetadataIfTrue, _OtherNodeT]]cCr3r4r=r;rrrr?r<zMatchMetadataIfTrue.__and__cstjfddS)Ncrr4rrrrrrrz0MatchMetadataIfTrue.__invert__..)rrrrrrrBrzMatchMetadataIfTrue.__invert__cCr)NzMatchMetadataIfTrue(key=z, func=rh)rdrrrrrrr rzMatchMetadataIfTrue.__repr__)rr)r!r"r#r$rrrr.rrlrRrkrrrmrr-r6r?rBr&r rrrrrxs2(      rc@r)_BaseWildcardNodez A typing-only class for internal helpers in this module to be able to specify that they take a wildcard node type. Nrrrrrrsrc@eZdZdZejfdeeefdeddfddZ e defdd Z e deeeffd d Z d e defd dZd e defddZdefddZdefddZdS)AtLeastNa Matcher that matches ``n`` or more LibCST nodes in a row in a sequence. :class:`AtLeastN` defaults to matching against the :func:`DoNotCare` matcher, so if you do not specify a matcher as a child, :class:`AtLeastN` will match only by count. If you do specify a matcher as a child, :class:`AtLeastN` will instead make sure that each LibCST node matches the matcher supplied. For example, this will match all function calls with at least 3 arguments:: m.Call(args=[m.AtLeastN(n=3)]) This will match all function calls with 3 or more integer arguments:: m.Call(args=[m.AtLeastN(n=3, matcher=m.Arg(m.Integer()))]) You can combine sequence matchers with concrete matchers and special matchers and it will behave as you expect. For example, this will match all function calls that have 2 or more integer arguments in a row, followed by any arbitrary argument:: m.Call(args=[m.AtLeastN(n=2, matcher=m.Arg(m.Integer())), m.DoNotCare()]) And finally, this will match all function calls that have at least 5 arguments, the final one being an integer:: m.Call(args=[m.AtLeastN(n=4), m.Arg(m.Integer())]) rnrNcC*|dkr t|jjd||_||_dSNrz n attribute must be positiverH __class__r!_nrrrrrrrrR zAtLeastN.__init__cCrS)aH The number of nodes in a row that must match :attr:`AtLeastN.matcher` for this matcher to be considered a match. If there are less than ``n`` matches, this matcher will not be considered a match. If there are equal to or more than ``n`` matches, this matcher will be considered a match. rrrrrrsz AtLeastN.ncCrSzK The matcher which each node in a sequence needs to match. rrrrrr zAtLeastN.matcherr8cCru)Nz*AtLeastN cannot be used in a OneOf matcherrvr;rrrr6rwzAtLeastN.__or__cCru)Nz+AtLeastN cannot be used in an AllOf matcherrvr;rrrr?rwzAtLeastN.__and__cCru)Nz"Cannot invert an AtLeastN matcher!rvrrrrrBrwzAtLeastN.__invert__cC6|jdkrdt|jdSdt|jd|jdS)Nrz ZeroOrMore(rhz AtLeastN(, n=rrdrrrrrr  zAtLeastN.__repr__r!r"r#r$rr%rr'intrRrkrrrmrr6r?rBr&r rrrrrs$    rrcCtttttft|ddS)a Used as a convenience wrapper to :class:`AtLeastN` when ``n`` is equal to ``0``. Use this when you want to match against any number of nodes in a sequence. For example, this will match any function call with zero or more arguments, as long as all of the arguments are integers:: m.Call(args=[m.ZeroOrMore(m.Arg(m.Integer()))]) This will match any function call where the first argument is an integer and it doesn't matter what the rest of the arguments are:: m.Call(args=[m.Arg(m.Integer()), m.ZeroOrMore()]) You will often want to use :class:`ZeroOrMore` on both sides of a concrete matcher in order to match against sequences that contain a particular node in an arbitrary location. For example, the following will match any function call that takes in at least one string argument anywhere:: m.Call(args=[m.ZeroOrMore(), m.Arg(m.SimpleString()), m.ZeroOrMore()]) rr)rrrr'rrrrr ZeroOrMore"src@r)AtMostNa Matcher that matches ``n`` or fewer LibCST nodes in a row in a sequence. :class:`AtMostN` defaults to matching against the :func:`DoNotCare` matcher, so if you do not specify a matcher as a child, :class:`AtMostN` will match only by count. If you do specify a matcher as a child, :class:`AtMostN` will instead make sure that each LibCST node matches the matcher supplied. For example, this will match all function calls with 3 or fewer arguments:: m.Call(args=[m.AtMostN(n=3)]) This will match all function calls with 0, 1 or 2 string arguments:: m.Call(args=[m.AtMostN(n=2, matcher=m.Arg(m.SimpleString()))]) You can combine sequence matchers with concrete matchers and special matchers and it will behave as you expect. For example, this will match all function calls that have 0, 1 or 2 string arguments in a row, followed by an arbitrary argument:: m.Call(args=[m.AtMostN(n=2, matcher=m.Arg(m.SimpleString())), m.DoNotCare()]) And finally, this will match all function calls that have at least 2 arguments, the final one being a string:: m.Call(args=[m.AtMostN(n=2), m.Arg(m.SimpleString())]) rrrNcCrrrrrrrrR[rzAtMostN.__init__cCrS)aj The number of nodes in a row that must match :attr:`AtLeastN.matcher` for this matcher to be considered a match. If there are less than or equal to ``n`` matches, then this matcher will be considered a match. Any more than ``n`` matches in a row and this matcher will stop matching and be considered not a match. rrrrrrfs z AtMostN.ncCrSrrrrrrrqrzAtMostN.matcherr8cCru)Nz)AtMostN cannot be used in a OneOf matcherrvr;rrrr6yrwzAtMostN.__or__cCru)Nz*AtMostN cannot be used in an AllOf matcherrvr;rrrr?|rwzAtMostN.__and__cCru)Nz!Cannot invert an AtMostN matcher!rvrrrrrBrwzAtMostN.__invert__cCr)Nz ZeroOrOne(rhzAtMostN(rrrrrrr rzAtMostN.__repr__rrrrrr=s$    rcCr)a Used as a convenience wrapper to :class:`AtMostN` when ``n`` is equal to ``1``. This is effectively a maybe clause. For example, this will match any function call with zero or one integer argument:: m.Call(args=[m.ZeroOrOne(m.Arg(m.Integer()))]) This will match any function call that has two or three arguments, and the first and last arguments are strings:: m.Call(args=[m.Arg(m.SimpleString()), m.ZeroOrOne(), m.Arg(m.SimpleString())]) rr)rrrr'rrrrr ZeroOrOnesrobjcCs.t|tttttfr|}nt|}tt|S)a Matcher helper that inverts the match result of its child. You can also invert a matcher by using Python's bitwise invert operator on concrete matchers or any special matcher. For example, the following matches against any identifier that isn't ``True``/``False``:: m.DoesNotMatch(m.OneOf(m.Name("True"), m.Name("False"))) Or you could use the shorthand, like:: ~(m.Name("True") | m.Name("False")) This can be used in place of any concrete matcher as long as it is not the root matcher. Calling :func:`matches` directly on a :func:`DoesNotMatch` is redundant since you can invert the return of :func:`matches` using a bitwise not. )rFr+rrrArrr-)rinverserrrr`s'  r`rcCsttt||S)a Matcher helper that captures the matched node that matched against a matcher class, making it available in the dictionary returned by :func:`extract` or :func:`extractall`. For example, the following will match against any binary operation whose left and right operands are not integers, saving those expressions for later inspection. If used inside :func:`extract` or :func:`extractall`, the resulting dictionary will contain the keys ``left_operand`` and ``right_operand``:: m.BinaryOperation( left=m.SaveMatchedNode( m.DoesNotMatch(m.Integer()), "left_operand", ), right=m.SaveMatchedNode( m.DoesNotMatch(m.Integer()), "right_operand", ), ) This can be used in place of any concrete matcher as long as it is not the root matcher. Calling :func:`extract` directly on a :func:`SaveMatchedNode` is redundant since you already have the reference to the node itself. )rr-r)rrrrrSaveMatchedNodesrcCs>t|tr |jdkr dSt|trdSt|trt|jSdS)NrTF)rFrrrr_matches_zero_nodesrrrrrrs    r)frozenc@sPeZdZUeeeeeje ejffe d<eeeje e ejfe d<dS)_SequenceMatchesResultsequence_capture matched_nodesN) r!r"r#rr r&rlibcstCSTNoderrrrrrrrs  rnodesmatchersmetadata_lookupc CsV|s |s tidS|s%|r%tdd|Dr tdd|DdStddS|r.|s.tddS|d}|d}t|trMtt|dd|dd|j|St|trQt|tr|jdkrt |d|j |}|durt|ddt|j |jddg|dd|}|jdur|j }t|t sJti||j|g|RStt||dd|jdSt|t rG|jdkrt |d|j |}|durt|ddt |j |jddg|dd|}|jdur|j }t|t sJti||j|g|RStddSt |d|j |}|dur9t|dd||}|jdur9|j }t|t s+Jti||j|g|RStt||dd|jdStd t|d t|tr}t||j g|dd|}|jdurxt|j|j i|j|j StddSt|||}|durt|dd|dd|}|jdurti||j|StddS) Ncsrbr4)rr|rrrrf#rgz$_sequence_matches..cSsi|] }t|tr|jdqS)r)rFrrr|rrr &sz%_sequence_matches..rrrrz"Logic error unrecognized wildcard !)rallrFr_sequence_matchesrrrr_attribute_matchesrrrrrHrZrr_matches) rrrr2rattribute_captureresultmatched match_capturerrrrs                                  rr2c Cs(t|triSt|trt||j|duriSdSt|tr4t||j|}|dur2i||j|iSdSt|trB||r@iSdS|durN|durLiSdSt|t r[||krYiSdSt|t rh||urfiSdSt|t j j rtt tttjf|}t|tr|jD],}t|t j j rt|||}|jdur|jSqt|tr||riSdSqdSt|tri}|jD]!}t|t j j rt|||}|jdurdSi||j}qdS|St|t j j rt|tt tttttjtf||jSdStttttjf|tttttf||Sr4)rFrrArrrrrrr&rl collectionsabcrrrrrrr:rErrr>r+rrr)r2rrrr}r all_capturesrrrrs            '     rmetadatacCsDt|tr|jD]}t|||}|dur|SqdSt|tr=i}|jD]}t|||}|dur4dSi||}q%|St|trOt||j|durMiSdSt|trjt||j|}|durhi||j|iSdSt|t r||j |}|t ur{dS| |riSdSt|t r||j |}|t urdS||jkriSdStd)N Logic error!)rFr:rE_metadata_matchesr>rArrrrr_METADATA_MISSING_SENTINELrrrrH)r2rrmetadata_capturer actual_valuerrrrsR           rc CsNt|trt||j|duriSdSt|tr-t||j|}|dur+i||j|iSdSt|tr;||r9iSdSt|tt frHt |||S|j j |j j krRdSi}t |D]L}|jdkr`qX|jdkrt||j}t|trqqXt |||}|dur~dSi||}qXt||j}t||j}t|||} | durdSi|| }qX|S)N _metadatar)rFrA _node_matchesrrrrrrrrrr!rrrr) r2rr node_capturerfielddesiredractualrrrrrPsP             rcCst|trt|tr iSdSt|ttfr+|jD]}t|||}|dur(|SqdSt|trMi}|jD]}t|||}|durDdSi||}q5|St|||Sr4)rFrrAr:r5rErr>)r2rrrrrrrrs$       rcCsdtjdtjdtfdd}|S)Nproviderr2rcSst|jd)Nz3 is not resolved; did you forget a MetadataWrapper?) LookupErrorr!rr2rrr_fetchs z0_construct_metadata_fetcher_null.._fetch)rrrrr)rrrr _construct_metadata_fetcher_nullsrdependent_classcs"dtjdtjdtffdd }|S)Nrr2rcs||tSr4) get_metadatarrrrrrrCz5_construct_metadata_fetcher_dependent.._fetchrrrrrm)rrrrr%_construct_metadata_fetcher_dependentsrwrappercs(idtjdtjdtffdd }|S)Nrr2rcs:|vr ||<||t}t|tr|}|Sr4)resolvegetrrFr)rr2 node_metadatarrrrrs  z3_construct_metadata_fetcher_wrapper.._fetchr)rrrr r#_construct_metadata_fetcher_wrappers  r metadata_resolverr cCs^t|trdSt|ttttfrdS|durt}nt|tjr%t |}nt |}t |||S)a; Given an arbitrary node from a LibCST tree, and an arbitrary matcher, returns a dictionary of extracted children of the tree if the node matches the shape defined by the matcher. Note that the node can also be a :class:`~libcst.RemovalSentinel` or a :class:`~libcst.MaybeSentinel` in order to use extract directly on transform results and node attributes. In these cases, :func:`extract` will always return ``None``. If the node matches the shape defined by the matcher, the return will be a dictionary whose keys are defined by the :func:`SaveMatchedNode` name parameter, and the values will be the node or sequence that was present at that location in the shape defined by the matcher. In the case of multiple :func:`SaveMatchedNode` matches with the same name, parent nodes will take prioirity over child nodes, and nodes later in sequences will take priority over nodes earlier in sequences. The matcher can be any concrete matcher that subclasses from :class:`BaseMatcherNode`, or a :class:`OneOf`/:class:`AllOf` special matcher. It cannot be a :class:`MatchIfTrue` or a :func:`DoesNotMatch` matcher since these are redundant. It cannot be a :class:`AtLeastN` or :class:`AtMostN` matcher because these types are wildcards which can only be used inside sequences. N) rFrrrrrrrMetadataWrapperr rr)r2rr fetcherrrrextracts    rcCst|||dduS)a Given an arbitrary node from a LibCST tree, and an arbitrary matcher, returns ``True`` if the node matches the shape defined by the matcher. Note that the node can also be a :class:`~libcst.RemovalSentinel` or a :class:`~libcst.MaybeSentinel` in order to use matches directly on transform results and node attributes. In these cases, :func:`matches` will always return ``False``. The matcher can be any concrete matcher that subclasses from :class:`BaseMatcherNode`, or a :class:`OneOf`/:class:`AllOf` special matcher. It cannot be a :class:`MatchIfTrue` or a :func:`DoesNotMatch` matcher since these are redundant. It cannot be a :class:`AtLeastN` or :class:`AtMostN` matcher because these types are wildcards which can only be used inside sequences. r N)r)r2rr rrrmatches'src @sleZdZdeeeejee eeeejeffde e j ejge fddfddZdejdefdd ZdS) _FindAllVisitorrrrNcCs||_||_g|_g|_dSr4)rr found_nodesextracted_nodes)rrrrrrrR@s z_FindAllVisitor.__init__r2cCs4t||j|j}|dur|j||j|dSrW)rrrrrKr)rr2matchrrron_visitWs   z_FindAllVisitor.on_visit)r!r"r#rr+rrrrrArrrrmrRrlrrrrrr?s, rtreecCst|ttfr ggfSt|ttfrggfSt|tjr"|dur"|}|dur*t}nt|tjr5t |}nt |}t ||}| ||j |jfSr4)rFrrrrrrrrr rrvisitrr)rrr rfinderrrr_find_or_extract_all_s     rcCst|||d\}}|S)a: Given an arbitrary node from a LibCST tree and an arbitrary matcher, iterates over that node and all children returning a sequence of all child nodes that match the given matcher. Note that the tree can also be a :class:`~libcst.RemovalSentinel` or a :class:`~libcst.MaybeSentinel` in order to use findall directly on transform results and node attributes. In these cases, :func:`findall` will always return an empty sequence. Note also that instead of a LibCST tree, you can instead pass in a :class:`~libcst.metadata.MetadataWrapper`. This mirrors the fact that you can call ``visit`` on a :class:`~libcst.metadata.MetadataWrapper` in order to iterate over it with a transform. If you provide a wrapper for the tree and do not set the ``metadata_resolver`` parameter specifically, it will automatically be set to the wrapper for you. The matcher can be any concrete matcher that subclasses from :class:`BaseMatcherNode`, or a :class:`OneOf`/:class:`AllOf` special matcher. Unlike :func:`matches`, it can also be a :class:`MatchIfTrue` or :func:`DoesNotMatch` matcher, since we are traversing the tree looking for matches. It cannot be a :class:`AtLeastN` or :class:`AtMostN` matcher because these types are wildcards which can only be used inside sequences. r r)rrr r_rrrfindallsrcCst|||d\}}|S)a- Given an arbitrary node from a LibCST tree and an arbitrary matcher, iterates over that node and all children returning a sequence of dictionaries representing the saved and extracted children specified by :func:`SaveMatchedNode` for each match found in the tree. This is analogous to running a :func:`findall` over a tree, then running :func:`extract` with the same matcher over each of the returned nodes. Note that the tree can also be a :class:`~libcst.RemovalSentinel` or a :class:`~libcst.MaybeSentinel` in order to use extractall directly on transform results and node attributes. In these cases, :func:`extractall` will always return an empty sequence. Note also that instead of a LibCST tree, you can instead pass in a :class:`~libcst.metadata.MetadataWrapper`. This mirrors the fact that you can call ``visit`` on a :class:`~libcst.metadata.MetadataWrapper` in order to iterate over it with a transform. If you provide a wrapper for the tree and do not set the ``metadata_resolver`` parameter specifically, it will automatically be set to the wrapper for you. The matcher can be any concrete matcher that subclasses from :class:`BaseMatcherNode`, or a :class:`OneOf`/:class:`AllOf` special matcher. Unlike :func:`matches`, it can also be a :class:`MatchIfTrue` or :func:`DoesNotMatch` matcher, since we are traversing the tree looking for matches. It cannot be a :class:`AtLeastN` or :class:`AtMostN` matcher because these types are wildcards which can only be usedi inside sequences. r r)rrr r extractionsrrr extractalls rc@s6eZdZdeeeejee eeeejeffde e j ejge fdeeeeje ejeeeejeejffgeeeejfffddfddZdeejeejfdeejeejffd d Zd eeeejeejffdeeeejeejfffd d ZdejdejdeejeeffddZdS)_ReplaceTransformerrr replacementrNcsX||_||_|tr|_ntttfr fdd|_nfdd|_i|_dS)NcsSr4rr2rr!rrrsz._ReplaceTransformer.__init__..csSr4) deep_cloner"r#rrrs) rrinspect isfunctionr!rFrrnode_lut)rrrr!rr#rrRs  z_ReplaceTransformer.__init__node_or_sequencecs*t|trtfdd|DSj|S)Nc3s|]}j|VqdSr4)r')rer2rrrrfsz6_ReplaceTransformer._node_translate..)rFrrNr')rr(rrr_node_translates  z#_ReplaceTransformer._node_translate extractedcsfdd|DS)Ncsi|] \}}||qSr)r))rerrrrrr"sz=_ReplaceTransformer._extraction_translate..)items)rr*rrr_extraction_translaterYz)_ReplaceTransformer._extraction_translate original_node updated_nodecCsh||j|<t||j|j}|dur$z||}Wn ty#d}Ynw|dur2|j|=|||S|Sr4)r'rrrr,KeyErrorr!)rr-r.r*rrron_leave$s   z_ReplaceTransformer.on_leave)r!r"r#rr+rrrrrArrrrmrrr r&rrRr)r,r0rrrrr sh <  r r!cCst|ttfr |St|ttfr)t|tjr|St|tj r%|j St dt|tj r5|dur5|}|dur=t }nt|tj rHt |}nt|}t|||}||}t|tr`t d|S)al Given an arbitrary node from a LibCST tree and an arbitrary matcher, iterates over that node and all children and replaces each node that matches the supplied matcher with a supplied replacement. Note that the replacement can either be a valid node type, or a callable which takes the matched node and a dictionary of any extracted child values and returns a valid node type. If you provide a valid LibCST node type, :func:`replace` will replace every node that matches the supplied matcher with the replacement node. If you provide a callable, :func:`replace` will run :func:`extract` over all matched nodes and call the callable with both the node that should be replaced and the dictionary returned by :func:`extract`. Under all circumstances a new tree is returned. :func:`extract` should be viewed as a short-cut to writing a transform which also returns a new tree even when no changes are applied. Note that the tree can also be a :class:`~libcst.RemovalSentinel` or a :class:`~libcst.MaybeSentinel` in order to use replace directly on transform results and node attributes. In these cases, :func:`replace` will return the same :class:`~libcst.RemovalSentinel` or :class:`~libcst.MaybeSentinel`. Note also that instead of a LibCST tree, you can instead pass in a :class:`~libcst.metadata.MetadataWrapper`. This mirrors the fact that you can call ``visit`` on a :class:`~libcst.metadata.MetadataWrapper` in order to iterate over it with a transform. If you provide a wrapper for the tree and do not set the ``metadata_resolver`` parameter specifically, it will automatically be set to the wrapper for you. The matcher can be any concrete matcher that subclasses from :class:`BaseMatcherNode`, or a :class:`OneOf`/:class:`AllOf` special matcher. Unlike :func:`matches`, it can also be a :class:`MatchIfTrue` or :func:`DoesNotMatch` matcher, since we are traversing the tree looking for matches. It cannot be a :class:`AtLeastN` or :class:`AtMostN` matcher because these types are wildcards which can only be usedi inside sequences. rNz/Logic error, cannot get a FlattenSentinel here!)rFrrrrrrr$rrmodulerHrr rr rr)rrr!r rreplacernew_treerrrreplaceAs(4        r4)`collections.abcrr%rrr dataclassesrrenumrrtypingrrr r r r r rrrrrrrrrlibcst.metadatarrrrrlibcst._metadata_dependentrrr'r)r*r-r.r/r0rmrr1r+rDr5r:r>rArrr&rrrrrrr%rrrr`rrrlrrrr_AttributeValueT_AttributeMatcherTrrrrrMetadataDependentrrr rr CSTVisitorrrrrCSTTransformerr r4rrrrsD D      N4K7V"5RV L  M  :     l  8 S  /      5 7 ; ' %y