API¶
GJSON module.
- gjson.get(obj, query, *, as_str=False, quiet=False)[source]¶
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 toTrue
returns a JSON-encoded string, a Python object otherwise.quiet (
bool
) – on error, if set toTrue
, will raises an GJSONError exception. Otherwise returnsNone
on error.
- Return type:
- Returns:
the resulting object.
- class gjson.GJSON(obj)[source]¶
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__()[source]¶
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:
- Returns:
the JSON-encoded string representing the instantiated object.
- get(query, *, quiet=False)[source]¶
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 agjson.GJSONError
exception on error or just returnNone
in case of error.
- Raises:
gjson.GJSONError – on error if the quiet parameter is not
True
.- Return type:
- Returns:
the resulting object or
None
if thequiet
parameter isTrue
and there was an error.
- getj(query, *, quiet=False)[source]¶
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 agjson.GJSONError
exception on error or just returnNone
in case of error.
- Raises:
gjson.GJSONError – on error if the quiet parameter is not
True
.- Return type:
- Returns:
the JSON-encoded string representing the resulting object or
None
if thequiet
parameter isTrue
and there was an error.
- get_gjson(query, *, quiet=False)[source]¶
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 agjson.GJSONError
exception on error or just returnNone
in case of error.
- Raises:
gjson.GJSONError – on error if the quiet parameter is not
True
.- Return type:
- Returns:
the resulting object encapsulated as a
gjson.GJSON
object orNone
if thequiet
parameter isTrue
and there was an error.
- register_modifier(name, func)[source]¶
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 thegjson.ModifierProtocol
.
- Raises:
gjson.GJSONError – if the provided callable doesn’t adhere to the
gjson.ModifierProtocol
.- Return type:
- exception gjson.GJSONError[source]¶
Bases:
Exception
Raised by the gjson module on error while performing queries or converting to JSON.
- exception gjson.GJSONParseError(*args, query, position)[source]¶
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:
- class gjson.ModifierProtocol(*args, **kwargs)[source]¶
Bases:
Protocol
Callback protocol for the custom modifiers.
- __call__(options, obj, *, last)[source]¶
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 orFalse
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) orquiet
parameter (Python library).- Return type:
- Returns:
the resulting object after applying the modifier.
- class gjson.GJSONObj(obj, query, *, custom_modifiers=None)[source]¶
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 thegjson.ModifierProtocol
protocol.
- Raises:
gjson.GJSONError – if any provided custom modifier overrides a built-in one or is not callable.
- get()[source]¶
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:
- Returns:
the resulting object.
- __str__()[source]¶
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:
- Returns:
the JSON encoded string.