Ajout d'un peu de doc string

lc_ldap.py

@@ -79,6 +79,8 @@ def lc_ldap_test():
     return lc_ldap(dn='cn=admin,dc=crans,dc=org', cred='75bdb64f32')
 
 class lc_ldap(ldap.ldapobject.LDAPObject):
+    """Connexion à la base ldap crans, chaque instance représente une connexion
+    """
     def __init__(self, dn=None, user=None, cred=None, uri=uri):
         """Initialise la connexion ldap,
          - En authentifiant avec dn et cred s'ils sont précisés
@@ -163,12 +165,10 @@ class lc_ldap(ldap.ldapobject.LDAPObject):
         _,adherents=self.allMachinesAdherents()
         return adherents
 
-
-    
-
     def newMachine(self, parent, realm, uldif):
         """Crée une nouvelle machine: realm peut être:
-        fil, fil-v6, wifi, wifi-v6, adm, gratuit, personnel-ens, special"""
+        fil, fil-v6, wifi, wifi-v6, adm, gratuit, personnel-ens, special
+        --Partiellement implémenté"""
         #adm, serveurs, bornes, wifi, adherents, gratuit ou personnel-ens"""
         owner = self.search('objectClass=*', dn=parent, scope=0)[0]
 
@@ -218,7 +218,8 @@ class lc_ldap(ldap.ldapobject.LDAPObject):
         return self._create_entity('cid=%s,%s' % (cid[0], base_dn), uldif)
 
     def newFacture(self, uldif):
-        """Crée une nouvelle facture"""
+        """Crée une nouvelle facture
+        --Non implémenté !"""
         raise NotImplementedError()
 
     def _create_entity(self, dn, uldif):
@@ -256,7 +257,8 @@ class lc_ldap(ldap.ldapobject.LDAPObject):
 
 def new_cransldapobject(conn, dn, mode='ro', ldif = None):
     """Crée un objet CransLdap en utilisant la classe correspondant à
-    l'objectClass du ldif"""
+    l'objectClass du ldif
+    --pour usage interne à la libraire uniquement !"""
 
     classe = None
 
@@ -274,7 +276,8 @@ def new_cransldapobject(conn, dn, mode='ro', ldif = None):
     return classe(conn, dn, mode, ldif)
 
 class CransLdapObject(object):
-    """Classe de base des objets CransLdap"""
+    """Classe de base des objets CransLdap.
+    Cette classe ne devrait pas être utilisée directement."""
     def __init__(self, conn, dn, mode='ro', ldif = None):
         '''
         Créée une instance d'un objet Crans (machine, adhérent,
@@ -325,7 +328,9 @@ class CransLdapObject(object):
                 self._modifs = ldif_to_cldif(ldif_to_uldif(res[0][1]), conn, check_ctxt = False)
 
     def save(self):
-        "Vérifie que self._modifs contient des valeurs correctes et enregistre les modifications"
+        """Sauvegarde dans la base les modifications apportées à l'objet.
+        Interne: Vérifie que self._modifs contient des valeurs correctes et
+        enregistre les modifications."""
         if self.mode not in ['w', 'rw']:
             raise EnvironmentError("Objet en lecture seule, réessayer en lecture/écriture")
 
@@ -347,7 +352,7 @@ class CransLdapObject(object):
             raise EnvironmentError("Les modifications apportées à l'objet %s n'ont pas été correctement sauvegardées\n%s" % (self.dn, differences))
 
     def get_modlist(self):
-        """Renvoie le dico des modifs"""
+        """Renvoie un dictionnaire des modifications apportées à l'objet"""
         # unicode -> utf-8
         ldif = cldif_to_ldif(self._modifs)
         orig_ldif = cldif_to_ldif(self.attrs)
@@ -355,6 +360,7 @@ class CransLdapObject(object):
         return modifyModlist(orig_ldif, ldif)
 
     def get(self, attr, default):
+        """Renvoie l'attribut demandé ou default si introuvable"""
         try:
             return self[attr]
         except KeyError:
@@ -370,6 +376,7 @@ class CransLdapObject(object):
         raise KeyError(attr)
 
     def has_key(self,attr):
+        """Est-ce que notre objet a l'attribut en question ?"""
         return attr in self.ofields or attr in self.xfields or\
             attr in self.ufields or attr in self.mfields
 
@@ -420,9 +427,11 @@ class CransLdapObject(object):
         return out
 
     def blacklist_actif(self):
