Refactored jsonpointer.py, added tox.ini

Author: thekafkaf

jsonpointer.py

@@ -11,12 +11,12 @@
 # are met:
 #
 # 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
+# notice, this list of conditions and the following disclaimer.
 # 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in the
-#    documentation and/or other materials provided with the distribution.
+# notice, this list of conditions and the following disclaimer in the
+# documentation and/or other materials provided with the distribution.
 # 3. The name of the author may not be used to endorse or promote products
-#    derived from this software without specific prior written permission.
+# derived from this software without specific prior written permission.
 #
 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
@@ -30,62 +30,65 @@
 # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
-from __future__ import unicode_literals
-
 """ Identify specific nodes in a JSON document (RFC 6901) """
 
-try:
-    from collections.abc import Mapping, Sequence
-except ImportError:
-    from collections import Mapping, Sequence
+from __future__ import unicode_literals
 
 # Will be parsed by setup.py to determine package metadata
 __author__ = 'Stefan Kögl <stefan@skoegl.net>'
-__version__ = '1.5'
+__version__ = '1.4'
 __website__ = 'https://github.com/stefankoegl/python-json-pointer'
 __license__ = 'Modified BSD License'
 
 
 try:
     from urllib import unquote
     from itertools import izip
-except ImportError: # Python 3
+except ImportError:  # Python 3
     from urllib.parse import unquote
     izip = zip
 
+try:
+    from collections.abc import Mapping, Sequence
+except ImportError:  # Python 3
+    from collections import Mapping, Sequence
+
 from itertools import tee
 import re
 import copy
 
 
-# array indices must not contain leading zeros, signs, spaces, decimals, etc
-RE_ARRAY_INDEX=re.compile('0|[1-9][0-9]*$')
-
+_nothing = object()
 
-class JsonPointerException(Exception):
-    pass
 
+def set_pointer(doc, pointer, value, inplace=True):
+    """
+    Resolves pointer against doc and sets the value of the target within doc.
 
-class EndOfList(object):
-    """ Result of accessing element "-" of a list """
+    With inplace set to true, doc is modified as long as pointer is not the
+    root.
 
-    def __init__(self, list_):
-        self.list_ = list_
+    >>> obj = {'foo': {'anArray': [ {'prop': 44}], 'another prop': {'baz': 'A string' }}}
 
+    >>> set_pointer(obj, '/foo/anArray/0/prop', 55) == \
+    {'foo': {'another prop': {'baz': 'A string'}, 'anArray': [{'prop': 55}]}}
+    True
 
-    def __repr__(self):
-        return '{cls}({lst})'.format(cls=self.__class__.__name__,
-                lst=repr(self.list_))
+    >>> set_pointer(obj, '/foo/yet%20another%20prop', 'added prop') == \
+    {'foo': {'another prop': {'baz': 'A string'}, 'yet another prop': 'added prop', 'anArray': [{'prop': 55}]}}
+    True
 
+    """
 
-_nothing = object()
+    pointer = JsonPointer(pointer)
+    return pointer.set(doc, value, inplace)
 
 
 def resolve_pointer(doc, pointer, default=_nothing):
     """
     Resolves pointer against doc and returns the referenced object
 
-    >>> obj = {"foo": {"anArray": [ {"prop": 44}], "another prop": {"baz": "A string" }}}
+    >>> obj = {'foo': {'anArray': [ {'prop': 44}], 'another prop': {'baz': 'A string' }}}
 
     >>> resolve_pointer(obj, '') == obj
     True
@@ -110,31 +113,54 @@ def resolve_pointer(doc, pointer, default=_nothing):
     pointer = JsonPointer(pointer)
     return pointer.resolve(doc, default)
 
-def set_pointer(doc, pointer, value, inplace=True):
+
+def pairwise(iterable):
     """
-    Resolves pointer against doc and sets the value of the target within doc.
+    s -> (s0,s1), (s1,s2), (s2, s3), ...
 
-    With inplace set to true, doc is modified as long as pointer is not the
-    root.
+    >>> list(pairwise([]))
+    []
 
-    >>> obj = {"foo": {"anArray": [ {"prop": 44}], "another prop": {"baz": "A string" }}}
+    >>> list(pairwise([1]))
+    []
 
