Convenience Functions

These package-level functions use the default JSONPathEnvironment, jsonpath.DEFAULT_ENV when strict=False, or the preconfigured strict environment, jsonpath.STRICT_ENV when strict=True.

jsonpath.compile

compile(
    path: str, *, strict: bool = False
) -> Union[JSONPath, CompoundJSONPath]

Prepare a path string ready for repeated matching against different data.

PARAMETER	DESCRIPTION
path	A JSONPath as a string. TYPE: str
strict	When True, compile the path for strict compliance with RFC 9535. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Union[JSONPath, CompoundJSONPath]	A JSONPath or CompoundJSONPath, ready to match against some data. Expect a CompoundJSONPath if the path string uses the union or intersection operators.

RAISES	DESCRIPTION
JSONPathSyntaxError	If path is invalid.
JSONPathTypeError	If filter functions are given arguments of an unacceptable type.

jsonpath.findall

findall(
    path: str,
    data: JSONData,
    *,
    filter_context: Optional[FilterContextVars] = None,
    strict: bool = False
) -> List[object]

Find all objects in data matching the JSONPath path.

If data is a string or a file-like objects, it will be loaded using json.loads() and the default JSONDecoder.

PARAMETER	DESCRIPTION
path	The JSONPath as a string. TYPE: str
data	A JSON document or Python object implementing the Sequence or Mapping interfaces. TYPE: JSONData
filter_context	Arbitrary data made available to filters using the filter context selector. TYPE: Optional[FilterContextVars] DEFAULT: None
strict	When True, compile and evaluate with strict compliance with RFC 9535. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
List[object]	A list of matched objects. If there are no matches, the list will be empty.

RAISES	DESCRIPTION
JSONPathSyntaxError	If the path is invalid.
JSONPathTypeError	If a filter expression attempts to use types in an incompatible way.

jsonpath.finditer

finditer(
    path: str,
    data: JSONData,
    *,
    filter_context: Optional[FilterContextVars] = None,
    strict: bool = False
) -> Iterable[JSONPathMatch]

Generate JSONPathMatch objects for each match of path in data.

If data is a string or a file-like objects, it will be loaded using json.loads() and the default JSONDecoder.

PARAMETER	DESCRIPTION
path	The JSONPath as a string. TYPE: str
data	A JSON document or Python object implementing the Sequence or Mapping interfaces. TYPE: JSONData
filter_context	Arbitrary data made available to filters using the filter context selector. TYPE: Optional[FilterContextVars] DEFAULT: None
strict	When True, compile and evaluate with strict compliance with RFC 9535. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Iterable[JSONPathMatch]	An iterator yielding JSONPathMatch objects for each match.

RAISES	DESCRIPTION
JSONPathSyntaxError	If the path is invalid.
JSONPathTypeError	If a filter expression attempts to use types in an incompatible way.

jsonpath.findall_async async

findall_async(
    path: str,
    data: JSONData,
    *,
    filter_context: Optional[FilterContextVars] = None,
    strict: bool = False
) -> List[object]

Find all objects in data matching the JSONPath path.

If data is a string or a file-like objects, it will be loaded using json.loads() and the default JSONDecoder.

PARAMETER	DESCRIPTION
path	The JSONPath as a string. TYPE: str
data	A JSON document or Python object implementing the Sequence or Mapping interfaces. TYPE: JSONData
filter_context	Arbitrary data made available to filters using the filter context selector. TYPE: Optional[FilterContextVars] DEFAULT: None
strict	When True, compile and evaluate with strict compliance with RFC 9535. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
List[object]	A list of matched objects. If there are no matches, the list will be empty.

RAISES	DESCRIPTION
JSONPathSyntaxError	If the path is invalid.
JSONPathTypeError	If a filter expression attempts to use types in an incompatible way.

jsonpath.finditer_async async

finditer_async(
    path: str,
    data: JSONData,
    *,
    filter_context: Optional[FilterContextVars] = None,
    strict: bool = False
) -> AsyncIterable[JSONPathMatch]

Find all objects in data matching the JSONPath path.

If data is a string or a file-like objects, it will be loaded using json.loads() and the default JSONDecoder.

PARAMETER	DESCRIPTION
path	The JSONPath as a string. TYPE: str
data	A JSON document or Python object implementing the Sequence or Mapping interfaces. TYPE: JSONData
filter_context	Arbitrary data made available to filters using the filter context selector. TYPE: Optional[FilterContextVars] DEFAULT: None
strict	When True, compile and evaluate with strict compliance with RFC 9535. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
AsyncIterable[JSONPathMatch]	A list of matched objects. If there are no matches, the list will be empty.

RAISES	DESCRIPTION
JSONPathSyntaxError	If the path is invalid.
JSONPathTypeError	If a filter expression attempts to use types in an incompatible way.

jsonpath.match

The JSONPath match object, as returned from JSONPath.finditer().

JSONPathMatch

A matched object with a concrete path.

ATTRIBUTE	DESCRIPTION
children	Matched child nodes. This will only be populated after all children have been visited, usually by using findall() or list(finditer()). TYPE: List[JSONPathMatch]
obj	The matched object. TYPE: object
parent	The immediate parent to this match in the JSON document. If this is the root node, parent will be None. TYPE: Optional[JSONPathMatch]
path	The canonical string representation of the path to this match. TYPE: str
parts	The keys, indices and/or slices that make up the path to this match. TYPE: Tuple[PathPart, ...]
root	A reference to the root node in the JSON document. TYPE: Union[Sequence[Any], Mapping[str, Any]]

value property

value: object

Return the value associated with this match/node.

add_child

add_child(*children: JSONPathMatch) -> None

Append one or more children to this match.

filter_context

filter_context() -> FilterContextVars

Return filter context data for this match.

new_child

new_child(
    obj: object, key: Union[int, str]
) -> JSONPathMatch

Return a new JSONPathMatch instance with this instance as its parent.

pointer

pointer() -> JSONPointer

Return a JSONPointer pointing to this match's path.

NodeList

Bases: List[JSONPathMatch]

List of JSONPathMatch objects, analogous to the spec's nodelist.

empty

empty() -> bool

Return True if this node list is empty.

paths

paths() -> List[str]

Return a normalized path for each node in this node list.

values

values() -> List[object]

Return the values from this node list.

values_or_singular

values_or_singular() -> object

Return the values from this node list.

jsonpath.query

query(
    path: str,
    data: JSONData,
    *,
    filter_context: Optional[FilterContextVars] = None,
    strict: bool = False
) -> Query

Return a Query iterator over matches found by applying path to data.

Query objects are iterable.

for match in jsonpath.query("$.foo..bar", data):
    ...

You can skip and limit results with Query.skip() and Query.limit().

matches = (
    jsonpath.query("$.foo..bar", data)
    .skip(5)
    .limit(10)
)

for match in matches
    ...

Query.tail() will get the last n results.

for match in jsonpath.query("$.foo..bar", data).tail(5):
    ...

Get values for each match using Query.values().

for obj in jsonpath.query("$.foo..bar", data).limit(5).values():
    ...

PARAMETER	DESCRIPTION
path	The JSONPath as a string. TYPE: str
data	A JSON document or Python object implementing the Sequence or Mapping interfaces. TYPE: JSONData
filter_context	Arbitrary data made available to filters using the filter context selector. TYPE: Optional[FilterContextVars] DEFAULT: None
strict	When True, compile and evaluate with strict compliance with RFC 9535. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Query	A query iterator.

RAISES	DESCRIPTION
JSONPathSyntaxError	If the path is invalid.
JSONPathTypeError	If a filter expression attempts to use types in an incompatible way.