0
# JSONPath RW
1

2
A robust and significantly extended implementation of JSONPath for Python, with a clear AST for metaprogramming. This library provides a full language implementation where JSONPath expressions are first-class objects that can be analyzed, transformed, parsed, printed, and extended. It enables powerful JSON data querying with comprehensive path tracking and extension capabilities.
3

4
## Package Information
5

6
- **Package Name**: jsonpath-rw
7
- **Language**: Python
8
- **Installation**: `pip install jsonpath-rw`
9
- **Dependencies**: ply, decorator, six
10

11
## Core Imports
12

13
```python
14
from jsonpath_rw import parse, __version__
15
```
16

17
For direct expression construction:
18

19
```python
20
from jsonpath_rw.jsonpath import Fields, Slice, Root, Index, DatumInContext
21
```
22

23
For advanced use cases:
24

25
```python
26
from jsonpath_rw.parser import JsonPathParser
27
from jsonpath_rw.lexer import JsonPathLexer, JsonPathLexerError
28
import jsonpath_rw.jsonpath as jsonpath
29
```
30

31
## Basic Usage
32

33
```python
34
from jsonpath_rw import parse
35

36
# Parse JSONPath expression
37
jsonpath_expr = parse('foo[*].baz')
38

39
# Find matches in data
40
data = {'foo': [{'baz': 1}, {'baz': 2}]}
41
matches = jsonpath_expr.find(data)
42

43
# Extract values
44
values = [match.value for match in matches]  # [1, 2]
45

46
# Get full paths
47
paths = [str(match.full_path) for match in matches]  # ['foo.[0].baz', 'foo.[1].baz']
48

49
# Update data
50
updated_data = jsonpath_expr.update(data, 999)
51
```
52

53
## Architecture
54

55
JSONPath RW uses an Abstract Syntax Tree (AST) approach with three main components:
56

57
- **JSONPath Classes**: Base abstract syntax tree nodes representing different path operations
58
- **DatumInContext**: Data wrapper that tracks values with their path context and parent relationships
59
- **Parser/Lexer**: PLY-based parsing system that converts string expressions to AST objects
60

61
This design enables metaprogramming capabilities, allowing JSONPath expressions to be constructed programmatically, analyzed, and transformed while maintaining complete path information for matched data.
62

63
## Capabilities
64

65
### JSONPath Parsing
66

67
Parse string JSONPath expressions into executable AST objects with comprehensive syntax support including field access, array operations, descendant queries, filtering, and union operations.
68

69
```python { .api }
70
def parse(string):
71
    """
72
    Parse a JSONPath string expression into a JSONPath object.
73
    
74
    Parameters:
75
    - string: str, JSONPath expression string
76
    
77
    Returns:
78
    JSONPath object that can be used to find/update data
79
    """
80
```
81

82
[JSONPath Parsing](./parsing.md)
83

84
### JSONPath Expression Classes
85

86
Core AST node classes representing different JSONPath operations including root access, field selection, array indexing, filtering, descendant queries, and path composition operations.
87

88
```python { .api }
89
class JSONPath:
90
    def find(self, data): ...
91
    def update(self, data, val): ...
92
    def child(self, child): ...
93

94
class Root(JSONPath): ...
95
class Fields(JSONPath): ...
96
class Index(JSONPath): ...
97
class Slice(JSONPath): ...
98
```
99

100
[JSONPath Expressions](./expressions.md)
101

102
### Data Context Management
103

104
Wrapper classes that maintain data values along with their path context, enabling full path tracking, parent relationships, and automatic ID field generation for matched data.
105

106
```python { .api }
107
class DatumInContext:
108
    def __init__(self, value, path=None, context=None): ...
109
    @property
110
    def full_path(self): ...
111
    def in_context(self, context, path): ...
112

113
class AutoIdForDatum(DatumInContext): ...
114
```
115

116
[Data Context](./context.md)
117

118
### Command Line Interface
119

120
Command-line tool for querying JSON files using JSONPath expressions, supporting both file input and stdin processing with glob pattern matching.
121

122
```python { .api }
123
def main(*argv):
124
    """
125
    Main CLI function for jsonpath.py command-line tool.
126
    
127
    Parameters:
128
    - argv: Command line arguments [expression, files...]
129
    """
130
```
131

132
[Command Line Interface](./cli.md)
133

134
## Global Configuration
135

136
```python { .api }
137
# Auto ID field configuration
138
jsonpath.auto_id_field = None  # Default: disabled
139
jsonpath.auto_id_field = 'id'  # Enable with 'id' field
140

141
# Package version
142
__version__ = '1.4.0'  # Version string constant
143
```
144

145
When enabled, auto ID field functionality automatically generates path-based identifiers for data elements, useful for tracking objects without explicit ID fields.