change way to describe fields of CapBaseObject, and lot of documentation

weboob/capabilities/dating.py

@@ -18,55 +18,103 @@
 # along with weboob. If not, see <http://www.gnu.org/licenses/>.
 
 
-import datetime
-
-from .base import IBaseCap, CapBaseObject
+from .base import IBaseCap, CapBaseObject, Field, StringField, DateField
 from .contact import Contact
 
 
-__all__ = ['ICapDating']
+__all__ = ['OptimizationNotFound', 'Optimization', 'Event', 'ICapDating']
 
 
 class OptimizationNotFound(Exception):
-    pass
+    """
+    Raised when an optimization is not found.
+    """
 
 
 class Optimization(object):
-    # Configuration of optim can be made by Value*s in this dict.
+    """
+    Optimization.
+
+    :var CONFIG: Configuration of optim can be made by
+                 :class:`weboob.tools.value.Value` objects
+                 in this dict.
+    """
     CONFIG = {}
 
     def start(self):
+        """
+        Start optimization.
+        """
         raise NotImplementedError()
 
     def stop(self):
+        """
+        Stop optimization.
+        """
         raise NotImplementedError()
 
     def is_running(self):
+        """
+        Know if the optimization is currently running.
+
+        :rtype: bool
+        """
         raise NotImplementedError()
 
     def get_config(self):
+        """
+        Get config of this optimization.
+
+        :rtype: dict
+        """
         return None
 
     def set_config(self, params):
+        """
+        Set config of this optimization.
+
+        :param params: parameters
+        :type params: dict
+        """
         raise NotImplementedError()
 
 
 class Event(CapBaseObject):
-    def __init__(self, id):
-        CapBaseObject.__init__(self, id)
-        self.add_field('date', (datetime.datetime))
-        self.add_field('contact', Contact)
-        self.add_field('type', basestring)
-        self.add_field('message', basestring)
+    """
+    A dating event (for example a visite, a query received, etc.)
+    """
+    date =      DateField('Date of event')
+    contact =   Field('Contact related to this event', Contact)
+    type =      StringField('Type of event')
+    message =   StringField('Message of the event')
 
 class ICapDating(IBaseCap):
+    """
+    Capability for dating websites.
+    """
     def init_optimizations(self):
+        """
+        Initialization of optimizations.
+        """
         raise NotImplementedError()
 
     def add_optimization(self, name, optim):
+        """
+        Add an optimization.
+
+        :param name: name of optimization
+        :type name: str
+        :param optim: optimization
+        :type optim: :class:`Optimization`
+        """
         setattr(self, 'OPTIM_%s' % name, optim)
 
-    def iter_optimizations(self, *optims):
+    def iter_optimizations(self):
+        """
+        Iter optimizations.
+
+        :rtype: iter[:class:`Optimization`]
+        """
         for attr_name in dir(self):
             if not attr_name.startswith('OPTIM_'):
                 continue
@@ -77,6 +125,13 @@ class ICapDating(IBaseCap):
             yield attr_name[6:], attr
 
     def get_optimization(self, optim):
+        """
+        Get an optimization from a name.
+
+        :param optim: name of optimization
+        :type optim: str
+        :rtype: :class:`Optimization`
+        """
         optim = optim.upper()
         if not hasattr(self, 'OPTIM_%s' % optim):
             raise OptimizationNotFound()
@@ -84,4 +139,9 @@ class ICapDating(IBaseCap):
         return getattr(self, 'OPTIM_%s' % optim)
 
     def iter_events(self):
+        """
+        Iter events.
+
+        :rtype: iter[:class:`Event`]
+        """
         raise NotImplementedError()