First version of the documentation

Slightly renamed typevars

Author: smarie

docs/index.md

@@ -4,6 +4,15 @@
 
 [![Build Status](https://travis-ci.org/smarie/python-yamlable.svg?branch=master)](https://travis-ci.org/smarie/python-yamlable) [![Tests Status](https://smarie.github.io/python-yamlable/junit/junit-badge.svg?dummy=8484744)](https://smarie.github.io/python-yamlable/junit/report.html) [![codecov](https://codecov.io/gh/smarie/python-yamlable/branch/master/graph/badge.svg)](https://codecov.io/gh/smarie/python-yamlable) [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://smarie.github.io/python-yamlable/) [![PyPI](https://img.shields.io/badge/PyPI-yamlable-blue.svg)](https://pypi.python.org/pypi/yamlable/)
 
+PyYaml is a great library. However it is a bit hard for anyone to add the yaml capability to their classes. Its `YamlObject` helper class is a first step but it has two drawbacks:
+ * one has to master PyYaml Loader/Dumper internal features to understand what they are doing
+ * there is a mandatory metaclass, which can prevent wide adoption (multiple inheritance with metaclasses...)
+
+`yamlable` provides a very easy way for you to leverage PyYaml without suffering the complexity: simply inherit from `YamlAble`, decorate with `@yaml_info`, implement the abstract methods to write to / load from a dictionary, and you're set!
+
+In addition `yamlable` provides 
+ * a way to creade Yaml codecs for several object types at the same time (`YamlCodec`).
+ * an alternative to `YamlAble` that relies strictly on `YamlObject`: `YamlObject2`
 
 
 ## Installing
@@ -14,14 +23,79 @@
 
 ## Usage
 
-TODO
+Let's make a class yaml-able: we have to
+ - inherit from `YamlAble`
+ - decorate it with the `@yaml_info` annotation to declare the associated yaml tag
+ - implement `from_yaml_dict` (class method called during decoding) and `to_yaml_dict` (instance method called during encoding)
+
+```python
+from yamlable import yaml_info, YamlAble
+
+@yaml_info(yaml_tag_ns='com.yamlable.example')
+class Foo(YamlAble):
+
+    def __init__(self, a, b):
+        """ Constructor """
+        self.a = a
+        self.b = b
+        self.irrelevant = 37
+
+    def __str__(self):
+        """ String representation for prints """
+        return "Foo - " + str(dict(a=self.a, b=self.b))
+
+    def to_yaml_dict(self):
+        """ This method is called when you call yaml.dump()"""
+        return {'a': self.a, 'b': self.b}
+
+    @classmethod
+    def from_yaml_dict(cls, dct, yaml_tag):
+        """ This method is called when you call yaml.load()"""
+        return Foo(dct['a'], dct['b'])
+```
+
+That's it! Let's check that our class is correct and allows us to create instances:
+
+```python
+>>> f = Foo(1, 'hello')
+>>> print(f)
+
+Foo - {'a': 1, 'b': 'hello'}
+```
+
+The object directly has the `dump_yaml` (dumping to file) / `dumps_yaml` (dumping to string) methods:
+
+```python
+>>> print(f.dumps_yaml())
+
+!yamlable/com.yamlable.example.Foo {a: 1, b: hello}
+```
+
+The class directly has the `load_yaml` (load from file) / `loads_yaml` (load from string) methods
+
+```python
+>>> print(Foo.loads_yaml("!yamlable/com.yamlable.example.Foo {a: 0, b: hey}"))
+
+Foo - {'a': 0, 'b': 'hey'}
+```
+
+See pyyaml help page for the various formatting arguments that you can use..
+
+```python
+>>> print(f.dumps_yaml(default_flow_style=False))
+
+!yamlable/com.yamlable.example.Foo
+a: 1
+b: hello
+```
 
-See [Usage](./usage) for a complete example with exceptions handling and more.
+See [Usage](./usage) for other possibilities of `yamlable`.
 
 
 ## Main features / benefits
 
- * TODO 
+ * Add yaml-ability to any class easily through inheritance without metaclass (as opposed to `YamlObject`) and without knowledge of internal PyYaml loader/dumper logic.
+ * Write codecs to support several types at a time with `YamlCodec`
 
 
 ## See Also

yamlable/__init__.py

@@ -1,7 +1,7 @@
-from yamlable.base import AbstractYamlObject, NONE_IGNORE_CHECKS, AYO, read_yaml_node_as_dict
+from yamlable.base import AbstractYamlObject, NONE_IGNORE_CHECKS, Y, read_yaml_node_as_dict
 from yamlable.main import YamlCodec, register_yamlable_codec, yaml_info_decorate, yaml_info, YamlAble, YA, \
     AbstractYamlAble, YAMLABLE_PREFIX
-from yamlable.yaml_objects import YO2, YamlObject2, ABCYAMLMeta, YAMLObjectMetaclassStrict
+from yamlable.yaml_objects import YamlObject2, ABCYAMLMeta, YAMLObjectMetaclassStrict
 
 __all__ = ['base',
            'main',

yamlable/base.py

@@ -9,7 +9,7 @@
     pass # normal for old versions of typing
 
 
-AYO = TypeVar('AYO', bound='AbstractYamlObject')
+Y = TypeVar('Y', bound='AbstractYamlObject')
 
 
 class AbstractYamlObject(ABC):
@@ -30,7 +30,7 @@ def to_yaml_dict(self) -> Dict[str, Any]:
 
     @classmethod
     @abstractmethod
-    def from_yaml_dict(cls: 'Type[AYO]', dct: Dict, yaml_tag: str) -> AYO:
+    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.
@@ -71,7 +71,7 @@ def dumps_yaml(self, **pyyaml_kwargs):
         return dump(self, **pyyaml_kwargs)
 
     @classmethod
-    def loads_yaml(cls: 'Type[AYO]', yaml_str: str) -> AYO:
+    def loads_yaml(cls: 'Type[Y]', yaml_str: str) -> Y:
         """
         Utility method to
         :param yaml_str
@@ -80,7 +80,7 @@ def loads_yaml(cls: 'Type[AYO]', yaml_str: str) -> AYO:
         return cls.load_yaml(StringIO(yaml_str))
 
     @classmethod
-    def load_yaml(cls: 'Type[AYO]', file_path_or_stream: Union[str, TextIOBase]) -> AYO:
+    def load_yaml(cls: 'Type[Y]', file_path_or_stream: Union[str, TextIOBase]) -> Y:
         """
         Parses the given file path or stream as a yaml document with the
 

yamlable/tests/test_yamlable.py

@@ -4,7 +4,7 @@
 import pytest
 from yaml import dump, load
 
-from yamlable import YamlAble, yaml_info, AYO
+from yamlable import YamlAble, yaml_info, Y
 
 
 def test_yamlable_incomplete_description():
@@ -16,7 +16,7 @@ def to_yaml_dict(self) -> Dict[str, Any]:
                 return copy(vars(self))
 
             @classmethod
-            def from_yaml_dict(cls: 'Type[AYO]', dct: Dict, yaml_tag: str) -> AYO:
+            def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
                 return Foo(**dct)
 
         # instantiate
@@ -46,7 +46,7 @@ def to_yaml_dict(self) -> Dict[str, Any]:
             return copy(vars(self))
 
         @classmethod
-        def from_yaml_dict(cls: 'Type[AYO]', dct: Dict, yaml_tag: str) -> AYO:
+        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
             return Foo(**dct)
 
     # instantiate
@@ -84,7 +84,7 @@ def to_yaml_dict(self) -> Dict[str, Any]:
             return copy(vars(self))
 
         @classmethod
-        def from_yaml_dict(cls: 'Type[AYO]', dct: Dict, yaml_tag: str) -> AYO:
+        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
             return Foo_Err(**dct)
 
         @classmethod

yamlable/tests/test_yamlobjects.py

@@ -3,7 +3,7 @@
 
 import pytest
 
-from yamlable import YamlObject2, AYO
+from yamlable import YamlObject2, Y
 
 
 def test_yamlobject_incomplete_description():
@@ -33,7 +33,7 @@ def to_yaml_dict(self) -> Dict[str, Any]:
             return copy(vars(self))
 
         @classmethod
-        def from_yaml_dict(cls: 'Type[AYO]', dct: Dict, yaml_tag: str) -> AYO:
+        def from_yaml_dict(cls: 'Type[Y]', dct: Dict, yaml_tag: str) -> Y:
             return Foo(**dct)
 
     # instantiate