style.matchers
Usage
Composable AST matchers for style rules — import this module as M.
Every factory (kind, calls, under, …) and preset (imports, control_flow, …) is a module-level [Matcher][captain_hook.style.matchers.Matcher] builder or constant; author a rule by combining them with &, |, and ~.
Example
from captain_hook.style import matchers as M M.imports & M.child_of(M.control_flow) & ~M.under(M.type_checking)
Classes
| Name | Description |
|---|---|
| Matcher | A composable, immutable AST matcher: a node predicate that is also a tree selector. |
Matcher
A composable, immutable AST matcher: a node predicate that is also a tree selector.
Usage
Matcher()A Matcher wraps a single (node, parents) -> bool test. Node-local matchers (e.g. [calls][captain_hook.style.matchers.calls]) ignore parents; structural matchers (e.g. [under][captain_hook.style.matchers.under]) consult it. Compose with the boolean algebra & (intersection), | (union), and ~ (negation), refine with [where][captain_hook.style.matchers.Matcher.where], and finish with a terminal — [over][captain_hook.style.matchers.Matcher.over], [violations][captain_hook.style.matchers.Matcher.violations], or [exists][captain_hook.style.matchers.Matcher.exists].
The module-level vocabulary (M.imports, M.control_flow, …) and factories (M.kind, M.calls, …) are the whole surface — author a new rule by combining them, not by reaching for a framework helper.
Parameter Attributes
test: Predicatelabel: str = "matcher"structural: bool = False
Example
M.imports & M.child_of(M.control_flow) & ~M.under(M.type_checking)
Methods
| Name | Description |
|---|---|
| diff() |
Yield violations for matches in post whose key was absent from pre.
|
| exists() |
Return whether any node in tree matches.
|
| matches() |
Test a single node (node-local matchers only; raises for structural matchers).
|
| over() |
Yield every node in tree that matches.
|
| violations() | Yield a [Violation][captain_hook.style.Violation] for each match, located at its line. |
| where() |
Refine with a node-local one-off predicate — the escape hatch for bespoke conditions.
|
diff()
Yield violations for matches in post whose key was absent from pre.
Usage
diff(pre, post, key=ast.unparse, label=None)exists()
Return whether any node in tree matches.
Usage
exists(tree)matches()
Test a single node (node-local matchers only; raises for structural matchers).
Usage
matches(node)over()
Yield every node in tree that matches.
Usage
over(tree)violations()
Yield a [Violation][captain_hook.style.Violation] for each match, located at its line.
Usage
violations(tree, label=None)where()
Refine with a node-local one-off predicate — the escape hatch for bespoke conditions.
Usage
where(predicate)Functions
| Name | Description |
|---|---|
| annotated() | Match an annotation owner (annotated variable, parameter, or function return). |
| calls() |
Match a call to the bare-name function name (e.g. calls("zip")).
|
| child_of() |
Match a node whose immediate parent matches other.
|
| following() |
Match a body statement that follows the first sibling matching boundary.
|
| kind() |
Match any of the given AST node types — the primitive for a category not shipped.
|
| kwarg() | Match a call that passes the keyword argument name (combine with calls). |
| named() |
Match a class/function/assignment/parameter whose bound name matches pattern (re.search).
|
| ref() |
Match the bare name reference name (e.g. ref("Any") for x: Any).
|
| under() |
Match a node with any ancestor matching other (negate with ~ for “not inside”).
|
annotated()
Match an annotation owner (annotated variable, parameter, or function return).
Usage
annotated(inner=None)Excludes *args/**kwargs. When inner is given, the owner’s annotation expression must also match it (e.g. annotated(ref("Any"))).
calls()
Match a call to the bare-name function name (e.g. calls("zip")).
Usage
calls(name)child_of()
Match a node whose immediate parent matches other.
Usage
child_of(other)following()
Match a body statement that follows the first sibling matching boundary.
Usage
following(boundary)kind()
Match any of the given AST node types — the primitive for a category not shipped.
Usage
kind(*types, label=None)kwarg()
Usage
kwarg(name)named()
Match a class/function/assignment/parameter whose bound name matches pattern (re.search).
Usage
named(pattern)ref()
Match the bare name reference name (e.g. ref("Any") for x: Any).
Usage
ref(name)under()
Match a node with any ancestor matching other (negate with ~ for “not inside”).
Usage
under(other)