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

weboob/capabilities/bill.py

@@ -17,74 +17,133 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with weboob. If not, see <http://www.gnu.org/licenses/>.
 
-from datetime import datetime, date
-from .base import CapBaseObject
+from .base import CapBaseObject, StringField, DateField, FloatField
 from .collection import ICapCollection
 
 
-__all__ = ['Subscription', 'SubscriptionNotFound', 'ICapBill', 'Detail']
+__all__ = ['SubscriptionNotFound', 'BillNotFound', 'Detail', 'Bill', 'Subscription', 'ICapBill']
 
 
 class SubscriptionNotFound(Exception):
-    def __init__(self, msg=None):
-        if msg is None:
-            msg = 'Subscription not found'
+    """
+    Raised when a subscription is not found.
+    """
+    def __init__(self, msg='Subscription not found'):
         Exception.__init__(self, msg)
 
 
 class BillNotFound(Exception):
-    def __init__(self, msg=None):
-        if msg is None:
-            msg = 'Bill not found'
+    """
+    Raised when a bill is not found.
+    """
+    def __init__(self, msg='Bill not found'):
         Exception.__init__(self, msg)
 
 
 class Detail(CapBaseObject):
+    """
+    Detail of a subscription
+    """
+    label =     StringField('label of the detail line')
+    infos =     StringField('information')
+    datetime =  DateField('date information')
+    price =     FloatField('price')
+
     def __init__(self):
         CapBaseObject.__init__(self, 0)
-        self.add_field('label', basestring)
-        self.add_field('infos', basestring)
-        self.add_field('datetime', datetime)
-        self.add_field('price', float)
 
 class Bill(CapBaseObject):
+    """
+    Bill.
+    """
+    date =      DateField('date of the bill')
+    format =    StringField('format of the bill')
+    label =     StringField('label of bill')
+    idparent =  StringField('id of the parent subscription')
+
     def __init__(self):
         CapBaseObject.__init__(self, 0)
-        self.add_field('date', date)
-        self.add_field('format', basestring)
-        self.add_field('label', basestring)
-        self.add_field('idparent', basestring)
 
 class Subscription(CapBaseObject):
-    def __init__(self, id):
-        CapBaseObject.__init__(self, id)
-        self.add_field('label', basestring)
-        self.add_field('subscriber', basestring)
+    """
+    Subscription to a service.
+    """
+    label =         StringField('label of subscription')
+    subscriber =    StringField('whe has subscribed')
 
 class ICapBill(ICapCollection):
     def iter_resources(self, objs, split_path):
+        """
+        Iter resources. Will return :func:`iter_subscriptions`.
+        """
         if Subscription in objs:
             self._restrict_level(split_path)
-
             return self.iter_subscription()
 
     def iter_subscription(self):
+        """
+        Iter subscriptions.
+
+        :rtype: iter[:class:`Subscription`]
+        """
         raise NotImplementedError()
 
     def get_subscription(self, _id):
+        """
+        Get a subscription.
+
+        :param _id: ID of subscription
+        :rtype: :class:`Subscription`
+        :raises: :class:`SubscriptionNotFound`
+        """
         raise NotImplementedError()
 
     def iter_history(self, subscription):
+        """
+        Iter history of a subscription.
+
+        :param subscription: subscription to get history
+        :type subscription: :class:`Subscription`
+        :rtype: iter[:class:`Detail`]
+        """
         raise NotImplementedError()
 
     def get_bill(self, id):
+        """
+        Get a bill.
+
+        :param id: ID of bill
+        :rtype: :class:`Bill`
+        :raises: :class:`BillNotFound`
+        """
         raise NotImplementedError()
 
     def download_bill(self, id):
+        """
+        Download a bill.
+
+        :param id: ID of bill
+        :rtype: str
+        :raises: :class:`BillNotFound`
+        """
         raise NotImplementedError()
 
     def iter_bills(self, subscription):
+        """
+        Iter bills.
+
+        :param subscription: subscription to get bills
+        :type subscription: :class:`Subscription`
+        :rtype: iter[:class:`Bill`]
+        """
         raise NotImplementedError()
 
     def get_details(self, subscription):
+        """
+        Get details of a subscription.
+
+        :param subscription: subscription to get bills
+        :type subscription: :class:`Subscription`
+        :rtype: iter[:class:`Detail`]
+        """
         raise NotImplementedError()