Renamed internal AbstractYamlObject methods with dunder: from_yaml_dict becomes __from_yaml_dict__ and to_yaml_dict become __to_yaml_dict__. Fixed #3

(Legacy names will remain supported for a while, added a tet to check that.)

`YamlCodec.create_from_yaml_dict` renamed `from_yaml_dict` for consistency.

Author: smarie

docs/usage.md

@@ -32,7 +32,7 @@ Writing a codec is quite simple:
     - `get_known_types` to return all object types that can be encoded by this codec
     - `is_yaml_tag_supported` to return `True` if a yaml tag (suffix) is supported by this codec for decoding.
  - finally fill the encoder/decoder:
-    - `create_from_yaml_dict` to decode
+    - `from_yaml_dict` to decode
     - `to_yaml_dict` to encode
 
 The example below shows how it can be done:
@@ -73,7 +73,7 @@ class MyCodec(YamlCodec):
     # ----
 
     @classmethod
-    def create_from_yaml_dict(cls, yaml_tag_suffix: str, dct, **kwargs):
+    def from_yaml_dict(cls, yaml_tag_suffix: str, dct, **kwargs):
         # Create an object corresponding to the given tag, from the decoded dict
         typ = yaml_tags_to_types[yaml_tag_suffix]
         return typ(**dct)

yamlable/base.py

@@ -1,7 +1,8 @@
-from abc import ABC, abstractmethod
+from abc import ABC
 from collections import OrderedDict
 from io import TextIOBase, StringIO
 from typing import Union, TypeVar, Dict, Any
+from warnings import warn
 
 try:
     from typing import Type
@@ -17,22 +18,28 @@ class AbstractYamlObject(ABC):
     Adds convenient methods load(s)_yaml/dump(s)_yaml to any object, to call pyyaml features directly on the object or
     on the object class.
 
-    Also adds the two methods to_yaml_dict / from_yaml_dict, that are common to YamlObject2 and YamlAble.
+    Also adds the two methods __to_yaml_dict__ / __from_yaml_dict__, that are common to YamlObject2 and YamlAble.
     Default implementation uses vars(self) and cls(**dct), but subclasses can override.
     """
 
-    def to_yaml_dict(self) -> Dict[str, Any]:
+    def __to_yaml_dict__(self) -> Dict[str, Any]:
         """
         Implementors should transform the object into a dictionary containing all information necessary to decode the
         object in the future. That dictionary will be serialized as a YAML mapping.
 
         Default implementation returns vars(self). TODO maybe some day we'll need to rather make a copy...?
         :return:
         """
+        # Legacy compliance TODO remove in future version
+        if 'to_yaml_dict' in dir(self):
+            warn(type(self).__name__ + " still uses the legacy method name 'to_yaml_dict'. This name will not be "
+                                       "supported in future version, please use '__to_yaml_dict__' instead")
+            return self.to_yaml_dict()
+
         return vars(self)
 
     @classmethod
-    def from_yaml_dict(cls: 'Type[Y]', dct: Dict[Any, Any], yaml_tag: str) -> Y:
+    def __from_yaml_dict__(cls: 'Type[Y]', dct: Dict[Any, Any], yaml_tag: str) -> Y:
         """
         Implementors should transform the given dictionary (read from yaml by the pyYaml stack) into an object instance.
         The yaml tag associated to this object, read in the yaml document, is provided in parameter.
@@ -47,6 +54,12 @@ def from_yaml_dict(cls: 'Type[Y]', dct: Dict[Any, Any], yaml_tag: str) -> Y:
             against is_json_schema_id_supported)
         :return:
         """
+        # Legacy compliance TODO remove in future version
+        if 'from_yaml_dict' in dir(cls):
+            warn(cls.__name__ + " still uses the legacy method name 'from_yaml_dict'. This name will not be "
+                                "supported in future version, please use '__from_yaml_dict__' instead")
+            return cls.from_yaml_dict(dct, yaml_tag)
+
         return cls(**dct)
 
     def dump_yaml(self, file_path_or_stream: Union[str, TextIOBase], safe: bool = True, **pyyaml_kwargs):

yamlable/main.py

@@ -201,7 +201,7 @@ def decode_yamlable(loader, yaml_tag, node, **kwargs):
         try:
             if clazz.is_yaml_tag_supported(yaml_tag):
                 constructor_args = read_yaml_node_as_dict(loader, node)
-                return clazz.from_yaml_dict(constructor_args, yaml_tag=yaml_tag)
+                return clazz.__from_yaml_dict__(constructor_args, yaml_tag=yaml_tag)
         except Exception as e:
             errors[clazz.__name__] = e
 
@@ -223,7 +223,7 @@ def encode_yamlable(dumper, obj, without_custom_tag: bool = False, **kwargs):
     :return:
     """
     # Convert objects to a dictionary of their representation