-        """Renvoie la liste des blacklistes actives sur l'entité"""
+        """Renvoie la liste des blacklistes actives sur l'entité
-        # XXX - Proposer de filtrer les blacklistes avec un arg supplémentaire ?
+        Améliorations possibles:
-        # XXX - Vérifier les blacklistes des machines pour les adhérents ?
+        - Proposer de filtrer les blacklistes avec un arg supplémentaire ?
+        - Vérifier les blacklistes des machines pour les adhérents ?
+        """
         attrs = (self.attrs if self.mode not in ["w", "rw"] else self._modifs)
         return filter((lambda bl: bl.is_actif()), attrs.get("blacklist",[]))
 
@@ -445,6 +454,7 @@ class CransLdapObject(object):
 
 
 class proprio(CransLdapObject):
+    u""" Un propriétaire de machine (adhérent, club…) """
     ufields = [ 'nom', 'chbre' ]
     mfields = [ 'paiement', 'info', 'blacklist', 'controle']
     ofields = []
@@ -455,7 +465,7 @@ class proprio(CransLdapObject):
         self._machines = machines
         
     def paiement_ok(self):
-        """Renvoie si le propriétaire à payé pour l'année en cours"""
+        u"""Renvoie si le propriétaire a payé pour l'année en cours"""
         if self.dn == base_dn:
             return True
         bool_paiement = False
@@ -479,6 +489,7 @@ class proprio(CransLdapObject):
                                                                
 
     def machines(self):
+        """Renvoie la liste des machines"""
         if not self._machines:
             self._machines = self.conn.search('mid=*', dn = self.dn, scope = 1)
             for m in self._machines:
@@ -486,6 +497,7 @@ class proprio(CransLdapObject):
         return self._machines
 
 class machine(CransLdapObject):
+    u""" Une machine """
     ufields = ['mid', 'macAddress', 'host', 'midType']
     ofields = []
     mfields = ['info', 'blacklist', 'hostAlias', 'exempt',
@@ -497,24 +509,29 @@ class machine(CransLdapObject):
         self._proprio = None
 
     def proprio(self):
+        u"""Renvoie le propriétaire de la machine"""
         parent_dn = self.dn.split(',', 1)[1]
         if not self._proprio:
             self._proprio = new_cransldapobject(self.conn, parent_dn, self.mode)
         return self._proprio
         
     def blacklist_actif(self):
-        """Renvoie la liste des blacklistes actives sur la machine et le proprio"""
+        u"""Renvoie la liste des blacklistes actives sur la machine et le proprio
-        # XXX - Proposer de filtrer les blacklistes avec un arg supplémentaire ?
+        Améliorations possibles:
-        # XXX - Vérifier les blacklistes des machines pour les adhérents ?
+        - Proposer de filtrer les blacklistes avec un arg supplémentaire ?
+        - Vérifier les blacklistes des machines pour les adhérents ?"""
         black=self.proprio().blacklist_actif()
         attrs = (self.attrs if self.mode not in ["w", "rw"] else self._modifs)
         black.extend(filter((lambda bl: bl.is_actif()), attrs.get("blacklist",[])))
         return  black
 
 
-class AssociationCrans(proprio): pass
+class AssociationCrans(proprio):
+    u""" Association crans (propriétaire particulier)."""
+    pass
 
 class adherent(proprio):
+    u"""Adhérent crans."""
     ufields = proprio.ufields + ['aid', 'prenom', 'tel', 'mail', 'mailInvalide']
     ofields = proprio.ofields + ['charteMA', 'adherentPayant', 'typeAdhesion',
                                  'canonicalAlias', 'solde', 'contourneGreylist',
@@ -524,8 +541,8 @@ class adherent(proprio):
     xfields = ['etudes', 'postalAddress']
 
     def compte(self,login = None, uidNumber=0, hash_pass = '', shell=config.login_shell):
-        """Renvoie le nom du compte crans, s'il n'existe pas, et que uid
+        u"""Renvoie le nom du compte crans. S'il n'existe pas, et que uid
-        est précisé, le crée"""
+        est précisé, le crée."""
 
         if u'posixAccount' in self.attrs['objectClass']:
             return self.attrs['uid'][0]
@@ -590,12 +607,16 @@ class adherent(proprio):
 
 
 class club(proprio):
+    u"""Club crans"""
     ufields = ['cid', 'responsable']
     mfields = ['imprimeurClub']
 
-class machineFixe(machine): pass
+class machineFixe(machine):
+    u"""Machine fixe"""
+    pass
 
 class machineWifi(machine):
+    u"""Machine wifi"""
     ufields = machine.ufields + ['ipsec']
 
 class machineCrans(machine):