‘jsondata.jsondataserializer’ - Module

Core features for serialization of structured JSON based in-memory data. This comprises the load of a model from a JSON file, and the incremental addition and removal of branches by loading additional JSON modules. The resulting data could be saved for later reuse, either as a complete tree, or by modular parts as branches. The implementation is based on the standard packages json and jsonschema.

This module uses either preloaded JSON data, or loads the data from files.

Additional modification of the data is supported the modules jsondata and jsonpatch, analysis and comparison by the module jsondatadiff.

Module

Basic features for the persistence of JSON based in-memory data.

  • import and export of JSON data from/into files
  • modular import and export of JSON branches from/into files
  • validation by JSON schema

JSONDataSerializer

class jsondata.jsondataserializer.JSONDataSerializer(jdata, **kargs)[source]

Persistency for JSONData.

Attributes

  • JSONDataSerializer.data

    In-memory JSON data, see JSONData.data.

  • JSONDataSerializer.schema

    In-memory JSON schema, see JSONData.schema.

Methods

__init__

JSONDataSerializer.__init__(jdata, **kargs)[source]

Creates a serializable instance of JSONData, optionally loads and validates a JSON definition.

Args:
jdata:
The initial data of current instance, see JSONData
kargs:

Keywords are also passed to JSONData.

datafile:
Filepathname of JSON data file, when provided a further search by pathlist, filelist, and filepathlist is suppressed. Therefore it has to be a valid filepathname.
mode:

The mode of JSON processing:

mode := (
     MJ_RFC4627
   | MJ_RFC7493  # currently not supported, mapped to RFC7159
   | MJ_RFC7159
   | MJ_RFC8259
   | MJ_ECMA404  # same as RFC8259
)

default := MJ_RFC7159

schemafile:
Filepathname of JSONschema file.
schema:
Could be used instead of schemafile, see JSONData.
validator:
See JSONData.
Returns:
Results in an initialized object.
Raises:

NameError

JSONDataSourceFileError

JSONDataAmbiguityError

JSONDataValueError

jsonschema.ValidationError

jsonschema.SchemaError

json_export

JSONDataSerializer.json_export(datafile, sourcenode=None, **kargs)[source]

Exports current data into a file.

Args:
datafile:
File name for the exported data.
sourcenode:

Base of sub-tree for export. None for complete JSON document.

default := self.data

kargs:
force:
Forces the overwrite of existing files.
pretty:

Defines the syntax format of the data.

pretty := (
     True     # tree view
   | False    # all in one line
)

When set, the value is fetched from self.indent.

default := True

Returns:
When successful returns ‘True’, else returns either ‘False’, or raises an exception.
Raises:
JSONDataTargetFileError:

json_import

JSONDataSerializer.json_import(datafile, targetnode=None, key=None, **kargs)[source]

Imports and validates data from a file.

The schema and validator for the imported data could be set independent from the schema of the main data.

Args:
datafile:

JSON data file name containing the subtree for the target branch.

datafile := <filepathname>
targetnode:

Target container for the inclusion of the loaded branch.

targetnode := (
    JSONPointer                  # [RFC6901] or [RELPOINTER]
    | <rfc6901-string>           # [RFC6901]
    | <relative-pointer-string>  # [RELPOINTER]
    | <pointer-items-list>       # non-URI-fragment pointer path items of [RFC6901]
    )

default := self.data

key:

The optional index/key-hook within the targetnode,

default:= None

kargs:
mechanic:

The import mechanic. Selects either the RFC6902 conform branch_add, or the flexible mapping by branch_superpose. The latter is more suitable for the application of modular templates.

mechanic := (
     B_ADD  |  'add'   # branch_add
   | B_AND  |  'and'   # branch_superpose(map=B_AND)
   | B_OR   |  'or'    # branch_superpose(map=B_OR)
   | B_XOR  |  'xor'   # branch_superpose(map=B_XOR)
)
matchcondition:
Defines the criteria for comparison of present child nodes in the target container. The value is a list of criteria combined by logical AND. The criteria may vary due to the requirement and the type of applied container.
schema:

