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"}}

patch.patched(ops, data) and JSONPatch.patched(data) apply patch operations to a deep copy of data.

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"}}
patched_data = patch.patched(patch_operations, data)

assert data != patched_data

License

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