Skip to content

Commit a838f1a

Browse files
committed
docs: update README with new features and 'Why this' section
1 parent d396bc5 commit a838f1a

File tree

1 file changed

+29
-18
lines changed

1 file changed

+29
-18
lines changed

README.md

Lines changed: 29 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,24 @@
1-
- [jsonpath-python](#jsonpath-python)
2-
- [Features](#features)
3-
- [JSONPath Syntax](#jsonpath-syntax)
4-
- [Operators](#operators)
5-
- [Examples](#examples)
6-
- [Select Fields](#select-fields)
7-
- [Recursive Descent](#recursive-descent)
8-
- [Slice](#slice)
9-
- [Filter Expression](#filter-expression)
10-
- [Sorter Expression](#sorter-expression)
11-
- [Field-Extractor Expression](#field-extractor-expression)
12-
- [Appendix: Example JSON data:](#appendix-example-json-data)
13-
- [Todo List](#todo-list)
14-
151
# jsonpath-python
162

17-
A more powerful JSONPath implementation in modern python.
3+
A lightweight and powerful JSONPath implementation for Python.
4+
5+
## Why jsonpath-python?
6+
7+
There are already several JSONPath libraries in Python, so why choose this one?
8+
9+
1. **Lightweight & Zero Dependency**: Unlike `jsonpath-ng` which relies on complex AST parsing frameworks like `ply`, `jsonpath-python` is implemented with pure Python string parsing. It has **zero third-party dependencies**, making it incredibly easy to integrate into any environment (including restricted ones like AWS Lambda or embedded systems).
10+
2. **Simple & Pythonic**: The implementation is straightforward and linear. If you encounter a bug or need to extend it, the code is easy to read and modify. You can even copy the core file directly into your project as a utility.
11+
3. **Powerful Features**: It supports advanced features like **sorting**, **filtering**, and **updating** JSON data, which are often missing or incomplete in other lightweight implementations.
1812

1913
## Features
2014

2115
- [x] **Light. (No need to install third-party dependencies.)**
2216
- [x] **Support filter operator, including multi-selection, inverse-selection filtering.**
2317
- [x] **Support sorter operator, including sorting by multiple fields, ascending and descending order.**
18+
- [x] **Support updating JSON data using JSONPath expressions.**
2419
- [x] Support basic semantics of JSONPath.
2520
- [x] Support output modes: VALUE, PATH.
26-
- [ ] Support embedded syntax.
27-
- [ ] Support user-defined function.
28-
- [ ] Support parent operator.
21+
- [x] Support regex filter (`=~`).
2922

3023
## Installation
3124

@@ -141,6 +134,8 @@ Support all python comparison operators (`==`, `!=`, `<`, `>`, `>=`, `<=`), pyth
141134
['Moby Dick']
142135
>>> JSONPath('$.book[?(@.author=="Herman Melville" or @.author=="Evelyn Waugh")].author').parse(data)
143136
['Evelyn Waugh', 'Herman Melville']
137+
>>> JSONPath('$.book[?(@.title =~ /.*Century/)]').parse(data)
138+
[{'category': 'reference', 'author': 'Nigel Rees', 'title': 'Sayings of the Century', 'price': 8.95, 'brand': {'version': 'v1.0.0'}}]
144139
```
145140

146141
`Note`: You must use double quote(`""`) instead of single quote(`''`) to wrap the compared string, because single quote(`''`) has another usage in this JSONPath syntax .
@@ -173,6 +168,20 @@ Using `(field1,field2,…,filedn)` after a dict object to extract its fields.
173168
[{'title': 'Moby Dick', 'price': 8.99}, {'title': 'Sword of Honour', 'price': 12.99}, {'title': 'The Lord of the Rings', 'price': 22.99}, {'title': 'Sayings of the Century', 'price': 8.95}]
174169
```
175170

171+
#### Update Data
172+
173+
Update values in the JSON object using the `update` method.
174+
175+
```python
176+
# Update with a static value
177+
>>> JSONPath("$.book[*].price").update(data, 100)
178+
# Result: All book prices are set to 100
179+
180+
# Update with a function (e.g., apply a discount)
181+
>>> JSONPath("$.book[*].price").update(data, lambda x: x * 0.9)
182+
# Result: All book prices are multiplied by 0.9
183+
```
184+
176185
### Appendix: Example JSON data:
177186

178187
```python
@@ -249,6 +258,8 @@ data = {
249258

250259
## Todo List
251260

261+
- Support embedded syntax.
262+
- Support user-defined function.
252263
- Syntax and character set (refer to k8s)
253264

254265
> The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.

0 commit comments

Comments
 (0)