JSON-Schema for validation of the subtree/branch.

default := self.schema # the pre-loaded schema

schemafile:

JSON-Schema filename for validation of the subtree/branch.

default := self.schema # the pre-loaded schema

subpointer:

The path of the sub-tree of the serialized document to be imported.

default := ‘’ # whole serialized document

validator:

Sets schema validator for the data file. Current release relies on jsonschema, which supports at the time of writing draft-03 and draft-04.

The values are:

validator := (
      MS_DRAFT3           | 'draft3'
    | MS_DRAFT4           | 'draft4'
    | MS_ON               | 'on'
    | MS_OFF              | 'off'
    | MODE_SCHEMA_DEFAULT | 'default'
)

default:= MS_OFF

Returns:
When successful returns ‘True’, else returns either ‘False’, or raises an exception.
Raises:

JSONDataError

JSONDataValueError

JSONDataSourceFileError:

dump_data

JSONDataSerializer.dump_data(pretty=True, **kargs)[source]

Dumps structured data by calling json.dumps().

Args:
pretty:
Activates pretty printer for treeview, else flat.
kargs:

The remaining keyword arguments are passed through to json.dumps().

ensure_ascii:

See json_dumps.

default := False

indent:
Sets indent when pretty is True.
sort_keys:

Sorts keys.

default := False

sourcefile:

Loads data from ‘sourcefile’ into ‘source’.

default := None

source:

Prints data within ‘source’.

default := self.data

Returns:
When successful returns the dump string, else either ‘None’, or raises an exception.
Raises:

JSONDataAmbiguityError:

forwarded from ‘json’

dump_schema

JSONDataSerializer.dump_schema(pretty=True, **kargs)[source]

Dumps structured schema by calling json.dumps().

Args:
pretty:
Activates pretty printer for treeview, else flat.
kargs:

The remaining keyword arguments are passed through to json.dumps().

ensure_ascii:

See json_dumps.

default := False

indent:
Sets indent when pretty is True.
sort_keys:

Sorts keys.

default := False

sourcefile:

Loads schema from ‘sourcefile’ into ‘source’.

default := None

source:

Prints schema within ‘source’.

default := self.schema

Returns:
When successful returns the dump string, else either ‘None’, or raises an exception.
Raises:

JSONDataAmbiguityError:

forwarded from ‘json’

set_schema

JSONDataSerializer.set_schema(schemafile=None, targetnode=None, **kargs)[source]

Sets schema or inserts a new branch into the current schema. The main schema(targetnode==None) is the schema of the current instance. Additional branches could be added by importing the specific schema definitions. These could either kept volatile as a temporary runtime extension, or stored persistently.

Args:
schemafile:
JSON-Schema filename for validation of the subtree/branch, see also kargs[‘schema’].
targetnode:
Target container hook for the inclusion of the loaded branch.
kargs:
schema:

In-memory JSON-Schema as an alternative to schemafile, when provided the ‘schemafile’ is ignored.

default:=None

persistent:

Stores the ‘schema’ persistently into ‘schemafile’ after the completion of update, requires a valid ‘schemafile’.

default:=False

Returns:
When successful returns ‘True’, else returns either ‘False’, or raises an exception.

Raises:

JSONDataError

JSONDataSourceFileError

JSONDataValueError

Exceptions

exception jsondata.JSONDataAmbiguityError(requested, *sources)[source]

Error ambiguity of provided parameters.

exception jsondata.JSONDataError(*arg)[source]

base Exception.

exception jsondata.JSONDataModeError(*arg)[source]

Type error of source file content.

exception jsondata.JSONDataParameterError(*arg)[source]

Erroneous parameters.

exception jsondata.JSONDataSourceFileError(*arg)[source]

Error on read of a source file.

exception jsondata.JSONDataTargetFileError(*arg)[source]

Error on writing a file.

exception jsondata.JSONDataValueError(*arg)[source]

Error on a value.