API Docs¶

jsonpath_rfc9535.compile(expr: str) → JSONPathQuery¶

Compile JSONPath query expr using the default configuration.

Parameters:

expr – A JSONPath query expression.

Returns:

query – A compiled query ready to match against JSON-like data.

Raises:

JSONPathNameError – If a function extension can not be resolved.
JSONPathRecursionError – If expr is crafted in such a way to hit Python’s recursion limit.
JSONPathSyntaxError – If expr is syntactically invalid.
JSONPathTypeError – If expr is semantically invalid - Calling a function extension with arguments of the wrong type or arity, for example.

jsonpath_rfc9535.find(expr: str, data: object) → JSONPathNodeList¶

Return nodes found by apply query expression expr to data using the default configuration.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Returns:

JSONPathNodeList – A list of JSON-like values and their location in data.

Raises:

JSONPathNameError – If a function extension can not be resolved.
JSONPathRecursionError – If expr is crafted in such a way to hit Python’s recursion limit. Or if a descendent segment visits nodes to a depth that exceeds the configured max_recursion_depth.
JSONPathSyntaxError – If expr is syntactically invalid.
JSONPathTypeError – If expr is semantically invalid - Calling a function extension with arguments of the wrong type or arity, for example.

jsonpath_rfc9535.findall(expr: str, data: object) → list[object]¶

Return all values found from applying query expression expr to data.

