jsonobject

Subpackages

• fields

Flexible data structures, ideal to specify nested project configurations.

class JsonObject(mapping=None, **kwargs)

Bases: object

Flexible Dataclass-like data structure with enforced type schema.

This class is not meant to ever be instantiated directly. Rather, inherit from it, and specify fields as type-annotated class variables, potentially giving also default values. Values for non-default fields must be provided on instantiation in the form of a JSON string, a dictionary-like object, or keyword arguments. The handling of additional fields can be specified via boolean class keywords ignore_extra (defaults to False) and raise_extra (defaults to True).

By default, JSON fields with a None value are ignored and treated as not being present. To actually set fields to None (and, potentially, overwrite defaults), the class keyword respect_none needs to be set to True on subclass definition. Note, however, that type annotations must also tolerate None values, which is realized by wrapping existing types into Maybe instances.

The resulting object behaves in many ways like a dictionary, allowing dictionary-style, but also object-style access to data fields. Attributes of nested instances can be accessed dictionary-style (i.e., with the square-bracket accessor) with a dot.separated key.

Parameters:

• mapping (dict, str, bytes, or Series, optional) – Dictionary with string keys, JSON string/bytes, or pandas Series. Defaults to an empty dictionary.

• **kwargs – Can be any value or, for nested structures, again a dictionary with string keys or a JSON string/bytes or a pandas Series. Keyword arguments will override values already present in the mapping.

Raises:

• ValidationErrors – ExceptionGroup containing any number of the following exceptions.

• ParseError – If the (keyword) arguments cannot be parsed into a dictionary with string keys and if non-default fields are neither given in the mapping nor in the keyword arguments.

• CastError – If the dictionary values cannot be cast into the types specified in the schema.

Warning

This class is rather heavy, so do not use it to, e.g., wrap JSON payloads in high-throughput low-latency web services!

See also

fields.Maybe

__call__(mapping=None, **kwargs)

Update one or more (nested) fields with mapping and kwargs.

Parameters:

• mapping (dict, str, bytes, or Series, optional) – Dictionary with string keys, JSON string/bytes, or pandas Series. Defaults to an empty dictionary.

• **kwargs – Can be any value or, for nested structures, again a dictionary with string keys or a JSON string/bytes or a pandas Series. Keyword arguments will override values already present in the mapping.

Returns:

A new instance of self with updated values.

Return type:

JsonObject

Raises:

• ValidationErrors – ExceptionGroup containing any number of the following exceptions.

• ParseError – If the (keyword) arguments cannot be parsed into a dictionary with string keys.

• CastError – If the dictionary values cannot be cast into the types specified in the schema.

property as_dtype

Representation in a cell of a pandas data frame.

property as_json

JSON-serializable dictionary representation.

property as_series

Representation as a pandas series.

get(item, default=None)

Get (nested) attribute by (dot.separated) name or default.

keys()

Attribute names as dictionary keys.

class JsonObjects(items=(), *args)

Bases: Generic

List-like container for JSON-serializable dictionaries.

This class is not meant to ever be instantiated directly. Rather, inherit from it, and specify a subclass of JsonObject with the item_type class keyword on sub-classing.

Parameters:

• items (list, optional) – List of JSON-serializable dictionaries. Defaults to an empty list.

• *args – Additionally, any number of JSON-serializable dictionaries with the schema specified by the item_type can be provided. These will be appended to the items.

Raises:

• ParseError – If the constructor argument(s) can not be parsed as a list of dictionaries.

• SchemaError – If item_type is not a subclass of JsonObject.

Warning

This class is rather heavy, so do not use it to, e.g., wrap JSON payloads in high-throughput low-latency web services!

__call__(mapping=None, **kwargs)

Update one or more (nested) fields within each item.

Parameters:

• mapping (dict or str, optional) – Dictionary with string keys, JSON string/bytes, or pandas Series. Defaults to an empty dictionary.

• **kwargs – Can be any value or, for nested structures, again a dictionary with string keys or a JSON string/bytes or a pandas Series. Keyword arguments will override values already present in the mapping.

Returns:

A new instance of self with updated fields in each item.

Return type:

JsonObjects

Raises:

• ParseError – If the (keyword) arguments cannot be parsed into a dictionary with string keys.

• CastError – If the dictionary values cannot be cast into the types specified in the schema of the item_type.

property as_df

Representation as a pandas data frame.

property as_dtype

Representation in the cell of a pandas data frame.

property as_json

JSON-serializable representation.