Class JSONPointer

Normalizes and stores a JSONPointer. The internal
representation depends on the type.

* absolute path:

  A list of ordered items representing
  the path items.

* relative path:

  Relative paths in addition provide
  a positive numeric offset of outer
  containers [RELPOINTER]_.

Processes the ABNF of a JSON Pointer from RFC6901
and/or a relative JSON Pointer(draft 2018).

Attributes:
    For details see manuals.

    * *isfragment*
    * *isrel*
    * *raw*
    * *start*
    * *startrel*

Args:
    **ptr**:
        A JSONPointer to be represented by this object. The
        supported formats are:

        .. parsed-literal::

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

        JSONPointer:
            A valid object, is copied into this object,
            see 'deep'. Supports *rfc6901* [RFC6901]_
            and *relative* pointers [RELPOINTER]_.

        *rfc6901-string*:
            A string i accordance to RFC6901 [RFC6901]_.

        *relative-pointer-string*:
            Draft standard, currently
            experimental [RELPOINTER]_.

        *pointer-items-list*:
            Expects a path list, where each item
            is processed for escape and unquote.
            Supports *rfc6901* pointers [RFC6901]_.

        Containing:

        * absolute JSON Pointer
        * relative JSON Pointer, requires the
          keyword argument *startrel*

    kargs:

        **debug**:
            Enable debugging.

        **deep**:
            Applies for copy operations on structured data
            'deep' when 'True', else 'shallow' only.
            Flat data types are copied by value in any case.

        **node**:
            Force to set the pointed node in the internal cache.

        **replace**:
            Replace masked characters, is applied onto the *ptr*
            parameter only. For the replacement of *startrel*
            create and pass an object *JSONPointer*. ::

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

            .. note::

               Match operations on address strings are proceeded literally,
               thus the escaped characters should be consistent,
               see rfc6901, Section 3.

            default := False

        **startrel**:
            Start node for relative JSON Pointers. Is evaluated
            only in combination with a relative path, else
            ignored. ::

               startrel := (
                    JSONPointer           # supports [RFC6901]_ and [RELPOINTER]_
                  | <rfc6901-string>      # supports [RFC6901]_
                  | <rel-pointer-string>  # supports only relative to whole-document '0/...'
               )

            default := ""  # whole document

Returns:
    When successful returns *True*, else returns either *False*, or
    raises an exception.
    Success is the complete addition only, thus one failure returns
    *False*.

Raises:
    JSONPointerError:

Returns: new empty list

Overrides: object.__init__

Appends a Pointer to self.

Args:
    **x**:
        A valid JSONPointer of type: ::

           x := (
              JSONPointer - fragment
              | JSONPointer - relative-pointer
              | relative pointer
              )

Returns:
    A new object of JSONPointer

Raises:
    JSONPointerError:

Overrides: list.__add__

Evaluates the pointer value on the document.

Args:
    **x**:
        A valid JSON document.

Returns:
    The resulting pointer value.

Raises:
    JSONPointerError

x.__delattr__('name') <==> del x.name

Overrides: object.__delattr__

(inherited documentation)

Compares this pointer with x.

Args:
    **x**:
        A JSONPointer object.

Returns:
    True or False

Raises:
    JSONPointerError

Overrides: list.__eq__

Checks containment(>=) of another pointer within this.

The weight of contained entries is the criteria, though
the shorter is the bigger. This is true only in case of
a containment relation.

The number of equal path pointer items is compared.

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

Returns:
    True or False

Raises:
    JSONPointerError:

Overrides: list.__ge__

Checks containment(>) of another pointer or object within this.

The number of equal items is compared.

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

Returns:
    True or False

Raises:
    JSONPointerError:

Overrides: list.__gt__

Add in place x to self, appends a path.

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

Returns:
    'self' with updated pointer attributes

Raises:
    JSONPointerError:

Overrides: list.__iadd__

Checks containment(<=) of this pointer within another.

The number of equal items is compared.

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

Returns:
    True or False

Raises:
    JSONPointerError:

Overrides: list.__le__

Checks containment(<) of this pointer within another.

The number of equal items is compared.

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

Returns:
    True or False

Raises:
    JSONPointerError:

Overrides: list.__lt__

Compares this pointer with x.

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

Returns:
    True or False

Raises:
    JSONPointerError

Overrides: list.__ne__

Adds itself as the right-side-argument to the left.

This method appends 'self' to a path fragment on the left.
Therefore it adds the path separator on it's left side only.
The left side path fragment has to maintain to be in
accordance to RFC6901 by itself.

Once 'self' is added to the left side, it terminates it's
life cycle. Thus another simultaneous add operation is
handled by the resulting other element.

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

