jsonpath

library0.82.2pypypi✓ verified 23d ago

The `jsonpath` library provides a Pythonic implementation of JSONPath, following the IETF JSONPath draft specification. It allows users to query JSON-like data structures using XPath-like expressions. It's actively developed, with the latest version being 0.82.2, and typically releases updates as the IETF draft progresses or new features are added.

serialization data

pip install jsonpath

package ↗homepage ↗

INSTALL

IMPORT

SIG · JSONPATH

jsonpath

serializationpythonv0.82.2

Install

2.4s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.82.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.4s · import 0.000s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsonpath

✓ import jsonpath

Import the module to access `jsonpath.select` for convenience or `jsonpath.JSONPath` for object-oriented usage.

JSONPath

✓ from jsonpath import JSONPath

Import the main class to compile and reuse JSONPath expressions.

select

✓ from jsonpath import select

Import the convenience function to directly query data without explicit class instantiation.

This quickstart demonstrates how to use the `jsonpath.select` convenience function for simple queries, and how to use the `jsonpath.JSONPath` class for compiling and reusing path expressions, which is more efficient for repeated queries against different data.

import jsonpath 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} ], "bicycle": {"color": "red", "price": 19.95} } } # Use the convenience 'select' function to query data path_expression = "$.store.book[*].author" authors = jsonpath.select(path_expression, data) print(f"Authors found: {authors}") # For performance-critical scenarios, compile the path once using JSONPath class from jsonpath import JSONPath json_path = JSONPath(path_expression) authors_compiled = json_path.findall(data) print(f"Authors (compiled path): {authors_compiled}")

Debug

Known issues

breakingThis library strictly adheres to the IETF JSONPath draft. Its syntax and behavior may differ significantly from other popular Python JSONPath implementations (e.g., `jsonpath_rw`, `jsonpath-ng`). Users migrating or expecting behavior from non-standard JSONPath libraries should carefully review the IETF specification and library documentation.

fix

Consult the official documentation for the `jsonpath` library and the IETF JSONPath draft. Thoroughly test existing JSONPath expressions when migrating from other libraries.

affects: 0.1.0+

gotchaFor repeated queries with the same JSONPath expression, using `jsonpath.select()` repeatedly is less efficient than instantiating a `JSONPath` object once and calling its `findall()` method. `select()` re-compiles the path on each call.

fix

For performance-sensitive applications, instantiate `json_path = JSONPath("your_path")` once, and then call `json_path.findall(data)` or `json_path.find(data)` for each query.

affects: 0.1.0+

gotchaThe `JSONPath` object has both `find()` and `findall()` methods. `find()` returns the first matching element (or `None`), while `findall()` returns a list of all matching elements. Confusing these can lead to unexpected results (e.g., only getting one match when multiple exist).

fix

Always use `findall()` when you expect or need all potential matches from a JSONPath expression. Use `find()` only when you explicitly need the first result or know there's at most one.

affects: 0.1.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'jsonpath'

The `jsonpath` library is not installed in the current Python environment or is installed under a different name (e.g., `jsonpath-ng`).

fix

Install the correct package using pip: `pip install jsonpath`

AttributeError: module 'jsonpath' has no attribute 'jsonpath'

This typically occurs when trying to call a method like `jsonpath.jsonpath()` directly, but the primary functions are often exposed at the top level of the `jsonpath` module or via `JSONPath` object instantiation.

fix

Use the functions directly from the imported module, such as `jsonpath.find()` or `jsonpath.parse()`, or instantiate a `JSONPath` object: `from jsonpath import JSONPath; query = JSONPath('$.some.path')`

jsonpath.exceptions.JSONPathSyntaxError: Expected <token> at position <number>

The provided JSONPath expression has a syntax error, such as incorrect characters, unquoted names, or invalid filter conditions.

fix

Review and correct the JSONPath expression to comply with the IETF JSONPath draft specification, ensuring proper quoting, valid operators, and correct structure. Example of correct syntax: `$.store.book[?(@.price < 10)]`

AttributeError: 'list' object has no attribute 'find'

This error occurs when a JSONPath query returns a list of matching elements, but subsequent code attempts to call a method like `.find()` (which is usually for strings or `jsonpath` objects) directly on the resulting list.

fix

Iterate through the list of results or access elements by index if a list is expected: `results = jsonpath.find('$.items[*]', data); for item in results: print(item)` or `first_item = results[0]`

Upgrade

Version history

0.82.2latest on PyPI · released Aug 24, 2023

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/jsonpath/ ↗

homepagehttp://www.ultimate.com/phil/python/#jsonpath ↗