API

GJSON module.

class gjson.GJSON(obj)

Bases: object

The GJSON class to operate on JSON-like objects.

Initialize the instance with the given object.

Examples

Use the gjson.GJSON class for more complex usage or to perform multiple queries on the same object:

>>> import gjson
>>> data = {'items': [{'name': 'a', 'size': 1}, {'name': 'b', 'size': 2}]}
>>> gjson_obj = gjson.GJSON(data)

Parameters:

obj (Any) – the object to query.

__str__()

Return the current object as a JSON-encoded string.

Examples

Converting to string a gjson.GJSON object returns it as a JSON-encoded string:

>>> str(gjson_obj)
'{"items": [{"name": "a", "size": 1}, {"name": "b", "size": 2}]}'

Return type:

str

Returns:

the JSON-encoded string representing the instantiated object.

get(query, *, quiet=False)

Perform a query on the instantiated object and return the resulting object.

Examples

Perform a query and get the resulting object:

>>> gjson_obj.get('items.#.size')
[1, 2]

Parameters:

• query (str) – the GJSON query to apply to the object.

• quiet (bool) – wheter to raise a gjson.GJSONError exception on error or just return None in case of error.

Raises:

gjson.GJSONError – on error if the quiet parameter is not True.

Return type:

Any

Returns:

the resulting object or None if the quiet parameter is True and there was an error.

getj(query, *, quiet=False)

Perform a query on the instantiated object and return the resulting object as JSON-encoded string.

Examples

Perform a query and get the resulting object as a JSON-encoded string:

>>> gjson_obj.getj('items.#.size')
'[1, 2]'

Parameters:

• query (str) – the GJSON query to apply to the object.

• quiet (bool) – wheter to raise a gjson.GJSONError exception on error or just return None in case of error.

Raises:

gjson.GJSONError – on error if the quiet parameter is not True.

Return type:

str

Returns:

the JSON-encoded string representing the resulting object or None if the quiet parameter is True and there was an error.

get_gjson(query, *, quiet=False)

Perform a query on the instantiated object and return the resulting object as a GJSON instance.

Examples

Perform a query and get the resulting object already encapsulated into a gjson.GJSON object:

>>> sizes = gjson_obj.get_gjson('items.#.size')
>>> str(sizes)
'[1, 2]'
>>> sizes.get('0')
1

Parameters:

• query (str) – the GJSON query to apply to the object.

• quiet (bool) – wheter to raise a gjson.GJSONError exception on error or just return None in case of error.

Raises:

gjson.GJSONError – on error if the quiet parameter is not True.

Return type:

GJSON

Returns:

the resulting object encapsulated as a gjson.GJSON object or None if the quiet parameter is True and there was an error.

register_modifier(name, func)

Register a custom modifier.

Examples

Register a custom modifier that sums all the numbers in a list:

>>> def custom_sum(options, obj, *, last):
...     # insert sanity checks code here
...     return sum(obj)
...
>>> gjson_obj.register_modifier('sum', custom_sum)
>>> gjson_obj.get('items.#.size.@sum')
3

Parameters:

• name (str) – the modifier name. It will be called where @name is used in the query. If two custom modifiers are registered with the same name the last one will be used.

• func (ModifierProtocol) – the modifier code in the form of a callable object that adhere to the gjson.ModifierProtocol.

Raises:

gjson.GJSONError – if the provided callable doesn’t adhere to the gjson.ModifierProtocol.

Return type:

None

exception gjson.GJSONError

Bases: Exception

Raised by the gjson module on error while performing queries or converting to JSON.

class gjson.GJSONObj(obj, query, *, custom_modifiers=None)

Bases: object

A low-level class to perform the GJSON query on a JSON-like object.

Initialize the instance with the starting object and query.

Examples

Client code should not need to instantiate this low-level class in normal circumastances:

