Python JSONPath

A flexible JSONPath engine for Python.
We follow RFC 9535 and test against the JSONPath Compliance Test Suite.

---

Table of Contents

• Install
• Links
• Related projects
• Examples
• License

Install

Install Python JSONPath using pip:

pip install python-jsonpath

Or Pipenv:

pipenv install -u python-jsonpath

Or from conda-forge:

conda install -c conda-forge python-jsonpath

Links

• Documentation: https://jg-rp.github.io/python-jsonpath/.
• JSONPath Syntax: https://jg-rp.github.io/python-jsonpath/syntax/
• Change log: https://github.com/jg-rp/python-jsonpath/blob/main/CHANGELOG.md
• PyPi: https://pypi.org/project/python-jsonpath
• Source code: https://github.com/jg-rp/python-jsonpath
• Issue tracker: https://github.com/jg-rp/python-jsonpath/issues

Related projects

• JSONPath RFC 9535 - A minimal, slightly cleaner Python implementation of RFC 9535. If you're not interested JSONPath sytax beyond that defined in RFC 9535, you might choose jsonpath-rfc9535 over python-jsonpath.

  jsonpath-rfc9535 also includes utilities for verifying and testing the JSONPath Compliance Test Suite. Most notably the nondeterministic behavior of some JSONPath selectors.

• JSON P3 - RFC 9535 implemented in TypeScript. JSON P3 does not include all the non-standard features of Python JSONPath, but does define some optional extra syntax.

• Ruby JSON P3 - RFC 9535, RFC 6901 and RFC 6902 implemented in Ruby.

Examples

JSONPath

import jsonpath

data = {
    "users": [
        {"name": "Sue", "score": 100},
        {"name": "John", "score": 86},
        {"name": "Sally", "score": 84},
        {"name": "Jane", "score": 55},
    ]
}

user_names = jsonpath.findall("$.users[?@.score < 100].name", data)
print(user_names) # ['John', 'Sally', 'Jane']

JSON Pointer

We include an RFC 6901 compliant implementation of JSON Pointer. See JSON Pointer quick start, guide and API reference

from jsonpath import pointer

data = {
    "users": [
        {"name": "Sue", "score": 100},
        {"name": "John", "score": 86},
        {"name": "Sally", "score": 84},
        {"name": "Jane", "score": 55},
    ]
}

sue_score = pointer.resolve("/users/0/score", data)
print(sue_score)  # 100

jane_score = pointer.resolve(["users", 3, "score"], data)
print(jane_score)  # 55

JSON Patch

We also include an RFC 6902 compliant implementation of JSON Patch. See JSON Patch quick start and the API reference.

Warning

Objects passed to patch.apply() and JSONPatch.apply() are modified in place, even if a patch operation fails. Use patch.atomic() or JSONPatch.atomic() if you need to preserve input data on patch failure.

from jsonpath import patch

patch_operations = [
    {"op": "add", "path": "/some/foo", "value": {"foo": {}}},
    {"op": "add", "path": "/some/foo", "value": {"bar": []}},
    {"op": "copy", "from": "/some/other", "path": "/some/foo/else"},
    {"op": "add", "path": "/some/foo/bar/-", "value": 1},
]

data = {"some": {"other": "thing"}}
patch.apply(patch_operations, data)
print(data) # {'some': {'other': 'thing', 'foo': {'bar': [1], 'else': 'thing'}}}

Use patch.atomic() or JSONPatch.atomic() if you need to preserve input data on patch failure.

import contextlib

from jsonpath import JSONPatchError
from jsonpath import patch

patch_operations = [
    {"op": "add", "path": "/some/foo", "value": {"foo": {}}},
    {"op": "add", "path": "/some/foo", "value": {"bar": []}},
    {"op": "copy", "from": "/some/other", "path": "/some/foo/else"},
    {"op": "add", "path": "/some/foo/bar/-", "value": 1},
    {"op": "test", "path": "/some/thing", "value": "baz"},  # Always fails
]

data = {"some": {"other": "thing"}}

with contextlib.suppress(JSONPatchError):
    patch.atomic(patch_operations, data)

assert data == {"some": {"other": "thing"}}

License

python-jsonpath is distributed under the terms of the MIT license.