From ec40333e103f43d8e8d2f910127dc748e250e9d3 Mon Sep 17 00:00:00 2001 From: Olivier Iffrig Date: Thu, 7 Mar 2013 18:46:09 +0100 Subject: [PATCH] Formatage Sphinx d'une partie des docstrings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Modifs non commitées qui traînaient dans ma copie, histoire d'éviter les conflits... --- attributs.py | 27 +++++++++++++++------------ doc/source/lc_ldap/attributs.rst | 3 +++ lc_ldap.py | 30 ++++++++++++++++-------------- 3 files changed, 34 insertions(+), 26 deletions(-) diff --git a/attributs.py b/attributs.py index 350d5a1..b1aa0b1 100644 --- a/attributs.py +++ b/attributs.py @@ -76,13 +76,13 @@ DROITS_SUPERVISEUR = { nounou : TOUS_DROITS, def attrify(val, attr, ldif, conn, ctxt_check = True): - """Transforme un n'importe quoi en Attr. + """Transforme un n'importe quoi en :py:class:`Attr`. Doit effectuer les normalisations et sanity check si un str ou un unicode est passé en argument. Devrait insulter en cas de potentiel problème d'encodage. - Doit effectuer les vérifications de contexte dans le *ldif* si - ctxt_check est vrai""" + Doit effectuer les vérifications de contexte dans le ``ldif`` si + ``ctxt_check`` est vrai""" if isinstance(val, Attr): return val @@ -90,7 +90,14 @@ def attrify(val, attr, ldif, conn, ctxt_check = True): return CRANS_ATTRIBUTES.get(attr, Attr)(val, ldif, conn, ctxt_check) class Attr(object): - """La liste des droits qui suffisent à avoir le droit de modifier la valeur""" + """Objet représentant un attribut. + + **Paramètres :** + + * ``val`` : valeur de l'attribut + * ``ldif`` : objet contenant l'attribut (permet de faire les validations sur l'environnement) + * ``ctxt_check`` : effectue les validations + """ legend = "Human-readable description of attribute" singlevalue = None optional = None @@ -98,6 +105,7 @@ class Attr(object): unique = False can_modify = [nounou] + """La liste des droits qui suffisent à avoir le droit de modifier la valeur""" can_view = [nounou, apprenti, soi, parent, respo] """Qui peut voir l'attribut. Par défaut, les Nounous et les Apprentis @@ -108,12 +116,7 @@ class Attr(object): """Catégorie de l'attribut (pour affichage futur)""" def __init__(self, val, ldif, conn, ctxt_check): - """Crée un nouvel objet représentant un attribut. - - val: valeur de l'attribut - ldif: objet contenant l'attribut (permet de faire les validations sur l'environnement) - ctxt_check: effectue les validations - """ + """Crée un nouvel objet représentant un attribut. """ self.ctxt_check=ctxt_check #self.value = None self.conn = conn @@ -159,7 +162,7 @@ class Attr(object): raise ValueError('%s doit avoir au moins une valeur' % self.__class__) def _check_uniqueness(self): - """Vérifie l'unicité dans la base de la valeur (mailAlias, chbre, + """Vérifie l'unicité dans la base de la valeur (``mailAlias``, ``chbre``, etc...)""" attr = self.__class__.__name__ if self.unique: @@ -169,7 +172,7 @@ class Attr(object): def _check_users_restrictions(self, values): """Vérifie les restrictions supplémentaires imposées selon les - niveaux de droits (<= 3 mailAlias, pas de mac identiques, + niveaux de droits (<= 3 ``mailAlias``, pas de mac identiques, etc...)""" ### On l'implémente dans les classes filles ! pass diff --git a/doc/source/lc_ldap/attributs.rst b/doc/source/lc_ldap/attributs.rst index 093d760..879f3a2 100644 --- a/doc/source/lc_ldap/attributs.rst +++ b/doc/source/lc_ldap/attributs.rst @@ -4,4 +4,7 @@ lc_ldap.attributs -- Conteneurs pour les attributs LDAP .. automodule:: attributs :members: + :private-members: + :special-members: + :show-inheritance: diff --git a/lc_ldap.py b/lc_ldap.py index 70098d0..036594e 100644 --- a/lc_ldap.py +++ b/lc_ldap.py @@ -78,6 +78,7 @@ current_user = os.getenv("SUDO_USER") or os.getenv("USER") # Quand on a besoin du fichier de secrets def import_secrets(): + """Importe le fichier de secrets""" if not "/etc/crans/secrets/" in sys.path: sys.path.append("/etc/crans/secrets/") import secrets @@ -127,12 +128,12 @@ class lc_ldap(ldap.ldapobject.LDAPObject, object): """ def __init__(self, dn=None, user=None, cred=None, uri=uri, test=False): """Initialise la connexion ldap, - - En authentifiant avec dn et cred s'ils sont précisés - - Si dn n'est pas précisé, mais que user est précisé, récupère - le dn associé à l'uid user, et effectue l'authentification - avec ce dn et cred + - En authentifiant avec ``dn`` et ``cred`` s'ils sont précisés + - Si ``dn`` n'est pas précisé, mais que ``user`` est précisé, récupère + le ``dn`` associé à l'uid ``user``, et effectue l'authentification + avec ce ``dn`` et ``cred`` - Sinon effectue une authentification anonyme - Si test est à True, on se connecte à la base de test sur vo. + Si ``test`` est à ``True``, on se connecte à la base de test sur ``vo``. """ if test: uri = "ldapi:///" @@ -177,8 +178,9 @@ class lc_ldap(ldap.ldapobject.LDAPObject, object): self.simple_bind_s(who=secrets.ldap_readonly_auth_dn, cred=secrets.ldap_readonly_password) def search(self, filterstr='(objectClass=*)', mode='ro', dn= base_dn, scope=ldap.SCOPE_SUBTREE, sizelimit=1000): - """La fonction de recherche dans la base ldap qui renvoie un liste de - CransLdapObjects. On utilise la feature de sizelimit de python ldap""" + """La fonction de recherche dans la base LDAP qui renvoie un liste de + :py:class:`CransLdapObject`. On utilise la feature de ``sizelimit`` de + ``python-ldap``""" ldap_res = self.search_ext_s(dn, scope, filterstr, sizelimit=sizelimit) ret = [] for dn, ldif in ldap_res: @@ -228,7 +230,7 @@ class lc_ldap(ldap.ldapobject.LDAPObject, object): return adherents def newMachine(self, parent, realm, uldif): - """Crée une nouvelle machine: realm peut être: + """Crée une nouvelle machine: ``realm`` peut être: fil, fil-v6, wifi, wifi-v6, adm, gratuit, personnel-ens, special --Partiellement implémenté""" #adm, serveurs, bornes, wifi, adherents, gratuit ou personnel-ens""" @@ -299,7 +301,7 @@ class lc_ldap(ldap.ldapobject.LDAPObject, object): raise NotImplementedError() def _create_entity(self, dn, uldif): - '''Crée une nouvelle entité ldap en dn, avec attributs ldif: + '''Crée une nouvelle entité ldap en ``dn``, avec attributs ``ldif``: uniquement en unicode''' # Conversion en cldif pour vérification des valeurs cldif = ldif_to_cldif(uldif, self) @@ -410,8 +412,8 @@ class lc_ldap_local(lc_ldap): def new_cransldapobject(conn, dn, mode='ro', ldif = None): - """Crée un objet CransLdap en utilisant la classe correspondant à - l'objectClass du ldif + """Crée un objet :py:class:`CransLdap` en utilisant la classe correspondant à + l'``objectClass`` du ``ldif`` --pour usage interne à la libraire uniquement !""" classe = None @@ -430,7 +432,7 @@ 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 :py:class:`CransLdap`. Cette classe ne devrait pas être utilisée directement.""" """ Qui peut faire quoi ? """ @@ -444,7 +446,7 @@ class CransLdapObject(object): def __init__(self, conn, dn, mode='ro', ldif = None): ''' Créée une instance d'un objet Crans (machine, adhérent, - etc...) à ce dn, si ldif est précisé, n'effectue pas de + etc...) à ce ``dn``, si ``ldif`` est précisé, n'effectue pas de recherche dans la base ldap. ''' @@ -532,7 +534,7 @@ class CransLdapObject(object): def save(self): """Sauvegarde dans la base les modifications apportées à l'objet. - Interne: Vérifie que self._modifs contient des valeurs correctes et + 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")