YamlCodec completed:

 - `YamlCodec.decode_yamlable` renamed `decode` and `YamlCodec.encode_yamlable` renamed `encode`
 - added some checks in `YamlCodec.encode` to help users implement `to_yaml_dict` correctly
 - fixed bug in `register_with_pyyaml`: the wrong decoding method was registered
 - added tests and usage documentation

This fixes #4

Author: smarie

docs/usage.md

@@ -2,4 +2,112 @@
 
 You have seen in the [main page](./index) a small example to understand the concepts. Below we present other advanced usages.
 
-**TODO + explain YamlCodec**
+## `YamlCodec`
+
+Sometimes you do not have the possibility to change the classes of the objects that you wish to encode/decode. In this case the solution is to write an independent codec, inheriting from `YamlCodec`. Once again this feature leverages the `multi_constructor` and `multi_representer` concepts available in the `PyYaml` internals, but with `YamlCodec` it becomes a bit easier to do.
+
+Let's assume that the following two classes are given and can not be modified:
+
+```python
+class Foo:
+    def __init__(self, a, b):
+        self.a = a
+        self.b = b
+
+    def __eq__(self, other):
+        return vars(self) == vars(other)
+
+class Bar:
+    def __init__(self, c):
+        self.c = c
+
+    def __eq__(self, other):
+        return vars(self) == vars(other)
+```
+
+Writing a codec is quite simple:
+
+ - first inherit from `YamlCodec` and fill `get_yaml_prefix` so that it returns the common prefix that all yaml objects encoded/decoded by this codec will use
+ - then fill the checkers:
+    - `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
+    - `to_yaml_dict` to encode
+
+The example below shows how it can be done:
+
+
+```python
+from yamlable import YamlCodec
+from typing import Type, Any, Iterable, Tuple
+
+
+# the yaml tag suffixes for the two classes
+foo_yaml = "yaml.tests.Foo"
+bar_yaml = "yaml.tests.Bar"
+
+# 2-way mappings between the types and the yaml tags
+types_to_yaml_tags = {Foo: foo_yaml,
+                      Bar: bar_yaml}
+yaml_tags_to_types = {foo_yaml: Foo,
+                      bar_yaml: Bar}
+
+class MyCodec(YamlCodec):
+    @classmethod
+    def get_yaml_prefix(cls):
+        return "!mycodec/"  # This is our root yaml tag
+
+    # ---- 
+
+    @classmethod
+    def get_known_types(cls) -> Iterable[Type[Any]]:
+        # return the list of types that we know how to encode
+        return types_to_yaml_tags.keys()
+
+    @classmethod
+    def is_yaml_tag_supported(cls, yaml_tag_suffix: str) -> bool:
+        # return True if the given yaml tag suffix is supported
+        return yaml_tag_suffix in yaml_tags_to_types.keys()
+
+    # ----
+
+    @classmethod
+    def create_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)
+
+    @classmethod
+    def to_yaml_dict(cls, obj) -> Tuple[str, Any]:
+        # Encode the given object and also return the tag that it should have
+        return types_to_yaml_tags[type(obj)], vars(obj)
+```
+
+When you codec has been defined, it needs to be registerd before being usable. You can specify with which `PyYaml` Loaders/Dumpers it should be registered, or use the default (all): 
+
+```python
+# register the codec
+MyCodec.register_with_pyyaml()
+```
+
+Finally let's test that the codec works:
+
+```python
+from yaml import dump, load
+
+# instantiate
+f = Foo(1, 'hello')
+fy = "!mycodec/yaml.tests.Foo {a: 1, b: hello}\n"
+
+b = Bar('what?')
+by = "!mycodec/yaml.tests.Bar {c: 'what?'}\n"
+
+# dump
+assert dump(f) == fy
+assert dump(b) == by
+
+# load
+assert f == load(fy)
+assert b == load(by)
+```

yamlable/main.py

@@ -1,5 +1,6 @@
 from abc import abstractmethod, ABC
-from typing import TypeVar, Callable, Optional, Iterable, Any, Tuple
+from typing import TypeVar, Callable, Optional, Iterable, Any, Tuple, Mapping
+
 try:
     from typing import Type
 except ImportError:
@@ -339,7 +340,7 @@ def get_yaml_prefix(cls):
         """
 
     @classmethod
-    def decode_yamlable(cls, loader, yaml_tag_suffix, node, **kwargs):
+    def decode(cls, loader, yaml_tag_suffix, node, **kwargs):
         """
         The method used to decode object instances
 
@@ -365,12 +366,12 @@ def is_yaml_tag_supported(cls, yaml_tag_suffix: str) -> bool:
 
     @classmethod
     @abstractmethod
-    def create_from_yaml_dict(cls, yaml_tag_suffix: str, constructor_args, **kwargs):
+    def create_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.
 
-        :param constructor_args:
+        :param dct:
         :param yaml_tag_suffix:
         :param kwargs: keyword arguments coming from pyyaml, not sure what you will find here.
         :return:
@@ -387,7 +388,7 @@ def get_known_types(cls) -> Iterable['Type[Any]']:
         """
 
     @classmethod
-    def encode_yamlable(cls, dumper, obj, without_custom_tag: bool = False, **kwargs):
+    def encode(cls, dumper, obj, without_custom_tag: bool = False, **kwargs):
         """
         The method used to encode YamlAble object instances
 
@@ -400,14 +401,19 @@ def encode_yamlable(cls, dumper, obj, without_custom_tag: bool = False, **kwargs
         """
         # Convert objects to a dictionary of their representation
         yaml_tag_suffix, obj_as_dict = cls.to_yaml_dict(obj)
+        if not isinstance(obj_as_dict, Mapping) or not isinstance(yaml_tag_suffix, str):
+            raise TypeError("`to_yaml_dict` did not return correct results. It shoudl return a tuple of "
+                            "`yaml_tag_suffix, obj_as_dict`")
 
         if without_custom_tag:
             # TODO check that it works
             return dumper.represent_mapping(None, obj_as_dict, flow_style=None)
         else:
             # Add the tag information
-            # TODO make sure that there is a '/'
-            yaml_tag = cls.get_yaml_prefix() + yaml_tag_suffix
+            prefix = cls.get_yaml_prefix()
+            if len(prefix) == 0 or prefix[-1] != '/':
+                prefix = prefix + '/'
+            yaml_tag = prefix + yaml_tag_suffix
             return dumper.represent_mapping(yaml_tag, obj_as_dict, flow_style=None)
 
     @classmethod
@@ -436,8 +442,8 @@ def register_with_pyyaml(cls, loaders={Loader, SafeLoader}, dumpers={Dumper, Saf
         :return:
         """
         for loader in loaders:
-            loader.add_multi_constructor(cls.get_yaml_prefix(), decode_yamlable)
+            loader.add_multi_constructor(cls.get_yaml_prefix(), cls.decode)
 
         for dumper in dumpers:
             for t in cls.get_known_types():
-                dumper.add_multi_representer(t, cls.encode_yamlable)
+                dumper.add_multi_representer(t, cls.encode)

yamlable/tests/test_yamlcodec.py

@@ -0,0 +1,71 @@
+from typing import Tuple, Any, Iterable
+
+from yaml import dump, load
+
+from yamlable import YamlCodec
+
+
+def test_yamlcodec():
+    """ Tests that custom yaml codec work """
+
+    class Foo:
+        def __init__(self, a, b):
+            self.a = a
+            self.b = b
+
+        def __eq__(self, other):
+            return vars(self) == vars(other)
+
+    class Bar:
+        def __init__(self, c):
+            self.c = c
+
+        def __eq__(self, other):
+            return vars(self) == vars(other)
+
+    foo_yaml = "yaml.tests.Foo"
+    bar_yaml = "yaml.tests.Bar"
+    types_to_yaml_tags = {Foo: foo_yaml,
+                          Bar: bar_yaml}
+    yaml_tags_to_types = {foo_yaml: Foo,
+                          bar_yaml: Bar}
+
+    class MyCodec(YamlCodec):
+        @classmethod
+        def get_yaml_prefix(cls):
+            return "!mycodec/"
+
+        @classmethod
+        def get_known_types(cls) -> Iterable['Type[Any]']:
+            return types_to_yaml_tags.keys()
+
+        @classmethod
+        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):
+            typ = yaml_tags_to_types[yaml_tag_suffix]
+            return typ(**dct)
+
+        @classmethod
+        def to_yaml_dict(cls, obj) -> Tuple[str, Any]:
+            return types_to_yaml_tags[type(obj)], vars(obj)
+
+    # register the codec
+    MyCodec.register_with_pyyaml()
+
+    # instantiate
+    f = Foo(1, 'hello')
+    fy = "!mycodec/yaml.tests.Foo {a: 1, b: hello}\n"
+
+    b = Bar('what?')
+    by = "!mycodec/yaml.tests.Bar {c: 'what?'}\n"
+
+    # dump pyyaml
+    assert dump(f) == fy
+    assert dump(b) == by
+
+    # load pyyaml
+    assert f == load(fy)
+    assert b == load(by)