This repository contains an implementation of JSONPath (XPath for JSON) for the Python programming language.
The jsonpath2.path.Path class represents a JSONPath.
>>> s = '{"hello":"Hello, world!"}'
'{"hello":"Hello, world!"}'
>>> import json
>>> d = json.loads(s)
{'hello':'Hello, world!'}
>>> from jsonpath2.path import Path
>>> p = Path.parse_str('$["hello"]')
<jsonpath2.path.Path object>
>>> list(map(lambda match_data: match_data.current_value, p.match(d)))
['Hello, world!']
>>> list(map(lambda match_data: match_data.node.tojsonpath(), p.match(d)))
['$["hello"]']This class is constructed with respect to the given instance of the jsonpath2.nodes.root.RootNode class (viz., the root_node property).
Parse the given string and return a new instance of this class.
Parse the contents of the given file and return a new instance of this class.
Match the given JSON data structure against this instance.
For each match, yield an instance of the jsonpath2.node.MatchData class.
Tests if two instances are equal.
Returns the string representation of this instance.
The root node of the abstract syntax tree for this instance.
The jsonpath2.node.Node class represents the abstract syntax tree for a JSONPath.
Tests if two instances are equal.
Yields the lexer tokens for the string representation of this instance.
Match the given root and current JSON data structures against this instance.
For each match, yield an instance of the jsonpath2.node.MatchData class.
Returns the string representation of this instance.
The jsonpath2.node.MatchData class represents the JSON value and context for a JSONPath match.
This class is constructed with respect to a root JSON value, a current JSON value, and an abstract syntax tree node.
Tests if two instances are equal.
The root JSON value.
The current JSON value (i.e., the matching JSON value).
The abstract syntax tree node.
| XPath | JSONPath | Description |
|---|---|---|
/ |
$ |
the root JSON value |
. |
@ |
the current JSON value |
/ |
. or [] |
child operator |
// |
.. |
recursive descent (depth-first search) |
* |
* |
wildcard (all elements of a JSON array; all values of a JSON object; otherwise none) |
[] |
[] |
subscript operator |
| |
[,] |
union operator (for two or more subscript operators) |
| n/a | [start:end:step] |
slice operator (subset of elements of a JSON array) |
[] |
?() |
filter expression (for use with subscript operator) |
| JSONPath Filter Expression | Description |
|---|---|
$ or @ |
nested JSONPath (returns true if any match exists; otherwise, returns false) |
=, !=, >, >=, <, <= |
binary operator, where left- and right-hand operands are nested JSONPaths or JSON values (returns true if any match exists; otherwise, returns false) |
and, or, not |
Boolean operator, where operands are JSONPath filter expressions |
( ... ) |
parentheses |
See #14 for more information.
The syntax for a function call is the name of the function followed by the arguments in parentheses, i.e., name(arg1, arg2, ..., argN), where the arguments are either JSONPaths or JSON values.
>>> s = '{"hello":"Hello, world!"}'
'{"hello":"Hello, world!"}'
>>> import json
>>> d = json.loads(s)
{'hello':'Hello, world!'}
>>> from jsonpath2.path import Path
>>> p = Path.parse_str('$["hello"][length()]')
<jsonpath2.path.Path object>
>>> list(map(lambda match_data: match_data.current_value, p.match(d)))
[13]
>>> list(map(lambda match_data: match_data.node.tojsonpath(), p.match(d)))
['$["hello"][length()]']| JavaScript Function | Signature |
|---|---|
Array.length |
length(): int |
Array.prototype.entries() |
entries(): List[Tuple[int, Any]] |
Array.prototype.keys() |
keys(): List[int] |
Array.prototype.values() |
values(): List[Any] |
Object.entries() |
entries(): List[Tuple[str, Any]] |
Object.keys() |
keys(): List[str] |
Object.values() |
values(): List[Any] |
string.length |
length(): int |
String.prototype.charAt() |
charAt(index: int): str |
String.prototype.substring() |
substring(indexStart: int, indexEnd: Optional[int]): str |
In the above table, the type aliases (Any, List, Optional and Tuple) are defined by the typing module from the Python Standard Library.
The ANTLR v4 grammar for JSONPath is available at jsonpath2/parser/JSONPath.g4.
Adapted from https://github.com/antlr/antlr4/blob/master/doc/getting-started.md.
cd /usr/local/lib
curl -O http://www.antlr.org/download/antlr-4.7.1-complete.jar
export CLASSPATH=".:/usr/local/lib/antlr-4.7.1-complete.jar:$CLASSPATH"
alias antlr4='java -Xmx500M -cp "/usr/local/lib/antlr-4.7.1-complete.jar:$CLASSPATH" org.antlr.v4.Tool'
alias grun='java org.antlr.v4.gui.TestRig'Adapted from https://github.com/antlr/antlr4/blob/master/doc/python-target.md.
antlr4 -Dlanguage=Python3 -o . -lib . jsonpath2/parser/JSONPath.g4