Returns:
    The updated input of type 'x' as 'x+S(x)'

Raises:
    JSONPointerError:

Returns the attribute self.__raw, which is the raw input JSONPointer.

Args:
    None

Attributes:
    Evaluates *self.__isrel*

Returns:
    For relative paths: ::
       (<start-offset>, <pointer>)

       start-offset := [<self.startrel>]
       pointer := [<self>]

    For RFC6901 paths: ::

       <pointer>

       pointer := [<self>]

Raises:
    pass-through

Overrides: object.__repr__

x.__setattr__('name', value) <==> x.name = value

Overrides: object.__setattr__

(inherited documentation)

Returns the string for the processed path.

Args:
    None

Attributes:
    Evaluates *self.__isrel*

Returns:
    For relative paths: ::
       (<start-offset>, <pointer>)

       start-offset := [<self.startrel>]
       pointer := [<self>]

    For RFC6901 paths: ::

       <pointer>

       pointer := [<self>]

Raises:
    pass-through

Overrides: object.__str__

Checks the existence of the corresponding node
within the JSON document.

Args:
    **jsondata**:
        A valid JSON data node.

    **parent**:
        If *True* returns the parent node of the pointed value.

Returns:
    True or False

Raises:
    JSONPointerError:

    pass-through

Creates a copy of self.

Args:
    None

    kargs:
        **deep**:
            When *True* creates a deep copy,
            else shallow.

Returns:
    A copy of self.

Raises:
    pass-through

Returns a deep copy of the objects pointer path list.

Args:
    **parent**:
        The parent node of the pointer path.

Returns:
    A copy of the path list.

Raises:
    none

Get the resulting key for the pointer. In case of a relative pointer as resulting from the processing of the relative pointer and the starting node.

Returns a tuple containing the parent node and self as the child.

Args:
    **jsondata**:
        A valid JSON data node.

Returns:
    The the tuple: ::

       (p, c):
          p: Node reference to parent container.
          c: Node reference to self as the child.

Raises:
    JSONPointerError:

    pass=through

Returns a tuple containing the parent node and the key of current.

Args:
    **jsondata**:
        A valid JSON data node.

Returns:
    The the tuple: ::

       (n, k):
          n: Node reference to parent container.
          k: Key for self as the child entry:

             k := (
                  <list-index>
                | <dict-key>
                | None
             )

             list-index: 'int'
             dict-key: 'UTF-8'
             None: "for root-node"

Raises:
    JSONPointerError:

    pass-through

Gets the copy of the corresponding node.
Relies on the standard package 'json'.

Args:
    **jsondata**:
        A valid JSON data node.

    **cp**:
        Type of returned copy. ::

           cp := (
                C_DEEP
              | C_REF
              | C_SHALLOW
           )

    kargs:
        **valtype**:
            Type of requested value.

Returns:
    The copy of the node, see option *copy*.

Raises:
    JSONPointerError

    pass-through

Returns the existing node for the pointer,
calls transparently *JSONPointer.__call__*.

Args:
    **jsondata**:
        A valid JSON data node.

Returns:
    The node reference.

Raises:
    JSONPointerError:

    pass-through

Returns two parts, the exisitng node for valid part of
the pointer, and the remaining part of the pointer for
the non-existing sub-path.

This method works similar to the 'evaluate' method, whereas it
handles partial valid path pointers, which may also include
a '-' in accordance to RFC6902.

Therefore the non-ambiguous part of the pointer is resolved,
and returned with the remaining part for a newly create.
Thus this method is in particular foreseen to support the
creation of new sub data structures.

The 'evaluate' method therefore returns a list of two elements,
the first is the node reference, the second the list of the
remaining path pointer components. The latter may be empty in
case of a fully valid pointer.


Args:
    **jsondata**:
        A valid JSON data node.

    **parent**:
        Return the parent node of the pointed value.

Returns:
    The node reference, and the remaining part.
    ret:=(node, [<remaining-path-components-list>])

Raises:
    JSONPointerError:
    forwarded from json

Gets for the corresponding path list of the object pointer for
in-memory access on the data of the 'json' package.

Args:
    none

Returns:
    The path list.

Raises:
    none

Gets for the corresponding path list of the object pointer for in-memory access on the data of the 'json' package.

Args:
    none

Returns:
    The path list.

Raises:
    none

Gets the object pointer in compliance to RFC6901
or relative pointer/draft-01/2018.

The result is by default the assigned pointer itself without
verification. Similar in case of a relative pointer the start
offset is ignored by default and no verification is performed.

The following options modify this behaviour:

* superpose - superposes the *startrel* offset with the pointer
* verify - verifies the actual existence of the nodes and/or
  intermediate nodes

