jsonyx.Manipulator

class jsonyx.Manipulator(*, allow=NOTHING, use_decimal=False)

Bases: object

A configurable JSON manipulator.

Added in version 2.0.

Parameters:

• allow (Container[str], default: NOTHING) – the JSON deviations from jsonyx.allow

• use_decimal (bool, default: False) – use decimal.Decimal instead of float

apply_filter(nodes, query)

Apply a JSON filter query to a node or a list of nodes.

Parameters:

• nodes (_Node | list[_Node]) – a node or a list of nodes

• query (str) – a JSON filter query

Raises:

• IndexError – if an index is out of range

• JSONSyntaxError – if the filter query is invalid

• KeyError – if a key is not found

• TypeError – if a value has the wrong type

Returns:

list[_Node] – the filtered list of nodes

Example:

>>> import jsonyx as json
>>> manipulator = json.Manipulator()
>>> obj = None
>>> root = [obj]
>>> node = root, 0  # pointer to obj
>>> assert manipulator.apply_filter(node, "@ == null")

apply_patch(obj, patch)

Apply a JSON patch to a Python object.

Parameters:

• obj (Any) – a Python object

• patch (_Operation | list[_Operation]) – a JSON patch

Raises:

• AssertionError – if an assertion fails

• IndexError – if an index is out of range

• JSONSyntaxError – if a query is invalid

• KeyError – if a key is not found

• TypeError – if a value has the wrong type

• ValueError – if a value is invalid

Returns:

Any – the patched Python object

Example:

>>> import jsonyx as json
>>> manipulator = json.Manipulator()
>>> manipulator.apply_patch([1, 2, 3], {"op": "del", "path": "$[1]"})
[1, 3]

Tip

Using a filter instead of an index is more robust.

load_query_value(s)

Deserialize a JSON query value to a Python object.

Parameters:

s (str) – a JSON query value

Raises:

JSONSyntaxError – if the query value is invalid

Returns:

Any – a Python object

Example:

>>> import jsonyx as json
>>> manipulator = json.Manipulator()
>>> manipulator.load_query_value("'~'foo'")
"'foo"

paste_values(current_nodes, values, operation)

Paste value to a node or values to a list of nodes.

Parameters:

• current_nodes (_Node | list[_Node]) – a node or a list of nodes

• values (Any | list[Any]) – a value or a list of values

• operation (_Operation) – a JSON copy or move operation

Raises:

• IndexError – if an index is out of range

• JSONSyntaxError – if a query is invalid

• KeyError – if a key is not found

• TypeError – if a value has the wrong type

• ValueError – if a value is invalid

Example:

>>> import jsonyx as json
>>> manipulator = json.Manipulator()
>>> obj = [1, 2, 3]
>>> root = [obj]
>>> node = root, 0  # pointer to obj
>>> manipulator.paste_values(node, 4, {"mode": "append"})
>>> root[0]
[1, 2, 3, 4]

select_nodes(nodes, query, *, allow_slice=False, relative=False)

Select nodes from a node or a list of nodes.

Parameters:

• nodes (_Node | list[_Node]) – a node or a list of nodes

• query (str) – a JSON select query

• allow_slice (bool, default: False) – allow slice

• relative (bool, default: False) – query must start with "@" instead of "$"

Raises:

• IndexError – if an index is out of range

• JSONSyntaxError – if the select query is invalid

• KeyError – if a key is not found

• TypeError – if a value has the wrong type

Returns:

list[_Node] – the selected list of nodes

Example:

>>> import jsonyx as json
>>> manipulator = json.Manipulator()
>>> obj = [1, 2, 3, 4, 5, 6]
>>> root = [obj]
>>> node = root, 0  # pointer to obj
>>> for target, key in manipulator.select_nodes(node, "$[@ > 3]"):
...     target[key] = None
...
>>> root[0]
[1, 2, 3, None, None, None]