-    new_data = obj.to_yaml_dict()
+    new_data = obj.__to_yaml_dict__()
 
     if without_custom_tag:
         # TODO check that it works
@@ -323,7 +323,7 @@ class YamlCodec(ABC):
      - Decoding:
         - fill get_yaml_prefix
         - fill is_yaml_tag_supported to declare if a given yaml tag is supported or not
-        - fill create_from_yaml_dict to create new instances of objects from a dictionary, according to the yaml tag
+        - fill from_yaml_dict to create new instances of objects from a dictionary, according to the yaml tag
      - Encoding:
         - fill get_known_types
         - fill the to_yaml_dict
@@ -352,7 +352,7 @@ def decode(cls, loader, yaml_tag_suffix, node, **kwargs):
         """
         if cls.is_yaml_tag_supported(yaml_tag_suffix):
             constructor_args = read_yaml_node_as_dict(loader, node)
-            return cls.create_from_yaml_dict(yaml_tag_suffix, constructor_args, **kwargs)
+            return cls.from_yaml_dict(yaml_tag_suffix, constructor_args, **kwargs)
 
     @classmethod
     @abstractmethod
@@ -366,7 +366,7 @@ def is_yaml_tag_supported(cls, yaml_tag_suffix: str) -> bool:
 
     @classmethod
     @abstractmethod
-    def create_from_yaml_dict(cls, yaml_tag_suffix: str, dct, **kwargs):
+    def from_yaml_dict(cls, yaml_tag_suffix: str, dct, **kwargs):
         """
         Implementing classes should create an object corresponding to the given yaml tag, using the given constructor
         arguments.

yamlable/tests/test_yamlable.py

@@ -13,11 +13,11 @@ def test_yamlable_incomplete_description():
     with pytest.raises(NotImplementedError) as err_info:
         class Foo(YamlAble):
             # __yaml_tag_suffix__ = 'foo'
-            def to_yaml_dict(self) -> Dict[str, Any]:
+            def __to_yaml_dict__(self) -> Dict[str, Any]:
                 return copy(vars(self))
 
             @classmethod