Use findall if you just need values from data, without their location or normalized path. It can be significantly faster and more memory efficient than find` or finditer.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Returns:

list[object] – All values found by applying expr to data.

Raises:

JSONPathError – The same as find.

See also

find

jsonpath_rfc9535.finditer(expr: str, data: object) → Iterable[JSONPathNode]¶

Generate nodes from applying query expression expr to data using the default configuration.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Yields:

JSONPathNode – Matched JSON-like values and their locations in data.

Raises:

JSONPathError – The same as find.

See also

find

jsonpath_rfc9535.search(expr: str, data: object) → JSONPathNode | None¶

Return the first node found by applying query expression expr to data.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Returns:

node (JSONPathNode, Optional) – The first available JSONPathNode instance, or None if there are no matches.

Raises:

JSONPathError – The same as find.

See also

find

class jsonpath_rfc9535.JSONPathEnvironment(*, max_index: int = 9007199254740991, min_index: int = -9007199254740991, max_recursion_depth: int = 100, max_expression_depth: int = 30, parser: Parser = <class 'jsonpath_rfc9535._parser_standard.StandardParser'>)¶

JSONPath parser and evaluator configuration.

Parameters:

max_index – The maximum integer allowed when selecting array items by index.
min_index – The minimum integer allowed when selecting array items by index.
max_expression_depth – The maximum number of nested expressions allowed in a query before a JSONPathRecursionError is raised.
max_recursion_depth – The maximum depth the descendant segment can go before a JSONPathRecursionError is raised.
parser – The JSONPath query parser to use. You can subclass StandardParser to customize JSONPath parsing behavior.

functions¶: A map of JSONPath function extension names to implementation - classes inheriting from FunctionExtension.

compile(expr: str) → JSONPathQuery¶

Prepare JSONPath query expr for repeated application to different data.

Parameters:

expr – A JSONPath query expression.

Returns:

query – A compiled query ready to match against JSON-like data.

Raises:

JSONPathNameError – If a function extension can not be resolved.
JSONPathRecursionError – If expr is crafted in such a way to hit Python’s recursion limit.
JSONPathSyntaxError – If expr is syntactically invalid.
JSONPathTypeError – If expr is semantically invalid - Calling a function extension with arguments of the wrong type or arity, for example.

find(expr: str, data: object) → JSONPathNodeList¶

Apply JSONPath query expr to data and return a list of nodes.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Returns:

JSONPathNodeList – A list of JSON-like values and their location in data.

Raises:

JSONPathNameError – If a function extension can not be resolved.
JSONPathRecursionError – If expr is crafted in such a way to hit Python’s recursion limit. Or if a descendent segment visits nodes to a depth that exceeds the configured max_recursion_depth.
JSONPathSyntaxError – If expr is syntactically invalid.
JSONPathTypeError – If expr is semantically invalid - Calling a function extension with arguments of the wrong type or arity, for example.

find_one(expr: str, data: object) → JSONPathNode | None¶: An alias for search.

See also

search

findall(expr: str, data: object) → list[object]¶

Apply JSONPath query expr to data and return a list of values.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Returns:

list[object] – All values found by applying expr to data.

Raises:

JSONPathError – The same as find.

See also

find

finditer(expr: str, data: object) → Iterable[JSONPathNode]¶

Generate nodes from applying query expression expr to data.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Yields:

JSONPathNode – The matched value and its location in data.

Raises:

JSONPathError – The same as find.

See also

find

parse(expr: str) → JSONPathQuery¶: An alias for compile.

See also

compile

search(expr: str, data: object) → JSONPathNode | None¶

Return the first node found by applying query expression expr to data.

Parameters:

expr – A JSONPath query expression.
data – JSON-like data to apply expr to.

Returns:

node (JSONPathNode, Optional) – The first available JSONPathNode instance, or None if there are no matches.

Raises:

JSONPathError – The same as find.

See also

find

class jsonpath_rfc9535.JSONPathQuery(env: JSONPathEnvironment, segments: tuple[Segment, ...])¶

A compiled JSONPath expression ready to be applied to JSON-like data.

Parameters:

env – The JSONPath configuration object this query is bound to.
segments – Our internal representation of a compiled JSONPath query.

find(data: object) → JSONPathNodeList¶

Apply this query to data and return a list of nodes.

Parameters:: data – JSON-like data to apply this query to.
Returns:: JSONPathNodeList – The list of nodes found by applying this query to data
Raises:: JSONPathRecursionError – If a descendent segment visits nodes to a depth that exceeds the configured max_recursion_depth.

find_one(data: object) → JSONPathNode | None¶: An alias for search.

See also

search

findall(data: object) → list[object]¶

Apply this query to data and return a list of values.

Parameters:: data – JSON-like data to apply this query to.
Returns:: list[object] – All values found by applying this query to data.
Raises:: JSONPathRecursionError – If a descendent segment visits nodes to a depth that exceeds the configured max_recursion_depth.

finditer(data: object) → Iterable[JSONPathNode]¶

Generate nodes by applying this query to data.

Parameters:: data – JSON-like data to apply this query to.
Yields:: JSONPathNode – The matched value and its location in data.
Raises:: JSONPathRecursionError – If a descendent segment visits nodes to a depth that exceeds the configured max_recursion_depth.

search(data: object) → JSONPathNode | None¶

Return the first node found by applying this query to data.

Parameters:: data – JSON-like data to apply this query to.
Returns:: node (JSONPathNode, Optional) – The first available JSONPathNode instance, or None if there are no matches.
Raises:: JSONPathRecursionError – If a descendent segment visits nodes to a depth that exceeds the configured max_recursion_depth.

type jsonpath_rfc9535.Node = tuple[object, tuple[int | str, ...], Node | None]¶

class jsonpath_rfc9535.NodeList(iterable=(), /)¶: A list of tuple nodes.

class jsonpath_rfc9535.JSONPathNode(node: Node)¶

A JSON-like value and its location in a JSON document.

Parameters:: node – A tuple node generated by the JSONPath evaluator.

value¶

The JSON-like value associated with this node.

Assigning to value will update this node and mutate source data too. Mutating source data after evaluating a query can invalidate child nodes. Use at your own risk.

Type:: object

location¶

Property names and array indexes that make up the normalized path to value.

Type:: tuple[str|int, …]

parent() → JSONPathNode | None¶: Return this node’s direct parent, or None if this is the document root.

path() → str¶: Return the normalized path to this node in source data.

class jsonpath_rfc9535.JSONPathNodeList(iterable=(), /)¶

A list of JSONPath nodes with some helper methods.

items() → list[tuple[str, object]]¶: Return a list of (path, value) pairs, one for each node in the list.

locations() → list[tuple[str | int, ...]]¶: Return the location of each node in this node list.

paths() → list[str]¶: Return a normalized paths for each node in this node list.

values() → list[object]¶: Return node values from this node list.

Function Extensions¶

type jsonpath_rfc9535.functions.ExpressionType = Literal[1, 2, 3]¶: An integer indicating a function extension argument type or return type.

class jsonpath_rfc9535.functions.FunctionExtension¶

The base class for all JSONPath function extensions.

abstract property arg_types: Sequence[ExpressionType]¶: Argument types expected by this filter function.

abstract property return_type: ExpressionType¶: The type of this function extension’s return value.

class jsonpath_rfc9535.functions.Count¶

class jsonpath_rfc9535.functions.Length¶

class jsonpath_rfc9535.functions.CachingRegexFunction(*, cache_capacity: int = 300, debug: bool = False, thread_safe: bool = False)¶

class jsonpath_rfc9535.functions.Match(*, cache_capacity: int = 300, debug: bool = False, thread_safe: bool = False)¶

class jsonpath_rfc9535.functions.Search(*, cache_capacity: int = 300, debug: bool = False, thread_safe: bool = False)¶

class jsonpath_rfc9535.functions.Value¶

Exceptions¶

class jsonpath_rfc9535.JSONPathError¶: The base class for all JSONPath exceptions.

class jsonpath_rfc9535.DetailedJSONPathError(msg: str, token: Token, source: str)¶

A JSONPath exception with contextual information.

detailed_message() → str¶: Return an error message formatted with extra context info.

property message: object¶: The exception’s error message if one was given.

class jsonpath_rfc9535.JSONPathNameError(msg: str, token: Token, source: str)¶: The exception raised when a function extension can not be resolved.

class jsonpath_rfc9535.JSONPathSyntaxError(msg: str, token: Token, source: str)¶: The exception raised due to a malformed JSONPath query.

class jsonpath_rfc9535.JSONPathIndexError(msg: str, token: Token, source: str)¶: The exception raised when an index selector is out of range.

class jsonpath_rfc9535.JSONPathTypeError(msg: str, token: Token, source: str)¶: The exceptions raised when a JSONPath query is not well typed.

class jsonpath_rfc9535.JSONPathRecursionError¶

The exception raised when a recursion limit is reached.

This could be raised at parse time if a JSONPath query contains deeply nested expressions. Or at query resolution time if max_recursion_depth is reached by the descendant segment (..).