AST Predicates
A Python library for matching and querying Python AST nodes, inspired by libcst's matcher API but designed to work with Python's built-in ast module.
Overview
AST Predicates provides a declarative way to search for and match patterns in Python Abstract Syntax Trees using the standard library's ast module. It offers a more ergonomic alternative to manual AST traversal and isinstance checks.
Features
- Declarative matching: Define patterns using a clean, composable API
- Type-safe matchers: Match AST node types with optional attribute constraints
- Flexible queries: Support for wildcards, sequences, and logical operators
- Built on stdlib: Works with Python's built-in
astmodule - no additional dependencies - Familiar API: Inspired by libcst matchers
Installation
pip install ast-predicates
Quick Start
import ast
from ast_predicates import matches, Call, Name, Attribute
# Parse some code
tree = ast.parse("foo.bar(42)")
# Find function calls to methods named 'bar'
pattern = Call(func=Attribute(attr="bar"))
# Check if pattern matches
if matches(tree.body[0].value, pattern):
print("Found a call to a 'bar' method!")
Basic Usage
Matching Node Types
from ast_predicates import matches, FunctionDef
# Match any function definition
pattern = FunctionDef()
# Match function with specific name
pattern = FunctionDef(name="my_function")
Wildcards and Sequences
from pyast_matchers import DoNotCare, OneOf, AllOf
# Match any value (wildcard)
pattern = Call(func=Name(id=DoNotCare()))
# Match one of several possibilities
pattern = BinOp(op=OneOf(Add(), Sub()))
# Match all conditions
pattern = AllOf(
FunctionDef(name="process"),
FunctionDef(decorator_list=[...])
)
Finding Matches in a Tree
from pyast_matchers import find_all
tree = ast.parse(source_code)
pattern = Call(func=Name(id="print"))
# Find all matching nodes
matches = find_all(tree, pattern)
License
MIT License - see LICENSE file for details.
Roadmap
- Performance benchmarks
- Implement TypeOf matcher
- Implement DoesNotMatch matcher
- Implement MatchRegex matcher
- Implement ZeroOrMore matcher
- Implement ZeroOrOne matcher
Metadata
Release files for ast-predicates 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ast_predicates-1.0.2.tar.gz | 8.9 kB | Without provenance | Details for ast_predicates-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ast_predicates-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for ast_predicates-1.0.2-py3-none-any.whl |
Total release size: 19.6 kB
Release files / ast_predicates-1.0.2.tar.gz
| Download URL | ast_predicates-1.0.2.tar.gz |
|---|---|
| Size | 8.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c5390e2950336edb16f71d6c618a260648477fd268ddaa98bfd8b986babf78be
|
|
BLAKE2b-256 checksum How to use checksums |
84f8e19ea889f6aaad233b21c670612b080d39bbdfea974574b813d7330298d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.22
|
Release files / ast_predicates-1.0.2-py3-none-any.whl
| Download URL | ast_predicates-1.0.2-py3-none-any.whl |
|---|---|
| Size | 10.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e279cf61105db8fbba1b3eacab5be964cbd974e1d4e6f8d2d83b0eb5b1b2ca1
|
|
BLAKE2b-256 checksum How to use checksums |
e4142c30020862f4fea752c3fecdbe375315471b1c27dda900631e828c03c2af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.22
|
Security for ast-predicates 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.