add docstrings for ldapentities app

gvaldap/ldapentities/__init__.py

@@ -0,0 +1,7 @@
+"""
+This app takes care of managing LDAP entities, at the moment these are:
+
+* LDAP groups (:py:class:`ldapentities.models.LdapGroup`).
+* LDAP users (:py:class:`ldapentities.models.LdapUser`)
+
+"""

gvaldap/ldapentities/admin.py

@@ -1,3 +1,10 @@
+"""
+Admin classes for easy `django admin`_ based administration of LDAP entities.
+
+.. _django admin: https://docs.djangoproject.com/en/dev/ref/contrib/admin/
+
+"""
+
 from django.contrib import admin
 
 from .models import (
@@ -7,12 +14,22 @@ from .models import (
 
 
 class LdapGroupAdmin(admin.ModelAdmin):
+    """
+    Admin class for :py:class:`LDAP group <ldapentities.models.LdapGroup>`
+    entities.
+
+    """
     exclude = ['dn', 'members']
     list_display = ['name', 'gid']
     search_fields = ['name']
 
 
 class LdapUserAdmin(admin.ModelAdmin):
+    """
+    Admin class for :py:class:`LDAP user <ldapentities.models.LdapUser>`
+    entities.
+
+    """
     exclude = ['dn', 'password']
     list_display = ['username', 'uid']
     search_fields = ['username']

gvaldap/ldapentities/models.py

@@ -1,3 +1,12 @@
+"""
+This module defines models for LDAP entities.
+
+The models are based on :py:class:`ldapmodels.Model` from `django-ldapdb`_.
+
+.. _django-ldapdb: https://github.com/jlaine/django-ldapdb#readme
+
+"""
+
 from django.conf import settings
 from django.utils.encoding import python_2_unicode_compatible
 from ldapdb.models.fields import (
@@ -13,44 +22,87 @@ from passlib.hash import ldap_salted_sha1
 @python_2_unicode_compatible
 class LdapGroup(ldapmodels.Model):
     """
-    Class for representing an LDAP group entity.
+    Class for representing an LDAP group entity with objectClass `posixGroup`.
+
+    .. seealso:: :rfc:`2307#section-4`
+
+    .. py:attribute:: base_dn
+
+       a string containing the LDAP base distinguished name
+
+    .. py:attribute:: members
+
+       contains the list of `memberUid` attributes
 
     """
     # LDAP meta-data
     base_dn = settings.GROUP_BASE_DN
+    #: list of object classes
     object_classes = ['posixGroup']
 
     # posixGroup attributes
+    #: group id (`gidNumber`)
     gid = IntegerField(db_column='gidNumber', unique=True)
+    #: group name (`cn`)
     name = CharField(db_column='cn', max_length=200, primary_key=True)
+    #: group description (`description`)
     description = CharField(db_column='description')
     members = ListField(db_column='memberUid', blank=True)
 
     def __str__(self):
+        """
+        Get a string representation of this LDAP group.
+        """
         return self.name
 
 
 @python_2_unicode_compatible
 class LdapUser(ldapmodels.Model):
     """
-    Class for representing an LDAP user entity.
+    Class for representing an LDAP user entity with objectClasses `account` and
+    `posixAccount`.
+
+    .. seealso:: :rfc:`2307#section-4`, :rfc:`4524#section-3.1`
+
+    .. py:attribute:: base_dn
+
+       a string containing the LDAP base distinguished name
 
     """
     base_dn = settings.USER_BASE_DN
+    #: list of object classes
     object_classes = ['account', 'posixAccount']
 
     # posixAccount
+    #: user id (`uidNumber`)
     uid = IntegerField(db_column='uidNumber', unique=True)
+    #: group id (`gidNumber`) of the user's primary group
     group = IntegerField(db_column='gidNumber')
+    #: GECOS field (`gecos`)
     gecos = CharField(db_column='gecos')
+    #: home directory (`homeDirectory`)
     home_directory = CharField(db_column='homeDirectory')
+    #: login shell (`loginShell`)
     login_shell = CharField(db_column='loginShell', default='/bin/bash')
+    #: user name (`uid`)
     username = CharField(db_column='uid', primary_key=True)
+    #: password (`userPassword`) in an LDAP compatible format
     password = CharField(db_column='userPassword')
+    #: common name (`cn`)
     common_name = CharField(db_column='cn')
 
     def __str__(self):
+        """
+        Get a string representation of this LDAP user.
+        """
         return self.username
 
     def set_password(self, password):
+        """
+        Sets the encrypted password of the user from the given clear text
+        password.
+
+        :param str password: the clear text password
+
+        """
         self.password = ldap_salted_sha1.encrypt(password)

gvaldap/ldapentities/tests.py

@@ -1,3 +0,0 @@
-from django.test import TestCase
-
-# Create your tests here.