ast-search-python 1.0.0 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +117 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# ast-search-python
|
|
2
|
+
|
|
3
|
+
Python language plugin for [ast-search](../../README.md). Adds `.py` / `.pyw` file support using [tree-sitter](https://tree-sitter.github.io/tree-sitter/) S-expression queries.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [Installation](#installation)
|
|
8
|
+
- [Usage](#usage)
|
|
9
|
+
- [Example](#example)
|
|
10
|
+
- [Query syntax](#query-syntax)
|
|
11
|
+
- [Shorthands](#shorthands)
|
|
12
|
+
- [Supported file types](#supported-file-types)
|
|
13
|
+
- [Plugin API](#plugin-api)
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install -g ast-search
|
|
19
|
+
npm install -g ast-search-python
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Usage
|
|
23
|
+
|
|
24
|
+
Pass `--plugin ast-search-python` to enable Python file support:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
ast-search <query> --plugin ast-search-python [--dir <path>] [--format <fmt>] [--lang python]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
| Argument | Description | Default |
|
|
31
|
+
| -------------- | -------------------------------------------------------------- | ----------- |
|
|
32
|
+
| `<query>` | Shorthand or tree-sitter S-expression (see Query Syntax below) | required |
|
|
33
|
+
| `-d, --dir` | Root directory to search | current dir |
|
|
34
|
+
| `-f, --format` | Output format: `text`, `json`, or `files` | `text` |
|
|
35
|
+
| `-l, --lang` | Restrict search to `python` only (useful in mixed-language repos) | all languages |
|
|
36
|
+
| `-p, --plugin` | `ast-search-python` | required |
|
|
37
|
+
|
|
38
|
+
## Example
|
|
39
|
+
|
|
40
|
+
Find all functions that `raise` an exception:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
ast-search '(function_definition body: (block (raise_statement) @r) @b) @fn' --plugin ast-search-python
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Using the shorthand:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
ast-search 'raise' --plugin ast-search-python
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Query syntax
|
|
53
|
+
|
|
54
|
+
Python queries use tree-sitter S-expression syntax. A few examples:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# Find all function definitions (shorthand)
|
|
58
|
+
ast-search 'fn' --plugin ast-search-python
|
|
59
|
+
|
|
60
|
+
# Find all class definitions (raw S-expression)
|
|
61
|
+
ast-search '(class_definition) @cls' --plugin ast-search-python
|
|
62
|
+
|
|
63
|
+
# Find all calls to a specific function by name
|
|
64
|
+
ast-search '(call function: (identifier) @n (#eq? @n "my_func")) @c' --plugin ast-search-python
|
|
65
|
+
|
|
66
|
+
# Restrict to only Python files in a mixed-language repo
|
|
67
|
+
ast-search 'fn' --lang python --plugin ast-search-python
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Raw S-expression queries must include at least one `@capture_name` — tree-sitter's `captures()` requires it to return results. Shorthands include `@_` automatically.
|
|
71
|
+
|
|
72
|
+
### Shorthands
|
|
73
|
+
|
|
74
|
+
| Shorthand | Expands to |
|
|
75
|
+
| ----------- | ----------------------------------- |
|
|
76
|
+
| `fn` | `(function_definition) @_` |
|
|
77
|
+
| `call` | `(call) @_` |
|
|
78
|
+
| `class` | `(class_definition) @_` |
|
|
79
|
+
| `assign` | `(assignment) @_` |
|
|
80
|
+
| `return` | `(return_statement) @_` |
|
|
81
|
+
| `await` | `(await) @_` |
|
|
82
|
+
| `yield` | `(yield) @_` |
|
|
83
|
+
| `import` | `(import_statement) @_` |
|
|
84
|
+
| `from` | `(import_from_statement) @_` |
|
|
85
|
+
| `if` | `(if_statement) @_` |
|
|
86
|
+
| `for` | `(for_statement) @_` |
|
|
87
|
+
| `while` | `(while_statement) @_` |
|
|
88
|
+
| `raise` | `(raise_statement) @_` |
|
|
89
|
+
| `with` | `(with_statement) @_` |
|
|
90
|
+
| `lambda` | `(lambda) @_` |
|
|
91
|
+
| `decorator` | `(decorator) @_` |
|
|
92
|
+
| `augassign` | `(augmented_assignment) @_` |
|
|
93
|
+
| `comp` | `(list_comprehension) @_` |
|
|
94
|
+
| `dictcomp` | `(dictionary_comprehension) @_` |
|
|
95
|
+
| `setcomp` | `(set_comprehension) @_` |
|
|
96
|
+
| `genexp` | `(generator_expression) @_` |
|
|
97
|
+
| `assert` | `(assert_statement) @_` |
|
|
98
|
+
| `delete` | `(delete_statement) @_` |
|
|
99
|
+
| `global` | `(global_statement) @_` |
|
|
100
|
+
| `nonlocal` | `(nonlocal_statement) @_` |
|
|
101
|
+
| `decorated` | `(decorated_definition) @_` |
|
|
102
|
+
|
|
103
|
+
> **Note:** In tree-sitter-python 0.21+, `async def` functions are typed as `function_definition` (no separate `async_function_definition` node). The `fn` shorthand matches both sync and async functions. To match only async functions, use a predicate query.
|
|
104
|
+
|
|
105
|
+
## Supported file types
|
|
106
|
+
|
|
107
|
+
`.py` `.pyw`
|
|
108
|
+
|
|
109
|
+
## Plugin API
|
|
110
|
+
|
|
111
|
+
This package implements the `LanguageBackend` interface from `ast-search/plugin`. It registers the `python` language backend automatically when loaded via `--plugin ast-search-python`, or programmatically:
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
import { defaultRegistry } from 'ast-search/plugin';
|
|
115
|
+
const { register } = await import('ast-search-python');
|
|
116
|
+
register(defaultRegistry);
|
|
117
|
+
```
|