| Name | ast-predicates JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | A Python library for matching and querying Python AST nodes |
| upload_time | 2025-10-24 22:42:47 |
| maintainer | None |
| docs_url | None |
| author | Xavier Barbosa |
| requires_python | >=3.12 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# AST Predicates
A Python library for matching and querying Python AST nodes, inspired by [libcst's matcher API](https://libcst.readthedocs.io/en/latest/matchers_tutorial.html) 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](https://docs.python.org/3/library/ast.html) 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 `ast` module - no additional dependencies
- **Familiar API**: Inspired by libcst matchers
## Installation
```bash
pip install ast-predicates
```
## Quick Start
```python
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
```python
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
```python
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
```python
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](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.TypeOf) matcher
- [ ] Implement [DoesNotMatch](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.DoesNotMatch) matcher
- [ ] Implement [MatchRegex](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.MatchRegex) matcher
- [ ] Implement [ZeroOrMore](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.ZeroOrMore) matcher
- [ ] Implement [ZeroOrOne](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.ZeroOrOne) matcher
Raw data
{
"_id": null,
"home_page": null,
"name": "ast-predicates",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Xavier Barbosa",
"author_email": "Xavier Barbosa <clint.northwood@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/84/f8/e19ea889f6aaad233b21c670612b080d39bbdfea974574b813d7330298d7/ast_predicates-1.0.2.tar.gz",
"platform": null,
"description": "# AST Predicates\n\nA Python library for matching and querying Python AST nodes, inspired by [libcst's matcher API](https://libcst.readthedocs.io/en/latest/matchers_tutorial.html) but designed to work with Python's built-in `ast` module.\n\n## Overview\n\nAST Predicates provides a declarative way to search for and match patterns in [Python Abstract Syntax Trees](https://docs.python.org/3/library/ast.html) using the standard library's `ast` module. It offers a more ergonomic alternative to manual AST traversal and isinstance checks.\n\n## Features\n\n- **Declarative matching**: Define patterns using a clean, composable API\n- **Type-safe matchers**: Match AST node types with optional attribute constraints\n- **Flexible queries**: Support for wildcards, sequences, and logical operators\n- **Built on stdlib**: Works with Python's built-in `ast` module - no additional dependencies\n- **Familiar API**: Inspired by libcst matchers\n\n## Installation\n\n```bash\npip install ast-predicates\n```\n\n## Quick Start\n\n```python\nimport ast\nfrom ast_predicates import matches, Call, Name, Attribute\n\n# Parse some code\ntree = ast.parse(\"foo.bar(42)\")\n\n# Find function calls to methods named 'bar'\npattern = Call(func=Attribute(attr=\"bar\"))\n\n# Check if pattern matches\nif matches(tree.body[0].value, pattern):\n print(\"Found a call to a 'bar' method!\")\n```\n\n## Basic Usage\n\n### Matching Node Types\n\n```python\nfrom ast_predicates import matches, FunctionDef\n\n# Match any function definition\npattern = FunctionDef()\n\n# Match function with specific name\npattern = FunctionDef(name=\"my_function\")\n```\n\n### Wildcards and Sequences\n\n```python\nfrom pyast_matchers import DoNotCare, OneOf, AllOf\n\n# Match any value (wildcard)\npattern = Call(func=Name(id=DoNotCare()))\n\n# Match one of several possibilities\npattern = BinOp(op=OneOf(Add(), Sub()))\n\n# Match all conditions\npattern = AllOf(\n FunctionDef(name=\"process\"),\n FunctionDef(decorator_list=[...])\n)\n```\n\n### Finding Matches in a Tree\n\n```python\nfrom pyast_matchers import find_all\n\ntree = ast.parse(source_code)\npattern = Call(func=Name(id=\"print\"))\n\n# Find all matching nodes\nmatches = find_all(tree, pattern)\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Roadmap\n\n- [ ] Performance benchmarks\n- [ ] Implement [TypeOf](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.TypeOf) matcher\n- [ ] Implement [DoesNotMatch](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.DoesNotMatch) matcher\n- [ ] Implement [MatchRegex](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.MatchRegex) matcher\n- [ ] Implement [ZeroOrMore](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.ZeroOrMore) matcher\n- [ ] Implement [ZeroOrOne](https://libcst.readthedocs.io/en/latest/matchers.html#libcst.matchers.ZeroOrOne) matcher\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for matching and querying Python AST nodes",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/johnnoone/python-ast-predicates",
"Source": "https://github.com/johnnoone/python-ast-predicates",
"Tracker": "https://github.com/johnnoone/python-ast-predicates/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e4142c30020862f4fea752c3fecdbe375315471b1c27dda900631e828c03c2af",
"md5": "cc261f0ff16ee415484b815508aba912",
"sha256": "2e279cf61105db8fbba1b3eacab5be964cbd974e1d4e6f8d2d83b0eb5b1b2ca1"
},
"downloads": -1,
"filename": "ast_predicates-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc261f0ff16ee415484b815508aba912",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10789,
"upload_time": "2025-10-24T22:42:46",
"upload_time_iso_8601": "2025-10-24T22:42:46.107781Z",
"url": "https://files.pythonhosted.org/packages/e4/14/2c30020862f4fea752c3fecdbe375315471b1c27dda900631e828c03c2af/ast_predicates-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "84f8e19ea889f6aaad233b21c670612b080d39bbdfea974574b813d7330298d7",
"md5": "a5a02b33a689f41319a84ae6370bc02d",
"sha256": "c5390e2950336edb16f71d6c618a260648477fd268ddaa98bfd8b986babf78be"
},
"downloads": -1,
"filename": "ast_predicates-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a5a02b33a689f41319a84ae6370bc02d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 8853,
"upload_time": "2025-10-24T22:42:47",
"upload_time_iso_8601": "2025-10-24T22:42:47.161174Z",
"url": "https://files.pythonhosted.org/packages/84/f8/e19ea889f6aaad233b21c670612b080d39bbdfea974574b813d7330298d7/ast_predicates-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 22:42:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "johnnoone",
"github_project": "python-ast-predicates",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ast-predicates"
}
