Matchers

Matchers are provided as a way of asking whether a particular LibCST node and its children match a particular shape. It is possible to write a visitor that tracks attributes using visit_<Node> methods. It is also possible to implement manual instance checking and traversal of a node’s children. However, both are cumbersome to write and hard to understand. Matchers offer a more concise way of defining what attributes on a node matter when matching against predefined patterns.

To accomplish this, a matcher has been created which corresponds to each LibCST node documented in Nodes. Matchers default each of their attributes to the special sentinel matcher DoNotCare(). When constructing a matcher, you can initialize the node with only the values of attributes that you are concerned with, leaving the rest of the attributes set to DoNotCare() in order to skip comparing against them.

Matcher APIs

Functions

Matchers can be used either by calling matches() or findall() directly, or by using various decorators to selectively control when LibCST calls visitor functions.

libcst.matchers.matches(node: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode, *, metadata_resolver: MetadataDependent | MetadataWrapper | None = None) → bool

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 RemovalSentinel or a MaybeSentinel in order to use matches directly on transform results and node attributes. In these cases, matches() will always return False.

The matcher can be any concrete matcher that subclasses from BaseMatcherNode, or a OneOf/AllOf special matcher. It cannot be a MatchIfTrue or a DoesNotMatch() matcher since these are redundant. It cannot be a AtLeastN or AtMostN matcher because these types are wildcards which can only be used inside sequences.

libcst.matchers.findall(tree: MaybeSentinel | RemovalSentinel | CSTNode | MetadataWrapper, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | _BaseMetadataMatcher, *, metadata_resolver: MetadataDependent | MetadataWrapper | None = None) → Sequence[CSTNode]

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 RemovalSentinel or a MaybeSentinel in order to use findall directly on transform results and node attributes. In these cases, findall() will always return an empty sequence. Note also that instead of a LibCST tree, you can instead pass in a MetadataWrapper. This mirrors the fact that you can call visit on a 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 BaseMatcherNode, or a OneOf/AllOf special matcher. Unlike matches(), it can also be a MatchIfTrue or DoesNotMatch() matcher, since we are traversing the tree looking for matches. It cannot be a AtLeastN or AtMostN matcher because these types are wildcards which can only be used inside sequences.

libcst.matchers.extract(node: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode, *, metadata_resolver: MetadataDependent | MetadataWrapper | None = None) → Dict[str, CSTNode | Sequence[CSTNode]] | None

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 RemovalSentinel or a MaybeSentinel in order to use extract directly on transform results and node attributes. In these cases, 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 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 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 BaseMatcherNode, or a OneOf/AllOf special matcher. It cannot be a MatchIfTrue or a DoesNotMatch() matcher since these are redundant. It cannot be a AtLeastN or AtMostN matcher because these types are wildcards which can only be used inside sequences.

libcst.matchers.extractall(tree: MaybeSentinel | RemovalSentinel | CSTNode | MetadataWrapper, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | _BaseMetadataMatcher, *, metadata_resolver: MetadataDependent | MetadataWrapper | None = None) → Sequence[Dict[str, CSTNode | Sequence[CSTNode]]]

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 SaveMatchedNode() for each match found in the tree. This is analogous to running a findall() over a tree, then running extract() with the same matcher over each of the returned nodes. Note that the tree can also be a RemovalSentinel or a MaybeSentinel in order to use extractall directly on transform results and node attributes. In these cases, extractall() will always return an empty sequence. Note also that instead of a LibCST tree, you can instead pass in a MetadataWrapper. This mirrors the fact that you can call visit on a 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 BaseMatcherNode, or a OneOf/AllOf special matcher. Unlike matches(), it can also be a MatchIfTrue or DoesNotMatch() matcher, since we are traversing the tree looking for matches. It cannot be a AtLeastN or AtMostN matcher because these types are wildcards which can only be usedi inside sequences.

