# HG changeset patch
# User Sandro Knauß <knauss@netzguerilla.net>
# Date 1333038435 -7200
# Node ID 52284710c0b4a15a7633e76942de64bd8ac14b66
# Parent  212a69cc4d446c45ee3389b827f261310cec97dd
iro.model: adding docstrings

diff -r 212a69cc4d44 -r 52284710c0b4 iro/model/__init__.py
--- a/iro/model/__init__.py	Thu Mar 29 17:33:10 2012 +0200
+++ b/iro/model/__init__.py	Thu Mar 29 18:27:15 2012 +0200
@@ -1,3 +1,8 @@
+"""The model pakcage represents all data, that is stored either in database or in objects.
+
+before using the model, you have to use, you have to set the Engine with :func:`dbdefer.setEngine` and set the Threadpool with :func:`dbdefer.setPool` (see :func:`iro.main.runReactor` for initalizing this module).
+"""
+
 import schema
 import user
 import utils
@@ -6,7 +11,3 @@
 
 from dbdefer import setEngine
 from pool import setPool
-
-
-
-
diff -r 212a69cc4d44 -r 52284710c0b4 iro/model/job.py
--- a/iro/model/job.py	Thu Mar 29 17:33:10 2012 +0200
+++ b/iro/model/job.py	Thu Mar 29 18:27:15 2012 +0200
@@ -109,6 +109,7 @@
         :param list recipients: list of all recipients
         :param `iro.model.message.Message` message: message to send
         :param list offers: a list of offers ( list will be reduced to the allowed offers for the **user** -- using :func:`iro.model.offer.extendProvider`)
+        :param string info: a bill group name
         :returns: the new job
         """
         user = session.merge(user)
diff -r 212a69cc4d44 -r 52284710c0b4 iro/model/schema.py
--- a/iro/model/schema.py	Thu Mar 29 17:33:10 2012 +0200
+++ b/iro/model/schema.py	Thu Mar 29 18:27:15 2012 +0200
@@ -142,7 +142,7 @@
     """A complete Job.
 
     - **status** show the status of the job (``init``, ``started``, ``sending``, ``sended`` or ``error``). 
-    - **info** is used to make it possible to create diffrent billing groups for user.
+    - **info** is used to make it possible to create different billing groups for user.
     """
     __tablename__ = "job"
     id = Column(Integer, Sequence('job_id_seq'), primary_key=True)
diff -r 212a69cc4d44 -r 52284710c0b4 iro/model/status.py
--- a/iro/model/status.py	Thu Mar 29 17:33:10 2012 +0200
+++ b/iro/model/status.py	Thu Mar 29 18:27:15 2012 +0200
@@ -1,6 +1,13 @@
 class Status:
-    '''status for one recipient'''
+    '''status object -- the resulat of one :class:`iro.controller.task.Task`.'''
     def __init__(self, provider, route, costs=0.0, count=0, exID=None):
+        """
+        :param `iro.offer.provider.Provider` provider: a provider object
+        :param string route: a route of the provider
+        :param `decimal.Decimal` costs: costs for sending this message
+        :param integer count: count of sended messages
+        :param string exID: ID of external API
+        """
         self.provider = provider
         self.route = route
 
diff -r 212a69cc4d44 -r 52284710c0b4 iro/model/user.py
--- a/iro/model/user.py	Thu Mar 29 17:33:10 2012 +0200
+++ b/iro/model/user.py	Thu Mar 29 18:27:15 2012 +0200
@@ -12,6 +12,13 @@
 @validate(kwd="apikey", func=vHash, minlength=15, maxlength=15)
 @dbdefer
 def getuser(session, apikey):
+    """Returns a valid user object.
+
+    :param session: a valid session object (is created by decorator :func:`iro.model.dbdefer.dbdefer`)
+    :param string apikey: a vaild apikey (only [0-9a-f] is allowed)
+    :return: a :class:`iro.model.schema.User` object
+    :raises: :exc:`iro.error.UserNotFound`
+    """
     user = session.query(User).filter_by(apikey=apikey).first()
     if user is None:
         raise UserNotFound()
@@ -20,6 +27,12 @@
 
 @decorator
 def vUser(f,*args,**kargs):
+    """A Decorator to verify the apikey and execute the function with a valid :class:`iro.model.schema.User` instead of the apikey.
+    
+    The decorator expect the apikey in the **user** parameter.
+
+    :return: a defer
+    """ 
     kp=getcallargs(f,*args,**kargs)
     try:
         apikey = kp["user"]