-            def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
+            def __from_yaml_dict__(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
                 return Foo(**dct)
 
         # instantiate
@@ -43,11 +43,11 @@ def __init__(self, a, b):
         def __eq__(self, other):
             return vars(self) == vars(other)
 
-        def to_yaml_dict(self) -> Dict[str, Any]:
+        def __to_yaml_dict__(self) -> Dict[str, Any]:
             return copy(vars(self))
 
         @classmethod
-        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
+        def __from_yaml_dict__(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
             return Foo(**dct)
 
     # instantiate
@@ -80,6 +80,68 @@ def close(self):
     assert f == load(y)
 
 
+def test_yamlable_legacy_method_names():
+    """ Tests that YamlAbleMixIn works correctly """
+
+    global enc
+    global dec
+    enc, dec = False, False
+
+    @yaml_info(yaml_tag_ns='yaml.tests')
+    class FooLegacy(YamlAble):
+        # __yaml_tag_suffix__ = 'foo'   not needed: we used @yaml_info
+
+        def __init__(self, a, b):
+            self.a = a
+            self.b = b
+
+        def __eq__(self, other):
+            return vars(self) == vars(other)
+
+        def to_yaml_dict(self) -> Dict[str, Any]:
+            global enc
+            enc = True
+            return copy(vars(self))
+
+        @classmethod
+        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
+            global dec
+            dec = True
+            return FooLegacy(**dct)
+
+    # instantiate
+    f = FooLegacy(1, 'hello')
+
+    # dump
+    y = f.dumps_yaml()
+    assert y == "!yamlable/yaml.tests.FooLegacy {a: 1, b: hello}\n"
+
+    # dump io
+    class MemorizingStringIO(StringIO):
+        """ A StringIO object that memorizes its buffer when it is closed (as opposed to the standard StringIO) """
+        def close(self):
+            self.value = self.getvalue()
+            super(StringIO, self).close()
+    s = MemorizingStringIO()
+    f.dump_yaml(s)
+    assert s.value == y
+
+    # dump pyyaml
+    assert dump(f) == y
+
+    # load
+    assert f == FooLegacy.loads_yaml(y)
+
+    # load io
+    assert f == FooLegacy.load_yaml(StringIO(y))
+
+    # load pyyaml
+    assert f == load(y)
+
+    assert enc
+    assert dec
+
+
 # TODO override so that tag is not supported, to check error message
 def test_yamlable_not_supported():
 
@@ -94,11 +156,11 @@ def __init__(self, a, b):
         def __eq__(self, other):
             return vars(self) == vars(other)
 
-        def to_yaml_dict(self) -> Dict[str, Any]:
+        def __to_yaml_dict__(self) -> Dict[str, Any]:
             return copy(vars(self))
 
         @classmethod
-        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
+        def __from_yaml_dict__(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
             return Foo_Err(**dct)
 
         @classmethod

yamlable/tests/test_yamlcodec.py

@@ -44,7 +44,7 @@ def is_yaml_tag_supported(cls, yaml_tag_suffix: str) -> bool:
             return yaml_tag_suffix in yaml_tags_to_types.keys()
 
         @classmethod
-        def create_from_yaml_dict(cls, yaml_tag_suffix: str, dct, **kwargs):
+        def from_yaml_dict(cls, yaml_tag_suffix: str, dct, **kwargs):
             typ = yaml_tags_to_types[yaml_tag_suffix]
             return typ(**dct)
 

yamlable/tests/test_yamlobjects.py

@@ -29,11 +29,11 @@ def __init__(self, a, b):
         def __eq__(self, other):
             return vars(self) == vars(other)
 
-        def to_yaml_dict(self) -> Dict[str, Any]:
+        def __to_yaml_dict__(self) -> Dict[str, Any]:
             return copy(vars(self))
 
         @classmethod
-        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
+        def __from_yaml_dict__(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
             return Foo(**dct)
 
     # instantiate

yamlable/yaml_objects.py

@@ -51,7 +51,7 @@ class YamlObject2(AbstractYamlObject, YAMLObject, metaclass=ABCYAMLMeta):
     A helper class to register a class as able to dump instances to yaml and to load them back from yaml.
 
     This class relies on the `YAMLObject` class provided in pyyaml, and implements the to_yaml/from_yaml methods by
-    leveraging the VarsExposer/BuildableFromVars mix-ins.
+    leveraging the AbstractYamlObject class (__to_yaml_dict__ / __from_yaml_dict__).
 
     It is basically an extension of YAMLObject
      - mapping the methods to methods in AbstractYamlObject (for consistency with YamlAble) so that you only have to
@@ -60,7 +60,7 @@ class YamlObject2(AbstractYamlObject, YAMLObject, metaclass=ABCYAMLMeta):
 
     You still have to
      - define `yaml_tag` either directly or using the @yaml_info() decorator
-     - implement both methods from AbstractYamlObject: to_yaml_dict and from_yaml_dict
+     - optionally override methods from AbstractYamlObject: __to_yaml_dict__ and __from_yaml_dict__
 
     Note: since this class extends YAMLObject, it relies on metaclass. You might therefore prefer to extend YamlAble
     instead.
@@ -79,17 +79,17 @@ def to_yaml(cls, dumper, data: AbstractYamlObject):
         :param data:
         :return:
         """
-        new_data = data.to_yaml_dict()
+        new_data = data.__to_yaml_dict__()
         return dumper.represent_mapping(cls.yaml_tag, new_data, flow_style=cls.yaml_flow_style)
 
     @classmethod
     def from_yaml(cls, loader, node):
         """
-        Default implementation: loads the node as a dictionary and calls from_yaml_dict with this dictionary
+        Default implementation: loads the node as a dictionary and calls __from_yaml_dict__ with this dictionary
 
         :param loader:
         :param node:
         :return:
         """
         constructor_args = read_yaml_node_as_dict(loader, node)
-        return cls.from_yaml_dict(constructor_args, yaml_tag=cls.yaml_tag)
+        return cls.__from_yaml_dict__(constructor_args, yaml_tag=cls.yaml_tag)