libcst.matchers.replace(tree: MaybeSentinel | RemovalSentinel | CSTNode | MetadataWrapper, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | _BaseMetadataMatcher, replacement: MaybeSentinel | RemovalSentinel | CSTNode | Callable[[CSTNode, Dict[str, CSTNode | Sequence[CSTNode]]], MaybeSentinel | RemovalSentinel | CSTNode], *, metadata_resolver: MetadataDependent | MetadataWrapper | None = None) → MaybeSentinel | RemovalSentinel | CSTNode

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, replace() will replace every node that matches the supplied matcher with the replacement node. If you provide a callable, replace() will run extract() over all matched nodes and call the callable with both the node that should be replaced and the dictionary returned by extract(). Under all circumstances a new tree is returned. 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 RemovalSentinel or a MaybeSentinel in order to use replace directly on transform results and node attributes. In these cases, replace() will return the same RemovalSentinel or MaybeSentinel. Note also that instead of a LibCST tree, you can instead pass in a MetadataWrapper. This mirrors the fact that you can call visit on a 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 BaseMatcherNode, or a OneOf/AllOf special matcher. Unlike matches(), it can also be a MatchIfTrue or DoesNotMatch() matcher, since we are traversing the tree looking for matches. It cannot be a AtLeastN or AtMostN matcher because these types are wildcards which can only be usedi inside sequences.

Decorators

The following decorators can be placed onto a method in a visitor or transformer in order to convert it into a visitor which is called when the provided matcher is true.

libcst.matchers.visit(matcher: BaseMatcherNode) → Callable[[_CSTVisitFuncT], _CSTVisitFuncT]

A decorator that allows a method inside a MatcherDecoratableTransformer or a MatcherDecoratableVisitor visitor to be called when visiting a node that matches the provided matcher. Note that you can use this in combination with call_if_inside() and call_if_not_inside() decorators. Unlike explicit visit_<Node> and leave_<Node> methods, functions decorated with this decorator cannot stop child traversal by returning False. Decorated visit functions should always have a return annotation of None.

There is no restriction on the number of visit decorators allowed on a method. There is also no restriction on the number of methods that may be decorated with the same matcher. When multiple visit decorators are found on the same method, they act as a simple or, and the method will be called when any one of the contained matches is True.

libcst.matchers.leave(matcher: BaseMatcherNode) → Callable[[_CSTVisitFuncT], _CSTVisitFuncT]

A decorator that allows a method inside a MatcherDecoratableTransformer or a MatcherDecoratableVisitor visitor to be called when leaving a node that matches the provided matcher. Note that you can use this in combination with call_if_inside() and call_if_not_inside() decorators.

There is no restriction on the number of leave decorators allowed on a method. There is also no restriction on the number of methods that may be decorated with the same matcher. When multiple leave decorators are found on the same method, they act as a simple or, and the method will be called when any one of the contained matches is True.

The following decorators can be placed onto any existing visit_<Node> or leave_<Node> visitor, as well as any visitor created using either visit() or leave(). They control whether the visitor itself gets called or skipped by LibCST when traversing a tree. Note that when a visitor function is skipped, its children will still be visited based on the rules set forth in Visitors. Namely, if you have a separate visit_<Node> visitor that returns False for a particular node, we will not traverse to its children.

libcst.matchers.call_if_inside(matcher: BaseMatcherNode) → Callable[[_CSTVisitFuncT], _CSTVisitFuncT]

A decorator for visit and leave methods inside a MatcherDecoratableTransformer or a MatcherDecoratableVisitor. A method that is decorated with this decorator will only be called if it or one of its parents matches the supplied matcher. Use this to selectively gate visit and leave methods to be called only when inside of another relevant node. Note that this works for both node and attribute methods, so you can decorate a visit_<Node> or a visit_<Node>_<Attr> method.

libcst.matchers.call_if_not_inside(matcher: BaseMatcherNode) → Callable[[_CSTVisitFuncT], _CSTVisitFuncT]

A decorator for visit and leave methods inside a MatcherDecoratableTransformer or a MatcherDecoratableVisitor. A method that is decorated with this decorator will only be called if it or one of its parents does not match the supplied matcher. Use this to selectively gate visit and leave methods to be called only when outside of another relevant node. Note that this works for both node and attribute methods, so you can decorate a visit_<Node> or a visit_<Node>_<Attr> method.

When using matcher decorators, your visitors must subclass from MatcherDecoratableVisitor instead of libcst.CSTVisitor, and from MatcherDecoratableTransformer instead of libcst.CSTTransformer. This is so that visitors and transformers not making use of matcher decorators do not pay the extra cost of their implementation. Note that if you do not subclass from MatcherDecoratableVisitor or MatcherDecoratableTransformer, you can still use the matches() function.