-    >>> set_pointer(obj, '/foo/anArray/0/prop', 55) == \
-    {'foo': {'another prop': {'baz': 'A string'}, 'anArray': [{'prop': 55}]}}
-    True
+    >>> list(pairwise([1, 2, 3, 4]))
+    [(1, 2), (2, 3), (3, 4)]
+    """
+    a, b = tee(iterable)
+    for _ in b:
+        break
+    return izip(a, b)
 
-    >>> set_pointer(obj, '/foo/yet%20another%20prop', 'added prop') == \
-    {'foo': {'another prop': {'baz': 'A string'}, 'yet another prop': 'added prop', 'anArray': [{'prop': 55}]}}
-    True
 
+class JsonPointerException(Exception):
+    pass
+
+
+class EndOfList(object):
+    """
+    Result of accessing element "-" of a list
     """
 
-    pointer = JsonPointer(pointer)
-    return pointer.set(doc, value, inplace)
+    def __init__(self, list_):
+        self.list_ = list_
+
+    def __repr__(self):
+        return '{cls}({lst})'.format(cls=self.__class__.__name__,
+                                     lst=repr(self.list_))
 
 
 class JsonPointer(object):
-    """ A JSON Pointer that can reference parts of an JSON document """
+    """
+    A JSON Pointer that can reference parts of an JSON document
+    """
+    _GETITEM_SUPPORT_ERROR = """document '%s' does not support indexing,
+                             must be mapping/sequence
+                             or support __getitem__"""
+
+    # Array indices must not contain:
+    # leading zeros, signs, spaces, decimals, etc
+    _RE_ARRAY_INDEX = re.compile('0|[1-9][0-9]*$')
 
     def __init__(self, pointer):
         parts = pointer.split('/')
@@ -146,9 +172,10 @@ def __init__(self, pointer):
         parts = [part.replace('~0', '~') for part in parts]
         self.parts = parts
 
-
     def to_last(self, doc):
-        """ Resolves ptr until the last step, returns (sub-doc, last-step) """
+        """
+        Resolves ptr until the last step, returns (sub-doc, last-step)
+        """
 
         if not self.parts:
             return doc, None
@@ -158,9 +185,10 @@ def to_last(self, doc):
 
         return doc, self.get_part(doc, self.parts[-1])
 
-
     def resolve(self, doc, default=_nothing):
-        """Resolves the pointer against doc and returns the referenced object"""
+        """
+        Resolves the pointer against doc and returns the referenced object
+        """
 
         for part in self.parts:
 
@@ -174,11 +202,12 @@ def resolve(self, doc, default=_nothing):
 
         return doc
 
-
     get = resolve
 
     def set(self, doc, value, inplace=True):
-        """ Resolve the pointer against the doc and replace the target with value. """
+        """
+        Resolve the pointer against the doc and replace the target with value.
+        """
 
         if len(self.parts) == 0:
             if inplace:
@@ -194,7 +223,9 @@ def set(self, doc, value, inplace=True):
         return doc
 
     def get_part(self, doc, part):
-        """ Returns the next step in the correct type """
+        """
+        Returns the next step in the correct type
+        """
 
         if isinstance(doc, Mapping):
             return part
@@ -204,26 +235,28 @@ def get_part(self, doc, part):
             if part == '-':
                 return part
 
-            if not RE_ARRAY_INDEX.match(str(part)):
-                raise JsonPointerException("'%s' is not a valid list index" % (part, ))
+            if not self._RE_ARRAY_INDEX.match(str(part)):
+                raise JsonPointerException("'%s' is not a valid sequence index" % part)
 
             return int(part)
 
         elif hasattr(doc, '__getitem__'):
-            # Allow indexing via ducktyping if the target has defined __getitem__
+            # Allow indexing via ducktyping
+            # if the target has defined __getitem__
             return part
 
         else:
-            raise JsonPointerException("Document '%s' does not support indexing, "
-                                       "must be dict/list or support __getitem__" % type(doc))
-
+            raise JsonPointerException(self._GETITEM_SUPPORT_ERROR % type(doc))
 
     def walk(self, doc, part):
-        """ Walks one step in doc and returns the referenced part """
+        """
+        Walks one step in doc and returns the referenced part
+        """
 
         part = self.get_part(doc, part)
 
-        assert (type(doc) in (dict, list) or hasattr(doc, '__getitem__')), "invalid document type %s" % (type(doc),)
+        assert hasattr(doc, '__getitem__'), \
+            'invalid document type %s' % type(doc)
 
         if isinstance(doc, Mapping):
             try:
@@ -241,20 +274,23 @@ def walk(self, doc, part):
                 return doc[part]
 
             except IndexError:
-                raise JsonPointerException("index '%s' is out of bounds" % (part, ))
+                raise JsonPointerException("index '%s' is out of bounds" % part)
 
         else:
             # Object supports __getitem__, assume custom indexing
             return doc[part]
 
     def contains(self, ptr):
-        """ Returns True if self contains the given ptr """
-        return len(self.parts) > len(ptr.parts) and \
-             self.parts[:len(ptr.parts)] == ptr.parts
+        """
+        Returns True if self contains the given ptr
+        """
+        return len(self.parts) >= len(ptr.parts) and \
+               self.parts[:len(ptr.parts)] == ptr.parts
 
     @property
     def path(self):
-        """ Returns the string representation of the pointer
+        """
+        Returns the string representation of the pointer
 
         >>> ptr = JsonPointer('/~0/0/~1').path == '/~0/0/~1'
         """
@@ -263,24 +299,26 @@ def path(self):
         return ''.join('/' + part for part in parts)
 
     def __eq__(self, other):
-        """ compares a pointer to another object
+        """
+        Compares a pointer to another object
 
         Pointers can be compared by comparing their strings (or splitted
         strings), because no two different parts can point to the same
-        structure in an object (eg no different number representations) """
+        structure in an object (eg no different number representations)
+        """
 
         if not isinstance(other, JsonPointer):
             return False
 
         return self.parts == other.parts
 
-
     def __hash__(self):
         return hash(tuple(self.parts))
 
     @classmethod
     def from_parts(cls, parts):
-        """ Constructs a JsonPointer from a list of (unescaped) paths
+        """
+        Constructs a JsonPointer from a list of (unescaped) paths
 
         >>> JsonPointer.from_parts(['a', '~', '/', 0]).path == '/a/~0/~1/0'
         True
@@ -290,22 +328,3 @@ def from_parts(cls, parts):
         parts = [part.replace('/', '~1') for part in parts]
         ptr = cls(''.join('/' + part for part in parts))
         return ptr
-
-
-
-def pairwise(iterable):
-    """ s -> (s0,s1), (s1,s2), (s2, s3), ...
-
-    >>> list(pairwise([]))
-    []
-
-    >>> list(pairwise([1]))
-    []
-
-    >>> list(pairwise([1, 2, 3, 4]))
-    [(1, 2), (2, 3), (3, 4)]
-    """
-    a, b = tee(iterable)
-    for _ in b:
-        break
-    return izip(a, b)