From f0ecbf49140d13938d240b8e6abb080cfb238a0e Mon Sep 17 00:00:00 2001
From: gwen <gremond@cadoles.com>
Date: Mon, 6 Jan 2014 14:32:56 +0100
Subject: [PATCH] adds an extend API for the settings

---
 doc/config.txt      | 16 +++++++++++-----
 tiramisu/setting.py | 21 +++++++++++++++++++++
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/doc/config.txt b/doc/config.txt
index 3c6d9bc..f1ab1ce 100644
--- a/doc/config.txt
+++ b/doc/config.txt
@@ -10,8 +10,6 @@ Tiramisu is made of almost three main objects :
 - :class:`tiramisu.option.OptionDescription` is the shema, the option's structure
 - :class:`tiramisu.config.Config` which is the whole configuration entry point
 
-.. image:: config.png
-
 Accessing the `Option`'s
 -------------------------
 
@@ -47,9 +45,13 @@ object is returned, and if no `Option` has been declared in the
 
 The `Option` objects (in this case the :class:`~tiramisu.option.BoolOption`), 
 are organized into a tree into nested 
-:class:`~tiramisu.option.OptionDescription` objects. Every option has a name, 
-as does every option group. The parts of the full name of the option are 
-separated by dots: e.g. ``cfg.optgroup.optname``.
+:class:`~tiramisu.option.OptionDescription` objects. 
+
+.. image:: config.png
+
+Every option has a name, as does every option group. The parts 
+of the full name of the option are separated by dots: e.g. 
+``cfg.optgroup.optname``.
 
 Let's make the protocol of accessing a `Config`'s attribute explicit
 (because explicit is better than implicit):
@@ -362,6 +364,10 @@ read/write or read only mode::
     >>> c.cfgimpl_get_settings().remove('unknown')
     >>> print c.od1.var3
     value 
+
+Many properties can be defined at the same time on an option::
+
+    >>> c.cfgimpl_get_settings().extend(['unknown1', 'unknown2'])
     
 Properties can also be defined on an option group (that is, on an 
 :term:`option description`) let's hide a group and try to access to it::
diff --git a/tiramisu/setting.py b/tiramisu/setting.py
index 470ec94..3b4d2f7 100644
--- a/tiramisu/setting.py
+++ b/tiramisu/setting.py
@@ -260,6 +260,11 @@ class Property(object):
         self._properties = prop
 
     def append(self, propname):
+        """Appends a property named propname
+
+        :param propname: a predefined or user defined property name
+        :type propname: string
+        """
         if self._opt is not None and self._opt._calc_properties is not None \
                 and propname in self._opt._calc_properties:
             raise ValueError(_('cannot append {0} property for option {1}: '
@@ -269,12 +274,28 @@ class Property(object):
         self._setting._setproperties(self._properties, self._opt, self._path)
 
     def remove(self, propname):
+        """Removes a property named propname
+
+        :param propname: a predefined or user defined property name
+        :type propname: string
+        """
         if propname in self._properties:
             self._properties.remove(propname)
             self._setting._setproperties(self._properties, self._opt,
                                          self._path)
+    def extend(self, propnames):
+        """Extends properties to the existing properties
+
+        :param propnames: an iterable made of property names
+        :type propnames: iterable of string
+        """
+        for propname in propname:
+            self.append(propname)
 
     def reset(self):
+        """resets the properties (does not **clear** the properties,
+        default properties are still present)
+        """
         self._setting.reset(_path=self._path)
 
     def __contains__(self, propname):