Both of these classes are strict subclasses of their corresponding LibCST base class, so they can be used anywhere that expects a LibCST base class. See Visitors for more information.

class libcst.matchers.MatcherDecoratableVisitor

This class provides all of the features of a libcst.CSTVisitor, and additionally supports various decorators to control when methods get called when traversing a tree. Use this instead of a libcst.CSTVisitor if you wish to do more powerful decorator-based visiting.

on_visit(node: CSTNode) → bool

Called every time a node is visited, before we’ve visited its children.

Returns True if children should be visited, and returns False otherwise.

on_leave(original_node: CSTNode) → None

Called every time we leave a node, after we’ve visited its children. If the on_visit() function for this node returns False, this function will still be called on that node.

on_visit_attribute(node: CSTNode, attribute: str) → None

Called before a node’s child attribute is visited and after we have called on_visit() on the node. A node’s child attributes are visited in the order that they appear in source that this node originates from.

on_leave_attribute(original_node: CSTNode, attribute: str) → None

Called after a node’s child attribute is visited and before we have called on_leave() on the node.

matches(node: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode) → bool

A convenience method to call matches() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for matches() as it is identical to this function.

findall(tree: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | MatchMetadata | MatchMetadataIfTrue) → Sequence[CSTNode]

A convenience method to call findall() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for findall() as it is identical to this function.

extract(node: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode) → Dict[str, CSTNode | Sequence[CSTNode]] | None

A convenience method to call extract() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for extract() as it is identical to this function.

extractall(tree: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | MatchMetadata | MatchMetadataIfTrue) → Sequence[Dict[str, CSTNode | Sequence[CSTNode]]]

A convenience method to call extractall() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for extractall() as it is identical to this function.

replace(tree: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | MatchMetadata | MatchMetadataIfTrue, replacement: MaybeSentinel | RemovalSentinel | CSTNode | Callable[[CSTNode, Dict[str, CSTNode | Sequence[CSTNode]]], MaybeSentinel | RemovalSentinel | CSTNode]) → MaybeSentinel | RemovalSentinel | CSTNode

A convenience method to call replace() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for replace() as it is identical to this function.

class libcst.matchers.MatcherDecoratableTransformer

This class provides all of the features of a libcst.CSTTransformer, and additionally supports various decorators to control when methods get called when traversing a tree. Use this instead of a libcst.CSTTransformer if you wish to do more powerful decorator-based visiting.

on_visit(node: CSTNode) → bool

Called every time a node is visited, before we’ve visited its children.

Returns True if children should be visited, and returns False otherwise.

on_leave(original_node: CSTNodeT, updated_node: CSTNodeT) → CSTNodeT | RemovalSentinel

Called every time we leave a node, after we’ve visited its children. If the on_visit() function for this node returns False, this function will still be called on that node.

original_node is guaranteed to be the same node as is passed to on_visit(), so it is safe to do state-based checks using the is operator. Modifications should always be performed on the updated_node so as to not overwrite changes made by child visits.

Returning RemovalSentinel.REMOVE indicates that the node should be removed from its parent. This is not always possible, and may raise an exception if this node is required. As a convenience, you can use RemoveFromParent() as an alias to RemovalSentinel.REMOVE.

on_visit_attribute(node: CSTNode, attribute: str) → None

Called before a node’s child attribute is visited and after we have called on_visit() on the node. A node’s child attributes are visited in the order that they appear in source that this node originates from.

on_leave_attribute(original_node: CSTNode, attribute: str) → None

Called after a node’s child attribute is visited and before we have called on_leave() on the node.

Unlike on_leave(), this function does not allow modifications to the tree and is provided solely for state management.

matches(node: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode) → bool

A convenience method to call matches() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for matches() as it is identical to this function.

findall(tree: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | MatchMetadata | MatchMetadataIfTrue) → Sequence[CSTNode]

A convenience method to call findall() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for findall() as it is identical to this function.

extract(node: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode) → Dict[str, CSTNode | Sequence[CSTNode]] | None

A convenience method to call extract() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for extract() as it is identical to this function.

extractall(tree: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | MatchMetadata | MatchMetadataIfTrue) → Sequence[Dict[str, CSTNode | Sequence[CSTNode]]]

