Add doctests and docstrings

Author: sweeneytr

.github/workflows/test.yaml

@@ -20,7 +20,7 @@ jobs:
       run: |
         curl -sSL https://install.python-poetry.org | python3 -
         poetry install
-        poetry run pytest --cov=fast_json_pointer --cov-report lcov tests/
+        poetry run pytest --cov=fast_json_pointer --cov-report lcov tests/ --doctest-modules src/
 
     - name: Coveralls
       uses: coverallsapp/github-action@master

docs/api.rst

@@ -1,4 +1,16 @@
 API
 ========================================
 
-.. autoexception:: fast_json_pointer.exceptions.JsonPointerException
+.. automodule:: fast_json_pointer.rfc6901_parser
+
+.. autofunction:: validate
+.. autofunction:: parse
+.. autofunction:: unparse
+.. autofunction:: escape
+.. autofunction:: unescape
+
+
+.. py:module:: fast_json_pointer.exceptions
+
+.. autoexception:: JsonPointerException
+.. autoexception:: ParseException

src/fast_json_pointer/exceptions.py

@@ -1,5 +1,5 @@
 class JsonPointerException(Exception):
-    pass
+    '''Generic json pointer failure.'''
 
 class ParseException(JsonPointerException):
-    pass
+    '''Failure occurred while parsing a json pointer.'''

src/fast_json_pointer/rfc6901_parser.py

@@ -1,3 +1,7 @@
+'''Implements low-level json pointer parsing. See `RFC 6901 Section 4 <https://www.rfc-editor.org/rfc/rfc6901#section-4>`_ for the
+specification that this parser adheres to.
+'''
+
 import re
 from typing import *
 
@@ -6,30 +10,97 @@
 RE_INVALID_ESCAPE = re.compile("(~[^01]|~$)")
 
 
-def validate(s: str) -> None:
-    if match := RE_INVALID_ESCAPE.search(s):
+def validate(pointer: str) -> None:
+    '''Validate that a string is a well formed json pointer.
+    
+    :raises: :exc:`.ParseException`: If json pointer is invalid.
+
+    >>> validate('')
+    >>> validate('foo') # parts must lead with '/'
+    Traceback (most recent call last):
+        ...
+    fast_json_pointer.exceptions.ParseException: JSON pointers must be empty or start with '/'
+    >>> validate('/foo~') # ~ must be followed by either 0 or 1
+    Traceback (most recent call last):
+        ...
+    fast_json_pointer.exceptions.ParseException: Found invalid escape ~
+    >>> validate('/~2/foo') # only ~0, ~1 are valid escapes
+    Traceback (most recent call last):
+        ...
+    fast_json_pointer.exceptions.ParseException: Found invalid escape ~2
+    '''
+    
+    if len(pointer) > 0 and not pointer.startswith("/"):
+        raise ParseException("JSON pointers must be empty or start with '/'")
+
+    if match := RE_INVALID_ESCAPE.search(pointer):
         raise ParseException("Found invalid escape {}".format(match.group()))
 
 
-def parse(s: str) -> list[str]:
-    validate(s)
+def parse(pointer: str) -> list[str]:
+    r'''Parse a json pointer into a list of unescaped path parts.
+
+    :raises: :exc:`.ParseException`: If json pointer is invalid.
+
+    >>> parse('') # empty string is "the whole json object"
+    []
+    >>> parse('/') # keys can be zero-length strings
+    ['']
+    >>> parse('/ //  ') # which can look funky
+    [' ', '', '  ']
+    >>> parse('/foo/m~0n/a~1b') # ~1 escapes /, ~0 escapes ~
+    ['foo', 'm~n', 'a/b']
+    >>> parse('/c%d/e^f') # funky symbols are fine too!
+    ['c%d', 'e^f']
+    >>> parse(r'/i\\j/g|h/k\l') # r-string avoids escaping backslashes
+    ['i\\\\j', 'g|h', 'k\\l']
+    '''
+    validate(pointer)
 
-    parts = s.split("/")
-    # discard "empty" str, as "/foo/bar" becomes ["", "foo", "bar"]
-    if parts.pop(0) != "":
-        raise ParseException("JSON pointers must start with /")
+    parts = pointer.split("/")
+    # discard "empty" str, as "/foo/bar".split() becomes ["", "foo", "bar"]
+    parts.pop(0) 
     return [unescape(p) for p in parts]
 
 
 def unparse(parts: Iterable[str]) -> str:
-    return "/" + "/".join(escape(part) for part in parts)
+    r'''Combine an iterable of unescaped path parts into a json pointer.
+    
+    >>> unparse([])
+    ''
+    >>> unparse([''])
+    '/'
+    >>> unparse([' ', '', '  '])
+    '/ //  '
+    >>> unparse(['foo', 'm~n', 'a/b'])
+    '/foo/m~0n/a~1b'
+    >>> unparse(['c%d', 'e^f'])
+    '/c%d/e^f'
+    >>> unparse([r'i\\j', 'g|h', r'k\l'])
+    '/i\\\\j/g|h/k\\l'
+    '''
+    return "".join('/' + escape(part) for part in parts)
 
 
-def escape(s: str) -> str:
+def escape(part: str) -> str:
+    '''Escape a path part.
+    
+    >>> escape("foo")
+    'foo'
+    >>> escape("m~/0")
+    'm~0~10'
+    '''
     # Escape `~` first! https://www.rfc-editor.org/rfc/rfc6901#section-4
-    return s.replace("~", "~0").replace("/", "~1")
+    return part.replace("~", "~0").replace("/", "~1")
 
 
-def unescape(s: str) -> str:
+def unescape(part: str) -> str:
+    '''Unescape a path part.
+    
+    >>> unescape("foo")
+    'foo'
+    >>> unescape("m~0~10")
+    'm~/0'
+    '''
     # Unscape `~` last! https://www.rfc-editor.org/rfc/rfc6901#section-4
-    return s.replace("~1", "/").replace("~0", "~")
+    return part.replace("~1", "/").replace("~0", "~")