Install & Compatibility
Where this runs
tested against v1.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.154s · 20.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.9s · import 0.154s · 21MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ import jsonpath_rw_ext
expression = jsonpath_rw_ext.parse('$.foo.bar')
✗ from jsonpath_rw import parse
# This 'parse' will not include the extensions from jsonpath-rw-ext.
To utilize the extended features, ensure you import 'parse' directly from 'jsonpath_rw_ext' or use its namespace.
ExtentedJsonPathParser
✓ from jsonpath_rw_ext import parser
expression = parser.ExtentedJsonPathParser().parse('$.foo.bar')
✗ from jsonpath_rw.parser import parse
# This imports the base parser, not the extended one.
For explicit use of the extended parser class, import it from 'jsonpath_rw_ext.parser'.
match
✓ import jsonpath_rw_ext as jp
result = jp.match('$.items[*]', {'items': [1, 2, 3]})
The `match` and `match1` shortcut functions are available when importing `jsonpath_rw_ext` with an alias.
This example demonstrates how to use the 'len', 'filter', and 'arithmetic' extensions provided by jsonpath-rw-ext to query a sample JSON structure.
import json
import jsonpath_rw_ext
data = {
"store": {
"book": [
{ "category": "reference",
"author": "Nigel Rees",
"title": "Sayings of the Century",
"price": 8.95
},
{ "category": "fiction",
"author": "Evelyn Waugh",
"title": "Sword of Honour",
"price": 12.99
},
{ "category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
}
}
# Using the 'len' extension to get the number of books
jsonpath_expr_len = jsonpath_rw_ext.parse('$.store.book.`len`')
matches_len = jsonpath_expr_len.find(data)
print(f"Number of books: {matches_len[0].value}")
# Using the 'filter' extension to find books cheaper than 10
jsonpath_expr_filter = jsonpath_rw_ext.parse('$.store.book[?(@.price < 10)]')
matches_filter = [match.value for match in jsonpath_expr_filter.find(data)]
print(f"Books cheaper than 10: {[book['title'] for book in matches_filter]}")
# Using arithmetic extension
jsonpath_expr_arith = jsonpath_rw_ext.parse('$.store.bicycle.price * 2')
matches_arith = jsonpath_expr_arith.find(data)
print(f"Double bicycle price: {matches_arith[0].value}")
Debug
Known issues
gotchajsonpath-rw-ext acts as an extension to jsonpath-rw. Advanced filtering syntax (e.g., `[?()]`) and other extensions are provided by jsonpath-rw-ext, not the base jsonpath-rw library. Attempting to use these features directly with `jsonpath_rw.parse` will result in errors.fixAlways import and use `parse` from `jsonpath_rw_ext` to ensure the extended parser is used.
affects: All versions
gotchaThe classes internal to `jsonpath_rw` that are extended by `jsonpath-rw-ext` are not considered part of its public API. Their structure and naming might change if these extensions are eventually integrated into the upstream `jsonpath-rw` project. Only the JSONPath syntax is guaranteed to remain stable.fixRely primarily on the JSONPath query string syntax rather than directly manipulating internal `jsonpath_rw` AST classes when using `jsonpath-rw-ext`.
affects: All versions
deprecatedThe `jsonpath-ng` library is presented as a successor, merging `jsonpath-rw` and `jsonpath-rw-ext` functionalities, aiming for broader standard compliance, performance improvements, and enhanced AST API (e.g., node update/removal). For new projects, `jsonpath-ng` might be a more robust and actively developed alternative.fixConsider using `jsonpath-ng` for new projects: `pip install jsonpath-ng`.
affects: All versions
gotchaWhen using arithmetic or string operations within JSONPath expressions (e.g., `$.foo + $.bar`), the paths must be fully defined (e.g., `$.field`). If not fully defined, `jsonpath-rw-ext` may incorrectly interpret the expression as a string literal rather than a JSONPath field, leading to unexpected results or empty matches.fixEnsure all operands in arithmetic or string concatenation expressions are explicit JSONPath fields (e.g., `$.field`).
affects: All versions
gotchaIn some environments (e.g., PySpark), using `jsonpath-rw-ext` has been reported to cause issues related to its dependency `pbr` needing an updated `setuptools` to avoid versioning exceptions.fixEnsure `setuptools` is up-to-date in your environment, potentially by including it in the installation command: `pip install jsonpath-rw-ext setuptools`.
affects: Potentially older environments or specific deployment setups
Errors
Common errors & fixes
jsonpath_rw.lexer.JsonPathLexerError: Error on line 1, col X: Unexpected character: ?
This error occurs when attempting to use advanced JSONPath filter expressions (e.g., `[?(expression)]`) that are part of the `jsonpath-rw-ext` extensions, but the parsing is being performed by the standard `jsonpath-rw` parser, which does not support these extensions by default.
fixEnsure you are importing and using the `parse` function from `jsonpath_rw_ext` to enable the extended grammar.
```python
import jsonpath_rw_ext
jsonpath_expression = jsonpath_rw_ext.parse('$.foo[?(@.bar == "value")]')
# Or, for more control:
# from jsonpath_rw_ext import parser
# jsonpath_expression = parser.ExtentedJsonPathParser().parse('$.foo[?(@.bar == "value")]')
``` AttributeError: module 'jsonpath_rw' has no attribute 'parse'
This typically happens when a developer tries to import `parse` directly from `jsonpath_rw` while intending to use the extended parser provided by `jsonpath-rw-ext`. The `jsonpath_rw` module itself might not expose a top-level `parse` function in the way `jsonpath_rw_ext` does for convenience with its extensions.
fixTo use the extended parser, you should import `jsonpath_rw_ext` and use its `parse` function.
```python
import jsonpath_rw_ext
jsonpath_expression = jsonpath_rw_ext.parse('$.data.`len`')
``` Incorrect length calculation with .`len` extension (e.g., returns string length instead of list length, or unexpected count)
The `.len` extension is designed to get the length of a list or array. However, if the preceding path expression resolves to a single scalar value (like a string or number) rather than a list, applying `.len` might return the length of that scalar (e.g., string length) or behave unexpectedly if it's not applicable, leading to confusion about the result.
fixEnsure the JSONPath expression preceding the `.`len` extension correctly targets a list or array. If filtering, confirm the filter yields the desired list of elements before applying `.`len`. If a Python-level list of results is obtained, use Python's built-in `len()` function on the result list for clarity.
```python
import jsonpath_rw_ext
data = {'objects': ['a', 'b', 'c']}
path = jsonpath_rw_ext.parse('$.objects.`len`')
result = path.find(data)
# result.value will be 3
data_with_filtered_list = {'items': [{'id': 1}, {'id': 2}, {'id': 1}]}
path_filtered_len = jsonpath_rw_ext.parse('$.items[?(@.id == 1)].`len`') # This might not work as expected to count matches
# Instead, find and then use Python's len()
matches = jsonpath_rw_ext.parse('$.items[?(@.id == 1)]').find(data_with_filtered_list)
actual_count = len(matches) # This is the reliable way to count matched elements
``` Upgrade
Version history
1.2.2latest on PyPI · released Jul 12, 2019
Audit
Dependencies
jsonpath-rwrequiredProvides the core JSONPath implementation which jsonpath-rw-ext extends.