A convenience method to call extractall() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for extractall() as it is identical to this function.

replace(tree: MaybeSentinel | RemovalSentinel | CSTNode, matcher: BaseMatcherNode | MatchIfTrue[CSTNode] | MatchMetadata | MatchMetadataIfTrue, replacement: MaybeSentinel | RemovalSentinel | CSTNode | Callable[[CSTNode, Dict[str, CSTNode | Sequence[CSTNode]]], MaybeSentinel | RemovalSentinel | CSTNode]) → MaybeSentinel | RemovalSentinel | CSTNode

A convenience method to call replace() without requiring an explicit parameter for metadata. Since our instance is an instance of libcst.MetadataDependent, we work as a metadata resolver. Please see documentation for replace() as it is identical to this function.

Traversal Order

Visit and leave functions created using visit() or leave() follow the traversal order rules laid out in LibCST’s visitor Traversal Order with one additional rule. Any visit function created using the visit() decorator will be called before a visit_<Node> function if it is defined for your visitor. The order in which various visit functions which are created with visit() are called is indeterminate, but all such functions will be called before calling the visit_<Node> method. Similarly, any leave function created using the leave() decorator will be called after a leave_<Node> function if it is defined for your visitor. The order in which various leave functions which are created with leave() are called is indeterminate, but all such functions will be called after calling the visit_<Node> function if it is defined for your visitor.

This has a few implications. The first is that if you return False from a visit_<Node> method, we are guaranteed to call your decorated visit functions as well. Second, when modifying a node in both leave_<Node> and a visitor created with leave(), the original_node will be unchanged for both and the updated_node available to the decorated leave method will be the node that is returned by the leave_<Node> method. Chaining modifications across multiple leave functions is supported, but must be done with care.

Matcher Types

Concrete Matchers

For each node found in Nodes, a corresponding concrete matcher has been generated. Each matcher has attributes identical to its LibCST node counterpart. For example, libcst.Expr includes the value and semicolon attributes, and therefore libcst.matchers.Expr similarly includes the same attributes. Just as libcst.Expr’s value is typed as taking a libcst.BaseExpression, libcst.matchers.Expr’s value is typed as taking a libcst.matchers.BaseExpression. For every node that exists in LibCST, both concrete and abstract, a corresponding matcher has been defined.

There are a few special cases to the rules laid out above. For starters, matchers don’t support evaluating MaybeSentinel. There is no way to specify that you wish to match against a MaybeSentinel except with the DoNotCare() matcher. This tends not to be an issue in practice because MaybeSentinel is only found on syntax nodes.

While there are base classes such as libcst.matchers.BaseExpression, you cannot match directly on them. They are provided for typing purposes only in order to exactly match the types on LibCST node attributes. If you need to match on all concrete subclasses of a base class, we recommend using the special matcher OneOf.

class libcst.matchers.BaseMatcherNode

Base class that all concrete matchers subclass from. OneOf and 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 matches() with a concrete matcher, or a OneOf with several concrete matchers as options.

Special Matchers

Special matchers are matchers that don’t have a corresponding LibCST node. Concrete matchers only match against their corresponding LibCST node, limiting their use under certain circumstances. Special matchers fill in the gap by allowing higher-level logic constructs such as inversion. You can use any special matcher in place of a concrete matcher when specifying matcher attributes. Additionally, you can also use the AllOf and OneOf special matchers in place of a concrete matcher when calling matches() or using decorators.

class libcst.matchers.OneOf

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 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")

property options: Sequence[_MatcherT]

The normalized list of options that we can choose from to satisfy a OneOf matcher. If any of these matchers are true, the OneOf matcher will also be considered a match.

class libcst.matchers.AllOf

Matcher that matches all of its options. Useful when you want to match against a concrete matcher and a MatchIfTrue at the same time. Also useful when you want to match against a concrete matcher and a DoesNotMatch() at the same time. You can also construct a 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 OneOf, this can be used in place of any concrete matcher.

Real-world cases where 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 Name node as well as 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 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=())

property options: Sequence[_MatcherT]

The normalized list of options that we can choose from to satisfy a AllOf matcher. If all of these matchers are true, the AllOf matcher will also be considered a match.