The options could be applied combined.

Args:
    kargs:
        **returntype**:
            Defines the return type. ::

               returntype := (
                    RT_DEFAULT     | 'default'
                  | RT_LST         | 'list'      | list
                  | RT_JSONPOINTER | 'jpointer'
               )

        **superpose**:
            Is only relevant for relative paths. Superposes the offset
            *startrel* with the pointer into the resulting final pointer.
            By default nodes are not verified, see *verify* parameter.

            default := True

        **verify**:
            Verifies the "road" of the superposed pointers. ::

               verify := (
                    V_DEFAULT | 'default'
                  | V_NONE    | 'none'    | None    # no checks at all
                  | V_FINAL   | 'final'             # checks final result only
                  | V_STEPS   | 'steps'             # checks each intermediate directory
               )

            default := None
Returns:
    The new pointer in a choosen format, see *returntype*.

Raises:
    none

Gets the objects pointer string in compliance to RFC6901
or relative pointer/draft-01/2018.

The result is by default the assigned pointer itself without
verification. Similar in case of a relative pointer the start
offset is ignored by default and no verification is performed.

The following options modify this behaviour:

* superpose - superposes the *startrel* offset with the pointer
* verify - verifies the actual existence of the nodes and/or
  intermediate nodes

The options could be applied combined.

Args:
    kargs:
        **forcenotation**:
            Force the output notation for string representation to: ::

               forcenotation := (
                    NOTATION_NATIVE           # original format with unescape
                  | NOTATION_JSON             # transform to resulting pointer
                  | NOTATION_HTTP_FRAGMENT    # return a fragment with encoding
                  | NOTATION_JSON_REL         # resulting relative pointer
                  | NOTATION_RAW              # raw input
               )

               default := NOTATION_NATIVE

            **REMINDER**: Applicable for return type string only.

        **superpose**:
            Is only relevant for relative paths. Superposes the offset
            *startrel* with the pointer into the resulting final pointer.
            By default nodes are not verified, see *verify* parameter.

Returns:
    The new pointer in a choosen format, see *returntype*.

Raises:
    none

Gets the objects raw 6901-pointer.

Args:
    none

Returns:
    The raw path.

Raises:
    none

Gets the value resulting from the current pointer.

Args:
    **jsondata**:
        A JSON data node. ::

           jsondata := (
               JSONData
               | list
               | dict
               )

    **parent**:
        Return the parent node of the pointed value.
        When parent is selected, the pointed child node
        is not verified.

Returns:
    The referenced value.

Raises:
    JSONPointerError:

    pass-through

Iterator for the elements of the path pointer itself.

Args:
    **jsondata**:
        If provided a valid JSON data node, the
        path components are successively verified on
        the provided document.

    kargs:
        **parent**:
            Uses the path pointer to parent node.

        **rev**:
            Reverse the order, start with last.

        **superpose**:
            Is only relevant for relative paths, for *rfc6901* defined
            paths the parameter is ignored. When *True* superposes
            the offset *startrel* with the pointer into the resulting
            final pointer. By default nodes are not verified,
            see *verify* parameter. ::

               superpose := (
                    True   # iterates resulting paths from *startrel*
                  | False  # iterates the path only
               )


            default := True

Returns:
    Yields the iterator for the current path pointer
    components.

Raises:
    JSONPointerError:
    forwarded from json

Iterator for the elements the path pointer points to.

Args:
    **jsondata**:
        A valid JSON data node.

    **parent**:
        Uses the path pointer to parent node.

    **rev**:
        Reverse the order, start with last.

Returns:
    Yields the iterator of the current node reference.

Raises:
    JSONPointerError:
    forwarded from json

Successive iterator for the resulting sub-paths the
path pointer itself.

Args:
    **jsondata**:
        If provided a valid JSON data node, the
        path components are successively verified on
        the provided document.

    **parent**:
        Uses the path pointer to parent node.

    **rev**:
        Reverse the order, start with last.

Returns:
    Yields the iterator for the copy of the current
    slice of the path pointer.

Raises:
    JSONPointerError:
    forwarded from json

Successive iterator for the resulting sub-paths and the
corresponding nodes.

Args:
    **jsondata**:
        If provided a valid JSON data node, the
        path components are successively verified on
        the provided document.

    **parent**:
        Uses the path pointer to parent node.

    **rev**:
        Reverse the order, start with last.

Returns:
    Yields the iterator for the tuple of the current
    slice of the path pointer and the reference of the
    corresponding node. ::

       (<path-item>, <sub-path>, <node>)

       path-item: copy of the item
       sub-path:  copy of the current subpath
       node:      reference to the corresponding node

Raises:
    JSONPointerError:
    forwarded from json