Class JSONDataSerializer

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

Overrides: object.__init__

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:

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.

        .. parsed-literal::

           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:

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'

Overrides: jsondata.JSONData.dump_data

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'

Overrides: jsondata.JSONData.dump_schema

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

Overrides: jsondata.JSONData.set_schema