class libcst.matchers.TypeOf

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 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())

property initalized: bool

property options: Iterator[BaseMatcherNode]

libcst.matchers.DoesNotMatch(obj: _OtherNodeT) → _OtherNodeT

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 matches() directly on a DoesNotMatch() is redundant since you can invert the return of matches() using a bitwise not.

class libcst.matchers.MatchIfTrue

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 MatchRegex() matcher build on top of 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 matches() directly on a MatchIfTrue is redundant since you can just call the child callable directly with the node you are passing to matches().

property func: Callable[[_MatchIfTrueT], bool]

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.

libcst.matchers.MatchRegex(regex: str | Pattern[str]) → MatchIfTrue[str]

Used as a convenience wrapper to 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.

class libcst.matchers.MatchMetadata

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 MatchMetadata. If the metadata provider is unresolved, a LookupError exeption will be raised and ask you to provide a MetadataWrapper. If the metadata value does not exist for a particular node, 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 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 matches() directly on a MatchMetadata is redundant since you can just check the metadata on the root node that you are passing to matches().

property key: Type[BaseMetadataProvider[object]]

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.

property value: object

The value that we will compare against the return from the metadata provider for each node when determining a match.

class libcst.matchers.MatchMetadataIfTrue

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 LookupError exeption will be raised and ask you to provide a MetadataWrapper. If the metadata value does not exist for a particular node, 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 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 matches() directly on a MatchMetadataIfTrue is redundant since you can just check the metadata on the root node that you are passing to matches().

property key: Type[BaseMetadataProvider[object]]

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.

property func: Callable[[object], bool]

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.

libcst.matchers.SaveMatchedNode(matcher: _OtherNodeT, name: str) → _OtherNodeT

Matcher helper that captures the matched node that matched against a matcher class, making it available in the dictionary returned by extract() or 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 extract() or 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 extract() directly on a SaveMatchedNode() is redundant since you already have the reference to the node itself.

libcst.matchers.DoNotCare() → DoNotCareSentinel

Used when you want to match exactly one node, but you do not care what node it is. Useful inside sequences such as a libcst.matchers.Call’s args attribte. You do not need to use this for concrete matcher attributes since 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()])

Sequence Wildcard Matchers

Sequence wildcard matchers are matchers that only get used when constructing a sequence to match against. Not all LibCST nodes have attributes which are sequences, but for those that do, sequence wildcard matchers offer a great degree of flexibility. Unlike all other matcher types, these allow you to match against more than one LibCST node, much like wildcards in regular expressions do.

LibCST does not implicitly match on partial sequences for you. So, when matching against a sequence you will need to provide a complete pattern. This often means using helpers such as ZeroOrMore() as the first and last element of your sequence. Think of it as the difference between Python’s re.match and re.fullmatch functions. LibCST matchers behave like the latter so that it is possible to specify sequences which must start with, end with or be exactly equal to some pattern.

class libcst.matchers.AtLeastN

Matcher that matches n or more LibCST nodes in a row in a sequence. AtLeastN defaults to matching against the DoNotCare() matcher, so if you do not specify a matcher as a child, AtLeastN will match only by count. If you do specify a matcher as a child, 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())])

property n: int

The number of nodes in a row that must match 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.

property matcher: _MatcherT | DoNotCareSentinel

The matcher which each node in a sequence needs to match.

libcst.matchers.ZeroOrMore(matcher: _MatcherT | DoNotCareSentinel = DoNotCareSentinel.DEFAULT) → AtLeastN[_MatcherT | DoNotCareSentinel]

Used as a convenience wrapper to 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 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()])

class libcst.matchers.AtMostN

Matcher that matches n or fewer LibCST nodes in a row in a sequence. AtMostN defaults to matching against the DoNotCare() matcher, so if you do not specify a matcher as a child, AtMostN will match only by count. If you do specify a matcher as a child, 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())])

property n: int

The number of nodes in a row that must match 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.

property matcher: _MatcherT | DoNotCareSentinel

The matcher which each node in a sequence needs to match.

libcst.matchers.ZeroOrOne(matcher: _MatcherT | DoNotCareSentinel = DoNotCareSentinel.DEFAULT) → AtMostN[_MatcherT | DoNotCareSentinel]

Used as a convenience wrapper to 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())])