Subclassing can override json dumper and loader

Additionally:

* from_string gets a loads parameter
* to_string gets a dumps_parameter
* documentation added
* added more tests

1 files changed, 52 insertions, 0 deletions

diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 538cd0e..0bb1a9c 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -67,3 +67,55 @@ explicitly.
     # or from a list
     >>> patch = [{'op': 'add', 'path': '/baz', 'value': 'qux'}]
     >>> res = jsonpatch.apply_patch(obj, patch)
+
+
+Dealing with Custom Types
+-------------------------
+
+Custom JSON dump and load functions can be used to support custom types such as
+`decimal.Decimal`. The following examples shows how the
+`simplejson <https://simplejson.readthedocs.io/>`_ package, which has native
+support for Python's ``Decimal`` type, can be used to create a custom
+``JsonPatch`` subclass with ``Decimal`` support:
+
+.. code-block:: python
+
+    >>> import decimal
+    >>> import simplejson
+
+    >>> class DecimalJsonPatch(jsonpatch.JsonPatch):
+            @staticmethod
+            def json_dumper(obj):
+                return simplejson.dumps(obj)
+
+            @staticmethod
+            def json_loader(obj):
+                return simplejson.loads(obj, use_decimal=True,
+                                        object_pairs_hook=jsonpatch.multidict)
+
+    >>> src = {}
+    >>> dst = {'bar': decimal.Decimal('1.10')}
+    >>> patch = DecimalJsonPatch.from_diff(src, dst)
+    >>> doc = {'foo': 1}
+    >>> result = patch.apply(doc)
+    {'foo': 1, 'bar': Decimal('1.10')}
+
+Instead of subclassing it is also possible to pass a dump function to
+``from_diff``:
+
+    >>> patch = jsonpatch.JsonPatch.from_diff(src, dst, dumps=simplejson.dumps)
+
+a dumps function to ``to_string``:
+
+    >>> serialized_patch = patch.to_string(dumps=simplejson.dumps)
+    '[{"op": "add", "path": "/bar", "value": 1.10}]'
+
+and load  function to ``from_string``:
+
+    >>> import functools
+    >>> loads = functools.partial(simplejson.loads, use_decimal=True,
+                                  object_pairs_hook=jsonpatch.multidict)
+    >>> patch.from_string(serialized_patch, loads=loads)
+    >>> doc = {'foo': 1}
+    >>> result = patch.apply(doc)
+    {'foo': 1, 'bar': Decimal('1.10')}