implement JSON serialisation (pydantic#210)

* implement JSON serialisation, fix pydantic#133

* documenting JSON serialisation

* fix coverage

Author: samuelcolvin

HISTORY.rst

@@ -9,6 +9,7 @@ v0.11.0 (2018-06-28)
 * **breaking change**: remove msgpack parsing #201
 * add ``FilePath`` and ``DirectoryPath`` types #10
 * model schema generation #190
+* JSON serialisation of models and schemas #133
 
 v0.10.0 (2018-06-11)
 ....................

docs/examples/copy_values.py

@@ -14,8 +14,13 @@ class FooBarModel(BaseModel):
 m = FooBarModel(banana=3.14, foo='hello', bar={'whatever': 123})
 
 print(m.dict())
+# (returns a dictionary)
 # > {'banana': 3.14, 'foo': 'hello', 'bar': {'whatever': 123}}
 
+print(m.json())
+# (returns a str)
+# > {"banana": 3.14, "foo": "hello", "bar": {"whatever": 123}}
+
 print(m.dict(include={'foo', 'bar'}))
 # > {'foo': 'hello', 'bar': {'whatever': 123}}
 

docs/examples/schema1.json

@@ -1,6 +1,7 @@
 {
   "type": "object",
   "title": "Main",
+  "description": "This is the description of the main model",
   "properties": {
     "foo_bar": {
       "type": "object",
@@ -37,6 +38,5 @@
       "default": 42,
       "description": "this is the value of snap"
     }
-  },
-  "description": "This is the description of the main model"
+  }
 }

docs/examples/schema1.py

@@ -31,4 +31,11 @@ class MainModel(BaseModel):
     class Config:
         title = 'Main'
 
-print(json.dumps(MainModel.schema(), indent=2))
+debug(MainModel.schema())
+# > {
+#       'type': 'object',
+#       'title': 'Main',
+#       'properties': {
+#           'foo_bar': {
+#           ...
+print(MainModel.schema_json(indent=2))

docs/index.rst

@@ -206,6 +206,8 @@ Outputs:
 
 (This script is complete, it should run "as is")
 
+`schema` will return a dict of the schema, while `schema_json` will return a JSON representation of that.
+
 "submodels" are recursively included in the schema.
 
 The ``description`` for models is taken from the docstring of the class.
@@ -227,7 +229,7 @@ Instead of using ``Schema``, the ``fields`` property of :ref:`the Config class <
 to set all the arguments above except ``default``.
 
 The schema is generated by default using aliases as keys, it can also be generated using model
-property names not aliases with ``MainModel.Schema(by_alias=False)``.
+property names not aliases with ``MainModel.schema/schema_json(by_alias=False)``.
 
 Error Handling
 ..............
@@ -455,17 +457,18 @@ a model.
 Trying to change ``a`` caused an error and it remains unchanged, however the dict ``b`` is mutable and the
 immutability of ``foobar`` doesn't stop being changed.
 
-Copying and Dictionary Serialization
-....................................
+Copying and Serialization
+.........................
 
-The ``dict`` function returns a dict containing the attributes of a model. Sub-models are recursively
-converted to dicts.
+The ``dict`` function returns a dictionary containing the attributes of a model. Sub-models are recursively
+converted to dicts. The ``json`` method will serialise a model to JSON using ``dict``.
 
 While ``copy`` allows models to be duplicated, this is particularly useful for immutable models.
 
-Both ``dict`` and ``copy`` take the optional ``include`` and ``exclude`` keyword arguments to control which attributes
-are returned or copied, respectively. ``copy`` accepts an extra keyword argument, ``update``, which accepts a ``dict``
-mapping attributes to new values that will be applied as the model is duplicated.
+
+``dict``, ``json`` and ``copy`` all take the optional ``include`` and ``exclude`` keyword arguments to control
+which attributes are returned or copied, respectively. ``copy`` accepts an extra keyword argument, ``update``,
+which accepts a ``dict`` mapping attributes to new values that will be applied as the model is duplicated.
 
 .. literalinclude:: examples/copy_values.py
 

pydantic/json.py

@@ -0,0 +1,40 @@
+import datetime
+from decimal import Decimal
+from enum import Enum
+from types import GeneratorType
+from uuid import UUID
+
+from .main import BaseModel
+
+__all__ = ['pydantic_encoder']
+
+
+def isoformat(o):
+    return o.isoformat()
+
+
+ENCODERS_BY_TYPE = {
+    UUID: str,
+    datetime.datetime: isoformat,
+    datetime.date: isoformat,
+    datetime.time: isoformat,
+    set: list,
+    frozenset: list,
+    GeneratorType: list,
+    bytes: lambda o: o.decode(),
+    Decimal: float,
+}
+
+
+def pydantic_encoder(obj):
+    if isinstance(obj, BaseModel):
+        return obj.dict()
+    elif isinstance(obj, Enum):
+        return obj.value
+
+    try:
+        encoder = ENCODERS_BY_TYPE[type(obj)]
+    except KeyError:
+        raise TypeError(f"Object of type '{obj.__class__.__name__}' is not JSON serializable")
+    else:
+        return encoder(obj)

pydantic/main.py

@@ -1,3 +1,4 @@
+import json
 import warnings
 from abc import ABCMeta
 from copy import deepcopy
@@ -181,13 +182,21 @@ def __setstate__(self, state):
 
     def dict(self, *, include: Set[str]=None, exclude: Set[str]=set()) -> Dict[str, Any]:
         """
-        Get a dict of the values processed by the model, optionally specifying which fields to include or exclude.
+        Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
         """
         return {
             k: v for k, v in self
             if k not in exclude and (not include or k in include)
         }
 
+    def json(self, *, include: Set[str]=None, exclude: Set[str]=set(), **dumps_kwargs) -> str:
+        """
+        Generate a JSON representation of the model, `include` and `exclude` arguments as per `dict()`. Other arguments
+        as per `json.dumps()`.
+        """
+        from .json import pydantic_encoder
+        return json.dumps(self.dict(include=include, exclude=exclude), default=pydantic_encoder, **dumps_kwargs)
+
     @classmethod
     def parse_obj(cls, obj):
         if not isinstance(obj, dict):
@@ -253,24 +262,31 @@ def fields(self):
         return self.__fields__
 
     @classmethod
-    def schema(cls, by_alias=True):
+    def schema(cls, by_alias=True) -> Dict[str, Any]:
         cached = cls._schema_cache.get(by_alias)
         if cached is not None:
             return cached
-        if by_alias:
-            props = {f.alias: f.schema(by_alias) for f in cls.__fields__.values()}
-        else:
-            props = {k: f.schema(by_alias) for k, f in cls.__fields__.items()}
+
         s = {
             'type': 'object',
             'title': cls.__config__.title or cls.__name__,
-            'properties': props,
         }
         if cls.__doc__:
             s['description'] = clean_docstring(cls.__doc__)
+
+        if by_alias:
+            s['properties'] = {f.alias: f.schema(by_alias) for f in cls.__fields__.values()}
+        else:
+            s['properties'] = {k: f.schema(by_alias) for k, f in cls.__fields__.items()}
+
         cls._schema_cache[by_alias] = s
         return s
 
+    @classmethod
+    def schema_json(cls, *, by_alias=True, **dumps_kwargs) -> str:
+        from .json import pydantic_encoder
+        return json.dumps(cls.schema(by_alias=by_alias), default=pydantic_encoder, **dumps_kwargs)
+
     @classmethod
     def get_validators(cls):
         yield dict_validator

tests/test_json.py

@@ -0,0 +1,58 @@
+import datetime
+import json
+from decimal import Decimal
+from enum import Enum
+from uuid import UUID
+
+import pytest
+
+from pydantic import BaseModel, create_model
+from pydantic.json import pydantic_encoder
+
+
+class MyEnum(Enum):
+    foo = 'bar'
+    snap = 'crackle'
+
+
+@pytest.mark.parametrize('input,output', [
+    (UUID('ebcdab58-6eb8-46fb-a190-d07a33e9eac8'), '"ebcdab58-6eb8-46fb-a190-d07a33e9eac8"'),
+    (datetime.datetime(2032, 1, 1, 1, 1), '"2032-01-01T01:01:00"'),
+    (datetime.datetime(2032, 1, 1, 1, 1, tzinfo=datetime.timezone.utc), '"2032-01-01T01:01:00+00:00"'),
+    (datetime.datetime(2032, 1, 1), '"2032-01-01T00:00:00"'),
+    (datetime.time(12, 34, 56), '"12:34:56"'),
+    ({1, 2, 3}, '[1, 2, 3]'),
+    (frozenset([1, 2, 3]), '[1, 2, 3]'),
+    ((v for v in range(4)), '[0, 1, 2, 3]'),
+    (b'this is bytes', '"this is bytes"'),
+    (Decimal('12.34'), '12.34'),
+    (create_model('BarModel', a='b', c='d')(), '{"a": "b", "c": "d"}'),
+    (MyEnum.foo, '"bar"')
+])
+def test_encoding(input, output):
+    assert json.dumps(input, default=pydantic_encoder) == output
+
+
+def test_model_encoding():
+    class ModelA(BaseModel):
+        x: int
+        y: str
+
+    class Model(BaseModel):
+        a: float
+        b: bytes
+        c: Decimal
+        d: ModelA
+
+    m = Model(a=10.2, b='foobar', c=10.2, d={'x': 123, 'y': '123'})
+    assert m.dict() == {'a': 10.2, 'b': b'foobar', 'c': Decimal('10.2'), 'd': {'x': 123, 'y': '123'}}
+    assert m.json() == '{"a": 10.2, "b": "foobar", "c": 10.2, "d": {"x": 123, "y": "123"}}'
+    assert m.json(exclude={'b'}) == '{"a": 10.2, "c": 10.2, "d": {"x": 123, "y": "123"}}'
+
+
+def test_invalid_model():
+    class Foo:
+        pass
+
+    with pytest.raises(TypeError):
+        json.dumps(Foo, default=pydantic_encoder)

tests/test_main.py

@@ -56,6 +56,8 @@ def test_ultra_simple_repr():
     assert repr(m) == '<UltraSimpleModel a=10.2 b=10>'
     assert repr(m.fields['a']) == "<Field(a type=float required)>"
     assert dict(m) == {'a': 10.2, 'b': 10}
+    assert m.dict() == {'a': 10.2, 'b': 10}
+    assert m.json() == '{"a": 10.2, "b": 10}'
 
 
 def test_str_truncate():

tests/test_schema.py

@@ -1,3 +1,5 @@
+import json
+from decimal import Decimal
 from enum import Enum, IntEnum
 
 import pytest
@@ -191,3 +193,33 @@ class Model(BaseModel):
             },
         },
     }
+
+
+def test_json_schema():
+    class Model(BaseModel):
+        a = b'foobar'
+        b = Decimal('12.34')
+
+    with pytest.raises(TypeError):
+        json.dumps(Model.schema())
+
+    assert Model.schema_json(indent=2) == (
+        '{\n'
+        '  "type": "object",\n'
+        '  "title": "Model",\n'
+        '  "properties": {\n'
+        '    "a": {\n'
+        '      "type": "bytes",\n'
+        '      "title": "A",\n'
+        '      "required": false,\n'
+        '      "default": "foobar"\n'
+        '    },\n'
+        '    "b": {\n'
+        '      "type": "Decimal",\n'
+        '      "title": "B",\n'
+        '      "required": false,\n'
+        '      "default": 12.34\n'
+        '    }\n'
+        '  }\n'
+        '}'
+    )