Fast, modern, idiosyncratic jsonpath implementation in pure Python

This is a pure Python 3.x implementation of a JSON path language (there is no real standard syntax for JSON path, so this implements one among many, but I think the syntax is nice).

It uses a proper, extensivle parser, and it's fast compared to some pure-Python jsonpath libraries out there (the parser is literally thousands of times faster than jsonpath_ng for common inputs).

from jsonpathfx import parse

# Parse a JSON path string into a `jsonpathfx.JsonPath` object
jp = parse("foo.bar")

# Use the JsonPath object to search a JSON-like structure
assert jp.values({"foo": {"bar": 10, "baz": 20}}) == [10]

# You can get the matches as a generator instead of a list
for value in jp.itervalues({"foo": {"bar": 10, "baz": 20}}):
    print(value)

# You can get Match objects with a few useful methods if needed
for match in jp._find(data):
    print("The value of this match is:", match.value)
    print("The path to this match is:", match.path())
    print("The bound key values for this match are:", match.bindings())

JsonPath.values() always returns a list of all the values in the given structure that matched the path. If no items in the structure matched, the list is empty.

You can use Python-style line comments, which may be useful for "verbose" multi-line path definitions:

p = parse("""
foo.    # Lookup the 'foo' key at the root level
k:*.    # Try every key, bind the matching one to 'k'
bar     # Lookup the bar key
""")

• Operators have the following relative binding strength, from loosest to tightest binding:
  • () {} (group, contains)
  • & (intersect)
  • | (union)
  • || && (logic operators)
  • == != < <= > >= (comparisons)
  • + -
  • * /
  • . (child)
  • name: (bind)
• You can use parentheses (()) to group clauses.

The left and right hand side of a comparison are treated specially in some ways.

• A comparison yields items from the left side (for which the comparison returns true).
• A quoted string on thr right side is treated as a string to compare to, instead of a key match as it would be normally.

It's very useful to combine {} (contains) syntax with comparisons to filter items in an array or object. This is often in a form like *{x > 5} (find all objects with a key x of value greater than 5).

For example:

from jsonpathfx import parse

doc = {
    "things": [
        {"type": "car", "color": "red", "size": 5, "id": "a"},
        {"type": "boat", "color": "blue", "size": 2, "id": "b"},
        {"type": "car", "color": "blue", "size": 3, "id": "c"},
        {"type": "boat", "color": "red", "size": 6, "id": "d"},
    ]
}
# Find IDs of things where color == "red"
p = parse("things.*{color == 'red'}.id")
assert p.values(doc) == ["a", "d"]
# Find IDs of boats that are red
p = parse("things.*{type == 'boat' && color == 'red'}.id")
assert p.values(doc) == ["d"]

Sometimes it's useful to know which key/index of several options inside a path actually matched for each result. For example, if you have a path such as:

geometry.(points|vertices|faces).rows.*

...You might want to know if it was under a points, vertices, or faces key. To get this information, you can bind that key expression to a name such as component:

geometry.component:(points|vertices|faces).rows.*

Then, you can retrieve the bindings for each match from the Match objects returned by JsonPath.find():

from jsonpathfx import parse

jp = parse("geometry.component:(points|vertices|faces).rows.*")
for match in jp._find(my_data):
    print("value=", match.value, "bindings=", match.bindings())