0.2.0 - Updated documentation and changelog

Author: smarie

docs/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### 0.2.0 - Added default implementation
+
+ * By default `to_yaml_dict` returns `vars(self)` and `from_yaml_dict` returns `cls(**dct)`. Fixes [#1](https://github.com/smarie/python-yamlable/issues/1)
+
 ### 0.1.0 - First public version
 
  * Initial fork from private repository

docs/index.md

@@ -4,14 +4,16 @@
 
 [![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:
+PyYaml is a great library. However it is a bit hard for anyone to add the yaml capability to their classes while keeping control on what's happening. 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 seeing 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!
+`yamlable` provides a very easy way for you to leverage PyYaml without seeing the complexity: simply inherit from `YamlAble`, decorate with `@yaml_info`, and you're set! 
 
-In addition `yamlable` provides a way to creade Yaml codecs for several object types at the same time (`YamlCodec`) (see Usage page)
+You can then optionally override the methods `to_yaml_dict` and `from_yaml_dict` to write to / load from a dictionary, so as to adapt the yaml-ability to your class needs.
+
+In addition `yamlable` provides a way to create Yaml codecs for several object types at the same time (`YamlCodec`) (see [Usage](./usage) page)
 
 
 ## Installing
@@ -26,8 +28,8 @@ 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)
-
+ - *optionally* implement `from_yaml_dict` (class method called during decoding) and/or `to_yaml_dict` (instance method called during encoding) if we wish to have control on the process, for example to only dump part of the attributes or perform some custom instance creation. Note that default implementation relies on `vars(self)` for dumping and on `cls(**dct)` for loading.
+ 
 ```python
 from yamlable import yaml_info, YamlAble
 
@@ -43,14 +45,14 @@ class Foo(YamlAble):
     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()"""
+        """ This optional 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()"""
+        """ This optional method is called when you call yaml.load()"""
         return Foo(dct['a'], dct['b'])
 ```
 
@@ -63,23 +65,35 @@ That's it! Let's check that our class is correct and allows us to create instanc
 Foo - {'a': 1, 'b': 'hello'}
 ```
 
-The object directly has the `dump_yaml` (dumping to file) / `dumps_yaml` (dumping to string) methods:
+Now let's dump and load it using `pyyaml`:
 
 ```python
->>> print(f.dumps_yaml())
+>>> import yaml
+>>> print(yaml.dump(f))
 
 !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}"))
+>>> print(yaml.load("!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..
+For more general cases where your object is embedded in a more complex structure for example, it will work as expected:
+
+```python
+>>> d = {'foo': f, 'foo2': 12}
+>>> print(yaml.dump(d))
+
+foo: !yamlable/com.yamlable.example.Foo {a: 1, b: hello}
+foo2: 12
+```
+
+
+In addition, the object directly offers the `dump_yaml` (dumping to file) / `dumps_yaml` (dumping to string) convenience methods, and the class directly offers the `load_yaml` (load from file) / `loads_yaml` (load from string) convenience methods.
+
+See [PyYaml documentation](http://pyyaml.org/wiki/PyYAMLDocumentation) for the various formatting arguments that you can use, they are the same than in the `yaml.dump` method. For example:
 
 ```python
 >>> print(f.dumps_yaml(default_flow_style=False))
@@ -89,9 +103,6 @@ a: 1
 b: hello
 ```
 
-For more general cases where your object is embedded in a more complex structure for example, you can of course call pyyaml `dump`/`load` functions, it will work as expected.
-
-
 See [Usage](./usage) for other possibilities of `yamlable`.
 
 

docs/usage.md

@@ -2,4 +2,4 @@
 
 You have seen in the [main page](./index) a small example to understand the concepts. Below we present other advanced usages.
 
-TODO
+**TODO + explain YamlCodec**