0
# JSONPath-NG
1

2
A final implementation of JSONPath for Python that aims to be standard compliant, including arithmetic and binary comparison operators and providing clear AST for metaprogramming. JSONPath-NG provides a robust and significantly extended implementation of JSONPath for Python, treating JSONPath expressions as first-class objects that are easy to analyze, transform, parse, print, and extend.
3

4
## Package Information
5

6
- **Package Name**: jsonpath-ng
7
- **Language**: Python
8
- **Installation**: `pip install jsonpath-ng`
9

10
## Core Imports
11

12
Basic JSONPath functionality:
13

14
```python
15
from jsonpath_ng import jsonpath, parse
16
```
17

18
Extended functionality with arithmetic and filtering:
19

20
```python
21
from jsonpath_ng.ext import parse
22
```
23

24
Programmatic JSONPath construction:
25

26
```python
27
from jsonpath_ng.jsonpath import (
28
    Root, This, Fields, Index, Slice, Child, 
29
    Where, WhereNot, Descendants, Union, Parent
30
)
31
```
32

33
## Basic Usage
34

35
```python
36
from jsonpath_ng import parse
37

38
# Parse a JSONPath expression
39
jsonpath_expr = parse('foo[*].baz')
40

41
# Sample data
42
data = {'foo': [{'baz': 1}, {'baz': 2}]}
43

44
# Find matching values
45
matches = jsonpath_expr.find(data)
46
values = [match.value for match in matches]  # [1, 2]
47

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

51
# Update matching values
52
updated_data = jsonpath_expr.update(data, 42)
53
# Result: {'foo': [{'baz': 42}, {'baz': 42}]}
54

55
# Filter out matching values
56
filtered_data = jsonpath_expr.filter(lambda x: x == 2, data)
57
# Result: {'foo': [{'baz': 1}, {}]}
58
```
59

60
## Architecture
61

62
JSONPath-NG is built around a comprehensive AST (Abstract Syntax Tree) model:
63

64
- **JSONPath**: Base class for all JSONPath expressions with core operations (find, update, filter)
65
- **DatumInContext**: Wrapper preserving path information and context for located data
66
- **Expression Classes**: Each JSONPath syntax element has a corresponding class (Root, This, Fields, etc.)
67
- **Parser**: Converts string expressions into JSONPath AST objects
68
- **Extensions**: Additional functionality for arithmetic, filtering, and string operations
69

70
This design enables programmatic JSONPath construction, AST manipulation, and extensible functionality while maintaining full compatibility with standard JSONPath syntax.
71

72
## Capabilities
73

74
### Core Parsing and Expression Building
75

76
Parse JSONPath expressions from strings or build them programmatically using the AST classes. Supports standard JSONPath syntax with extensions for arithmetic and comparison operations.
77

78
```python { .api }
79
def parse(string: str) -> JSONPath: ...
80
```
81

82
```python { .api }
83
class Root(JSONPath):
84
    def find(self, data) -> List[DatumInContext]: ...
85
    def update(self, data, val): ...
86
    def filter(self, fn, data): ...
87

88
class This(JSONPath):
89
    def find(self, datum) -> List[DatumInContext]: ...
90
    def update(self, data, val): ...
91
    def filter(self, fn, data): ...
92

93
class Fields(JSONPath):
94
    def __init__(self, *fields: str): ...
95
    def find(self, datum) -> List[DatumInContext]: ...
96
    def update(self, data, val): ...
97
    def filter(self, fn, data): ...
98
```
99

100
[Core Parsing and Expression Building](./core-parsing.md)
101

102
### Path Operations
103

104
Core operations for finding, updating, and filtering data using JSONPath expressions. Includes context preservation and full path tracking.
105

106
```python { .api }
107
class JSONPath:
108
    def find(self, data) -> List[DatumInContext]: ...
109
    def find_or_create(self, data) -> List[DatumInContext]: ...
110
    def update(self, data, val): ...
111
    def update_or_create(self, data, val): ...
112
    def filter(self, fn, data): ...
113

114
class DatumInContext:
115
    def __init__(self, value, path=None, context=None): ...
116
    @property
117
    def full_path(self) -> JSONPath: ...
118
    @property
119
    def id_pseudopath(self) -> JSONPath: ...
120
```
121

122
[Path Operations](./path-operations.md)
123

124
### Extensions
125

126
Extended JSONPath functionality including arithmetic operations, advanced filtering with comparison operators, string manipulation functions, and iterable operations like length and sorting.
127

128
```python { .api }
129
# From jsonpath_ng.ext
130
def parse(path: str, debug: bool = False) -> JSONPath: ...
131
```
132

133
```python { .api }
134
# Arithmetic operations
135
class Operation(JSONPath):
136
    def __init__(self, left, op: str, right): ...
137
    def find(self, datum) -> List[DatumInContext]: ...
138

139
# Filtering operations  
140
class Filter(JSONPath):
141
    def __init__(self, expressions): ...
142
    def find(self, datum) -> List[DatumInContext]: ...
143
```
144

145
[Extensions](./extensions.md)
146

147
### Command Line Interface
148

149
Command-line tool for executing JSONPath queries against JSON files or stdin input. Supports all JSONPath syntax and integrates well with shell pipelines.
150

151
```python { .api }
152
def main(*argv): ...
153
def entry_point(): ...
154
def find_matches_for_file(expr, f): ...
155
def print_matches(matches): ...
156
```
157

158
[Command Line Interface](./command-line.md)
159

160
## Types
161

162
```python { .api }
163
class JSONPath:
164
    """Base class for JSONPath abstract syntax"""
165
    def find(self, data) -> Iterable[DatumInContext]: ...
166
    def find_or_create(self, data) -> Iterable[DatumInContext]: ...
167
    def update(self, data, val): ...  # val can be value or callable(old, parent, key) -> new
168
    def update_or_create(self, data, val): ...  # val can be value or callable(old, parent, key) -> new
169
    def filter(self, fn, data): ...  # fn: callable(value) -> bool
170
    def child(self, child: 'JSONPath') -> 'JSONPath': ...
171
    def make_datum(self, value) -> DatumInContext: ...
172

173
class DatumInContext:
174
    """Represents a datum along a path from a context"""
175
    def __init__(self, value, path: JSONPath = None, context: 'DatumInContext' = None): ...
176
    @classmethod
177
    def wrap(cls, data) -> 'DatumInContext': ...
178
    def in_context(self, context, path) -> 'DatumInContext': ...
179
    @property
180
    def full_path(self) -> JSONPath: ...
181
    @property
182
    def id_pseudopath(self) -> JSONPath: ...
183
    value: Any
184
    path: JSONPath
185
    context: 'DatumInContext'
186
```
187

188
## Exceptions
189

190
```python { .api }
191
class JSONPathError(Exception):
192
    """Base exception for all JSONPath operations"""
193

194
class JsonPathLexerError(JSONPathError):
195
    """Raised when the lexer encounters invalid tokens during tokenization"""
196

197
class JsonPathParserError(JSONPathError):
198
    """Raised when the parser encounters invalid JSONPath syntax"""
199
```
200

201
## Global Configuration
202

203
```python { .api }
204
# Module-level configuration
205
jsonpath.auto_id_field: Optional[str] = None  # Enable automatic ID field generation
206

207
# Module-level constants
208
__version__: str = "1.7.0"  # Package version
209
NOT_SET: object  # Sentinel value for missing data  
210
LIST_KEY: object  # Special key used for internal list operations
211
```