API Reference

Schema Loading

jsonbp.load_file(filepath, **kwargs)

Loads a JsonBlueprint from a file.

On success, the returned instance is associated with the absolute path of the argument file, and subsequent calls of this function to the same file will be presented with the same instance, unless invalidate_cache() is invoked.

Parameters:

• filepath (str) – schema file to load.

• **custom_types (str[]) – list of directories to scan for primitive types.

Returns:

the generated blueprint

Return type:

JsonBlueprint

Raises:

SchemaViolation – when the schema is malformed or there are inconsistencies in its relations

jsonbp.load_string(schema, **kwargs)

Loads a JsonBlueprint from the contents of a string.

Parameters:

• schema (str) – schema definition.

• **custom_types (str[]) – list of directories to scan for primitive types.

Returns:

the generated blueprint

Return type:

JsonBlueprint

Raises:

SchemaViolation – when the schema is malformed or there are inconsistencies in its relations

jsonbp.invalidate_cache()

Clears associations between files and existing JsonBlueprint instances.

This forces new load_file() invocations to effectively parse the files instead of returning a cached result (Useful when your schema file changed and needs to be refreshed).

Deserialization/Serialization

class jsonbp.JsonBlueprint(primitive_types)

Class to serialize Python objects to JSON strings and vice-versa.

choose_root(root_type, as_array=False, min_array_length=None, max_array_length=None)

Selects or changes the root element of a blueprint.

This function allows you to create a derivative JsonBlueprint instance, overwriting the root type (or selecting one, if none is defined). The original source JsonBlueprint instance remains unchanged.

Parameters:

• root_type (str) – name of the type to be used as root. as_array (bool): whether the chosen root is an array or not of the selected type.

• min_array_length (int) – if set as array, minimum size that the root must be.

• max_array_length (int) – if set as array, maximum size that the root can be.

Returns:

A new blueprint, with the root selected or replaced.

Raises:

SchemaViolation – when the given type doesn’t exist within the blueprint context.

deserialize(contents)

Attempts to deserialize a JSON string into a Python object.

The returned tuple’s first element indicates whether the deserialization was successful. When deserialization succeeds the respective Python data will be the second element. Conversely, when a problem is found the first element will be False and the second element will be an instance of DeserializationError.

Parameters:

contents (str) – JSON string to deserialize into Python data.

Returns:

Tuple[bool, object]

serialize(content)

Attempts to serialize a Python object into a JSON string.

Parameters:

content (object) – Python data to be transformed into a JSON string.

Returns:

the resulting JSON string

Raises:

SerializationException – when a field is missing in the Python object or some field has an incompatible type.

class jsonbp.DeserializationError(error_id, **context)

Error returned from failed deserializations.

localize(localization_priority=None)

Maps the error to possible localizations.

Parameters:

localization_priority ([str]) – list of locale codes, in order of priority, to attempt to localize the issue. If no list is passed, it will use the language defined by use_default_language().

Returns:

the localized issue with the JSON string.

Localization Setup

jsonbp.load_translation(filename, language)

Includes languages to be used in deserialization issues localization.

This function appends or overwrites languages available for use in the method DeserializationError.localize(). jsonbp comes with some builtin translations already, check its source if unsure.

Parameters:

• filename (str) – path to the ini file.

• language (str) – language code that that file corresponds to.

Raises:

IOError – When filename cannot be opened for reading.

Returns:

Nothing

jsonbp.use_default_language(language)

Defines which language to use to map errors by default.

This language will be applied when no languages are specified in the DeserializationError.localize() method. When jsonbp starts, this language is set to American English (en-US). If he language code passed is not available, it’ll also fallback to American English.

Parameters:

language (str) – Language code to set

Returns:

Nothing

Exceptions

class jsonbp.SchemaViolation

class jsonbp.SerializationException