Class JSONPatch

List of patch tasks.

Args:
    **p**:
        Patch list. ::

           p := (
                JSONPatch
              | <list-of-patch-items>
           )

    kargs:
        **replace**:
            Replace masked characters in *target* specification. ::

               replace := (
                    True    # replaces rfc6901 escape sequences: ~0 and ~1
                  | False   # omit unescaping
               )

            .. note::
            
               Match operations are proceeded literally, thus the
               escaped characters should be consistent,
               see rfc6901, Section 3.

            default := False

Returns:
    self.

Raises:
    pass-through

Overrides: object.__init__

Creates and adds patch job to the task queue.

Args:
    **x**:
        Extension of pathc job, eithe a *JSONPatch*,
        or a *JSONPatchItem*.

Returns:
    Returns a patch job, or raises Exception. 

Raises:
    JSONDataPatchError

Evaluates the related task for the provided index.

Args:
    **x**: 
        Task index.

    **jdata**: 
        JSON data the task has to be 
        applied on.

Returns:
    Returns a tuple of: ::

       (n, lerr): 

       n:    number of present active entries
       lerr: list of failed entries

Raises:
    JSONDataPatchError:

Compares this pointer with x.

Args:
    **x**:
        A valid Pointer.

Returns:
    *True* or *False*

Raises:
    JSONPointerError

Support of slices, for 'iterator' refer to self.__iter__.

#. self[key]

#. self[i:j:k]

#. x in self

#. for x in self

Removes the patch job from the task queue in place. 

Removes one of the following type(x) variants:

    *int*:
        The patch job with given index.

    *JSONPatchItem*:
        The first matching entry from 
        the task queue. 

Args:
    **x**:
        Item to be removed. ::

           x := (
                int
              | JSONPatchItem
           ) 

Returns:
    Returns resulting list without x.

Raises:
    JSONDataPatchError:

Compares this pointer with x.

Args:
    **x**:
        A valid Pointer.

Returns:
    *True* or *False*

Raises:
    JSONPointerError

Prints the representation format of a JSON patch list.

Overrides: object.__repr__

Prints the display format.

Overrides: object.__str__

Removes the patch job from the task queue. 

Removes one of the following type(x) variants:

    *int*:
        The patch job with given index.

    *JSONPatchItem*:
        The first matching entry from 
        the task queue. 

Args:
    **x**:
        Item to be removed. ::

           x := (
                int
              | JSONPatchItem
           ) 

Returns:
    Returns resulting list without x.

Raises:
    JSONDataPatchError:

Applies the JSONPatch task.

Args:
    **jsondata**:
        JSON data the joblist has to be applied on.

Returns:
    Returns a tuple of: ::

       (n, lerr): 

       n:    number of present active entries
       lerr: list of failed entries

Raises:
    JSONDataPatchError:

Gets the reference to a single patch item.

Args:
    **x**:
        Requested item. ::

           x := (
                int
              | JSONPatchItem
           ) 

           int:           index of patch item
           JSONPatchItem: the reference to the patch item
    
Returns:
    The selected patch item.

Raises:
    None

Gets a list of references of patch items.

Args:
    args:
        Requested items. ::

           *args := (
              <item>
              | <item-list>
              | None
           )
           item-list := <item>[, <item-list>]
           item := (
                int
              | JSONPatchItem
           )
           None := "all items of the current patch list"

           int:           index of patch item
           JSONPatchItem: the reference to the patch item
    
    kargs:
        **idxlist**:
            Print with index: ::

               idxlist := (
                    True     # format: [{<index>: <JSONPatchItem>}]
                  | False    # format: [<JSONPatchItem>]
               )

        **copydata**:
            Creates a copy of each resulting item. ::

               copydata := (C_DEEP | C_SHALLOW | C_REF)

            default := C_REF  # no copy
        
Returns:
    A list of the selected patch items.

Raises:
    None

Gets the resulting logical JSON data structure
constructed from the patch items of the current set.

Args:
    args:
        Requested items. ::

           *args := (
              <item>
              | <item-list>
              | None
           )
           item-list := <item>[, <item-list>]
           item := (
                int
              | JSONPatchItem
           )
           None := "all items of the current patch list"

           int:           index of patch item
           JSONPatchItem: the reference to the patch item
    
    kargs:
        **data**:
            An optional JSON data structure, when provided
            the actual data as selected by the patch list
            is returned. Else the paths only.

            default := None

        **scope**:
            Defines the source scope of the data structure. ::

               scope := (
                    "in"   # input data, e.g. source for "copy"
                  | "out"  # output data, e.g. target for "copy
               )

            default := "out"

Returns:
    The combined list of the selected patch items contained
    in an object JSONData.

Raises:
    None

Exports the current task list.

Args:
    **patchfile**:
        JSON patch for export.

    **schema**:
        JSON-Schema for validation of the patch list.

    kargs:
        **validator**: [default, draft3, off, ]
            Sets schema validator for the data file.
            The values are: ::

               default = validate
               draft3  = Draft3Validator
               off     = None

            default:= validate

        **pretty**:
            If True exports as tree format, 
            else all as one line.

Returns:
    When successful returns 'True', else raises an exception.

Raises:
    JSONDataPatchError:

Imports a task list.

Args:
    **patchfile**:
        JSON patch filename containing the list of patch operations.

    **schemafile**:
        JSON-Schema filename for validation of the patch list.

    kargs:
        **replace**:
            Replace masked characters in *target* specification. ::

               replace := (
                    True    # replaces rfc6901 escape sequences: ~0 and ~1
                  | False   # omit unescaping
               )

            .. note::
            
               Match operations are proceeded literally, thus the
               escaped characters should be consistent,
               see rfc6901, Section 3.

            default := False

        **validator**:
            Sets schema validator for the data file.
            Curren 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 raises an exception.

Raises:
    JSONDataPatchError: