Implement loads and dumps for preconf converters

Author: Tinche

HISTORY.rst

@@ -11,15 +11,16 @@ History
   (`#218 <https://github.com/python-attrs/cattrs/issues/218>`_)
 * Fix structuring bare ``typing.Tuple`` on Pythons lower than 3.9.
   (`#218 <https://github.com/python-attrs/cattrs/issues/218>`_)
-* Fix a wrong ``AttributeError`` of an missing ``__parameters__`` attribute. This could happen 
-  when inheriting certain generic classes – for example ``typing.*`` classes are affected. 
+* Fix a wrong ``AttributeError`` of an missing ``__parameters__`` attribute. This could happen
+  when inheriting certain generic classes – for example ``typing.*`` classes are affected.
   (`#217 <https://github.com/python-attrs/cattrs/issues/217>`_)
 * Fix structuring of ``enum.Enum`` instances in ``typing.Literal`` types.
   (`#231 <https://github.com/python-attrs/cattrs/pull/231>`_)
 * Fix unstructuring all tuples - unannotated, variable-length, homogenous and heterogenous - to `list`.
   (`#226 <https://github.com/python-attrs/cattrs/issues/226>`_)
 * For ``forbid_extra_keys`` raise custom ``ForbiddenExtraKeyError`` instead of generic ``Exception``.
   (`#255 <https://github.com/python-attrs/cattrs/pull/225>`_)
+* All preconf converters now support ``loads`` and ``dumps`` directly.
 
 1.10.0 (2022-01-04)
 -------------------

docs/conf.py

@@ -276,7 +276,7 @@
 # texinfo_no_detailmenu = False
 
 doctest_global_setup = (
-    "import attr, cattr;"
+    "import attr, cattr, cattrs;"
     "from attr import Factory, define, field;"
     "from typing import *;"
     "from enum import Enum, unique"

docs/customizing.rst

@@ -97,6 +97,7 @@ when fields have default values this may help with catching typos.
 creating structure hooks with ``make_dict_structure_fn``.
 
 .. doctest::
+    :options: +SKIP
 
     >>> from cattr.gen import make_dict_structure_fn
     >>>
@@ -164,4 +165,3 @@ or unstructuring function.
     >>> c.register_unstructure_hook(ExampleClass, unst_hook)
     >>> c.unstructure(ExampleClass(1))
     {}
-

docs/preconf.rst

@@ -22,6 +22,22 @@ These converters support the following classes and type annotations, both for st
 * sequences, mutable sequences, mappings, mutable mappings, sets, mutable sets
 * ``datetime.datetime``
 
+.. versionadded:: 22.1.0
+  All preconf converters now have ``loads`` and ``dumps`` methods, which combine un/structuring and the de/serialization logic from their underlying libraries.
+
+.. doctest::
+
+  >>> from cattr.preconf.json import make_converter
+  >>> converter = make_converter()
+
+  >>> @define
+  ... class Test:
+  ...     a: int
+  >>>
+
+  >>> converter.dumps(Test(1))
+  '{"a": 1}'
+
 Particular libraries may have additional constraints documented below.
 
 Standard library ``json``

docs/structuring.rst

@@ -461,19 +461,19 @@ Here's a small example showing how to use factory hooks to apply the `forbid_ext
 .. doctest::
 
     >>> from attr import define, has
-    >>> from cattr.gen import make_dict_structure_fn
-    
-    >>> c = cattr.GenConverter()
-    >>> c.register_structure_hook_factory(has, lambda cl: make_dict_structure_fn(cl, c, _cattrs_forbid_extra_keys=True))
+    >>> from cattrs.gen import make_dict_structure_fn
+
+    >>> c = cattrs.GenConverter()
+    >>> c.register_structure_hook_factory(has, lambda cl: make_dict_structure_fn(cl, c, _cattrs_forbid_extra_keys=True, _cattrs_detailed_validation=False))
 
     >>> @define
     ... class E:
     ...    an_int: int
-    
+
     >>> c.structure({"an_int": 1, "else": 2}, E)
     Traceback (most recent call last):
     ...
-    ForbiddenExtraKeyError: Extra fields in constructor for E: else
+    cattrs.errors.ForbiddenExtraKeysError: Extra fields in constructor for E: else
 
 
 A complex use case for hook factories is described over at :ref:`Using factory hooks`.

docs/validation.rst

@@ -71,4 +71,4 @@ Non-detailed validation
 -----------------------
 
 Non-detailed validation can be enabled by initializing any of the converters with ``detailed_validation=False``.
-In this mode, any errors during un/structuring will bubble up directly as soon as they happen
+In this mode, any errors during un/structuring will bubble up directly as soon as they happen.

src/cattr/preconf/bson.py

@@ -1,18 +1,47 @@
 """Preconfigured converters for bson."""
 from datetime import datetime
-from typing import Any
+from typing import Any, Type, TypeVar
+
+from bson import DEFAULT_CODEC_OPTIONS, CodecOptions, ObjectId, decode, encode
+
+from cattrs._compat import Set, is_mapping
 
-from .._compat import Set, is_mapping
 from ..converters import GenConverter
 from . import validate_datetime
 
+T = TypeVar("T")
+
+
+class BsonConverter(GenConverter):
+    def dumps(
+        self,
+        obj: Any,
+        unstructure_as=None,
+        check_keys: bool = False,
+        codec_options: CodecOptions = DEFAULT_CODEC_OPTIONS,
+    ) -> bytes:
+        return encode(
+            self.unstructure(obj, unstructure_as=unstructure_as),
+            check_keys=check_keys,
+            codec_options=codec_options,
+        )
+
+    def loads(
+        self,
+        data: bytes,
+        cl: Type[T],
+        codec_options: CodecOptions = DEFAULT_CODEC_OPTIONS,
+    ) -> T:
+        return self.structure(decode(data, codec_options=codec_options), cl)
+
 
 def configure_converter(converter: GenConverter):
     """
     Configure the converter for use with the bson library.
 
     * sets are serialized as lists
     * non-string mapping keys are coerced into strings when unstructuring
+    * a deserialization hook is registered for bson.ObjectId by default
     """
 
     def gen_unstructure_mapping(cl: Any, unstructure_to=None):
@@ -29,14 +58,15 @@ def gen_unstructure_mapping(cl: Any, unstructure_to=None):
     )
 
     converter.register_structure_hook(datetime, validate_datetime)
+    converter.register_structure_hook(ObjectId, lambda v, _: ObjectId(v))
 
 
-def make_converter(*args, **kwargs) -> GenConverter:
+def make_converter(*args, **kwargs) -> BsonConverter:
     kwargs["unstruct_collection_overrides"] = {
         **kwargs.get("unstruct_collection_overrides", {}),
         Set: list,
     }
-    res = GenConverter(*args, **kwargs)
+    res = BsonConverter(*args, **kwargs)
     configure_converter(res)
 
     return res

src/cattr/preconf/json.py

@@ -1,10 +1,23 @@
 """Preconfigured converters for the stdlib json."""
 from base64 import b85decode, b85encode
 from datetime import datetime
+from json import dumps, loads
+from typing import Any, Type, TypeVar, Union
+
+from cattrs._compat import Counter, Set
 
-from .._compat import Counter, Set
 from ..converters import Converter, GenConverter
 
+T = TypeVar("T")
+
+
+class JsonConverter(GenConverter):
+    def dumps(self, obj: Any, unstructure_as=None, **kwargs) -> str:
+        return dumps(self.unstructure(obj, unstructure_as=unstructure_as), **kwargs)
+
+    def loads(self, data: Union[bytes, str], cl: Type[T], **kwargs) -> T:
+        return self.structure(loads(data, **kwargs), cl)
+
 
 def configure_converter(converter: Converter):
     """
@@ -23,13 +36,13 @@ def configure_converter(converter: Converter):
     converter.register_structure_hook(datetime, lambda v, _: datetime.fromisoformat(v))
 
 
-def make_converter(*args, **kwargs) -> GenConverter:
+def make_converter(*args, **kwargs) -> JsonConverter:
     kwargs["unstruct_collection_overrides"] = {
         **kwargs.get("unstruct_collection_overrides", {}),
         Set: list,
         Counter: dict,
     }
-    res = GenConverter(*args, **kwargs)
+    res = JsonConverter(*args, **kwargs)
     configure_converter(res)
 
     return res

src/cattr/preconf/msgpack.py

@@ -1,9 +1,23 @@
 """Preconfigured converters for msgpack."""
 from datetime import datetime, timezone
+from typing import Any, Type, TypeVar
+
+from msgpack import dumps, loads
+
+from cattrs._compat import Set
 
-from .._compat import Set
 from ..converters import GenConverter
 
+T = TypeVar("T")
+
+
+class MsgpackConverter(GenConverter):
+    def dumps(self, obj: Any, unstructure_as=None, **kwargs) -> bytes:
+        return dumps(self.unstructure(obj, unstructure_as=unstructure_as), **kwargs)
+
+    def loads(self, data: bytes, cl: Type[T], **kwargs) -> T:
+        return self.structure(loads(data, **kwargs), cl)
+
 
 def configure_converter(converter: GenConverter):
     """
@@ -18,12 +32,12 @@ def configure_converter(converter: GenConverter):
     )
 
 
-def make_converter(*args, **kwargs) -> GenConverter:
+def make_converter(*args, **kwargs) -> MsgpackConverter:
     kwargs["unstruct_collection_overrides"] = {
         **kwargs.get("unstruct_collection_overrides", {}),
         Set: list,
     }
-    res = GenConverter(*args, **kwargs)
+    res = MsgpackConverter(*args, **kwargs)
     configure_converter(res)
 
     return res

src/cattr/preconf/orjson.py

@@ -2,11 +2,24 @@
 from base64 import b85decode, b85encode
 from datetime import datetime
 from enum import Enum
-from typing import Any
+from typing import Any, Type, TypeVar
+
+from orjson import dumps, loads
+
+from cattrs._compat import Set, is_mapping
 
-from .._compat import Set, is_mapping
 from ..converters import GenConverter
 
+T = TypeVar("T")
+
+
+class OrjsonConverter(GenConverter):
+    def dumps(self, obj: Any, unstructure_as=None, **kwargs) -> bytes:
+        return dumps(self.unstructure(obj, unstructure_as=unstructure_as), **kwargs)
+
+    def loads(self, data: bytes, cl: Type[T]) -> T:
+        return self.structure(loads(data), cl)
+
 
 def configure_converter(converter: GenConverter):
     """
@@ -43,12 +56,12 @@ def key_handler(v):
     )
 
 
-def make_converter(*args, **kwargs) -> GenConverter:
+def make_converter(*args, **kwargs) -> OrjsonConverter:
     kwargs["unstruct_collection_overrides"] = {
         **kwargs.get("unstruct_collection_overrides", {}),
         Set: list,
     }
-    res = GenConverter(*args, **kwargs)
+    res = OrjsonConverter(*args, **kwargs)
     configure_converter(res)
 
     return res

src/cattr/preconf/pyyaml.py

@@ -1,10 +1,24 @@
 """Preconfigured converters for pyyaml."""
 from datetime import datetime
+from typing import Any, Type, TypeVar
+
+from yaml import safe_dump, safe_load
+
+from cattrs._compat import FrozenSetSubscriptable
 
-from .._compat import FrozenSetSubscriptable
 from ..converters import GenConverter
 from . import validate_datetime
 
+T = TypeVar("T")
+
+
+class PyyamlConverter(GenConverter):
+    def dumps(self, obj: Any, unstructure_as=None, **kwargs) -> str:
+        return safe_dump(self.unstructure(obj, unstructure_as=unstructure_as), **kwargs)
+
+    def loads(self, data: str, cl: Type[T]) -> T:
+        return self.structure(safe_load(data), cl)
+
 
 def configure_converter(converter: GenConverter):
     """
@@ -19,12 +33,12 @@ def configure_converter(converter: GenConverter):
     converter.register_structure_hook(datetime, validate_datetime)
 
 
-def make_converter(*args, **kwargs) -> GenConverter:
+def make_converter(*args, **kwargs) -> PyyamlConverter:
     kwargs["unstruct_collection_overrides"] = {
         **kwargs.get("unstruct_collection_overrides", {}),
         FrozenSetSubscriptable: list,
     }
-    res = GenConverter(*args, **kwargs)
+    res = PyyamlConverter(*args, **kwargs)
     configure_converter(res)
 
     return res

src/cattr/preconf/tomlkit.py

@@ -1,12 +1,25 @@
 """Preconfigured converters for tomlkit."""
 from base64 import b85decode, b85encode
 from datetime import datetime
-from typing import Any
+from typing import Any, Type, TypeVar
+
+from tomlkit import dumps, loads
+
+from cattrs._compat import Set, is_mapping
 
-from .._compat import Set, is_mapping
 from ..converters import GenConverter
 from . import validate_datetime
 
+T = TypeVar("T")
+
+
+class TomlkitConverter(GenConverter):
+    def dumps(self, obj: Any, unstructure_as=None, **kwargs) -> str:
+        return dumps(self.unstructure(obj, unstructure_as=unstructure_as), **kwargs)
+
+    def loads(self, data: str, cl: Type[T]) -> T:
+        return self.structure(loads(data), cl)
+
 
 def configure_converter(converter: GenConverter):
     """
@@ -37,13 +50,13 @@ def gen_unstructure_mapping(cl: Any, unstructure_to=None):
     converter.register_structure_hook(datetime, validate_datetime)
 
 
-def make_converter(*args, **kwargs) -> GenConverter:
+def make_converter(*args, **kwargs) -> TomlkitConverter:
     kwargs["unstruct_collection_overrides"] = {
         **kwargs.get("unstruct_collection_overrides", {}),
         Set: list,
         tuple: list,
     }
-    res = GenConverter(*args, **kwargs)
+    res = TomlkitConverter(*args, **kwargs)
     configure_converter(res)
 
     return res