>>> import gjson
>>> data = {'items': [{'name': 'a', 'size': 1}, {'name': 'b', 'size': 2}]}
>>> gjson_obj = gjson.GJSONObj(data, 'items.#.size')

Parameters:

• obj (Any) – the JSON-like object to query.

• query (str) – the GJSON query to apply to the object.

• custom_modifiers (Optional[dict[str, ModifierProtocol]]) – an optional dictionary with the custom modifiers to load. The dictionary keys are the names of the modifiers and the values are the callables with the modifier code that adhere to the gjson.ModifierProtocol protocol.

Raises:

gjson.GJSONError – if any provided custom modifier overrides a built-in one or is not callable.

__str__()

Return the JSON string representation of the object, based on the query parameters.

Examples

Returns the resulting object as a JSON-encoded string:

>>> str(gjson_obj)
'[1, 2]'

Raises:

gjson.GJSONError – on error.

Return type:

str

Returns:

the JSON encoded string.

classmethod builtin_modifiers()

Return the names of the built-in modifiers.

Return type:

set[str]

Returns:

the names of the built-in modifiers.

get()

Perform the query and return the resulting object.

Examples

Returns the resulting object:

>>> gjson_obj.get()
[1, 2]

Raises:

gjson.GJSONError – on error.

Return type:

Any

Returns:

the resulting object.

exception gjson.GJSONParseError(*args, query, position)

Bases: GJSONError

Raised when there is an error parsing the query string, with nicer representation of the error.

Initialize the exception with the additional data of the query part.

Parameters:

• *args (Any) – all positional arguments like any regular exception.

• query (str) – the full query that generated the parse error.

• position (int) – the position in the query string where the parse error occurred.

__str__()

Return a custom representation of the error.

Return type:

str

Returns:

the whole query string with a clear indication on where the error occurred.

class gjson.ModifierProtocol(*args, **kwargs)

Bases: Protocol

Callback protocol for the custom modifiers.

__call__(options, obj, *, last)

To register a custom modifier a callable that adhere to this protocol must be provided.

Examples

Register a custom modifier that sums all the numbers in a list:

>>> import gjson
>>> data = [1, 2, 3, 4, 5]
>>> def custom_sum(options, obj, *, last):
...     # insert sanity checks code here
...     return sum(obj)
...
>>> gjson_obj = gjson.GJSON(data)
>>> gjson_obj.register_modifier('sum', custom_sum)
>>> gjson_obj.get('@sum')
15

Parameters:

• options (dict[str, Any]) – a dictionary of options. If no options are present in the query the callable will be called with an empty dictionary as options. The modifier can supports any number of options, or none.

• obj (Any) – the current object already modifier by any previous parts of the query.

• last (bool) – True if the modifier is the last element in the query or False otherwise.

Raises:

Exception – any exception that might be raised by the callable is catched by gjson and re-raised as a gjson.GJSONError exception to ensure that the normal gjson behaviour is respected according to the selected verbosity (CLI) or quiet parameter (Python library).

Return type:

Any

Returns:

the resulting object after applying the modifier.

gjson.__version__: str = '1.1.0'

the version of the current gjson module.

Type:

str

gjson.get(obj, query, *, as_str=False, quiet=False)

Quick accessor to GJSON functionalities exposed for simplicity of use.

Examples

Import and directly use this quick helper for the simpler usage:

>>> import gjson
>>> data = {'items': [{'name': 'a', 'size': 1}, {'name': 'b', 'size': 2}]}
>>> gjson.get(data, 'items.#.size')
[1, 2]

Parameters:

• obj (Any) – the object to query. It must be accessible in JSON-like fashion so it must be an object that can be converted to JSON.

• query (str) – the query string to evaluate to extract the data from the object.

• as_str (bool) – if set to True returns a JSON-encoded string, a Python object otherwise.

• quiet (bool) – on error, if set to True, will raises an GJSONError exception. Otherwise returns None on error.

Return type:

Any

Returns:

the resulting object.