document the celery tasks in osusers.tasks

docs/code.rst

@@ -8,6 +8,35 @@ gvaldap is implemented as a set of `Django`_ apps.
 
 .. _Django: https://www.djangoproject.com/
 
+
+:py:mod:`ldapentities` app
+==========================
+
 .. automodule:: ldapentities
 
+
+:py:mod:`ldapenties.admin`
+--------------------------
+
+.. automodule:: ldapentities.admin
+   :members:
+
+
+:py:mod:`ldapenties.models`
+---------------------------
+
+.. automodule:: ldapentities.models
+   :members:
+
+
+:py:mod:`osusers` app
+=====================
+
 .. automodule:: osusers
+
+:py:mod:`osusers.tasks`
+-----------------------
+
+.. automodule:: osusers.tasks
+   :members:
+   :undoc-members:

docs/conf.py

@@ -27,7 +27,7 @@ sys.path.insert(0, os.path.abspath(os.path.join('..', 'gvaldap')))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['releases', 'sphinx.ext.autodoc']
+extensions = ['releases', 'sphinx.ext.autodoc', 'celery.contrib.sphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

gvaldap/osusers/admin.py

@@ -1,3 +0,0 @@
-from django.contrib import admin
-
-# Register your models here.

gvaldap/osusers/models.py

@@ -0,0 +1,3 @@
+"""
+Empty models module required for Django to accept this as an app.
+"""

gvaldap/osusers/tasks.py

@@ -1,9 +1,17 @@
+"""
+This module defines `Celery`_ tasks to manage LDAP entities.
+
+.. _Celery: http://www.celeryproject.org/
+
+"""
+
 from __future__ import absolute_import
 
 from django.core.exceptions import ObjectDoesNotExist
 from celery import shared_task
 from celery.utils.log import get_task_logger
 from celery.exceptions import Reject
+
 from ldapentities.models import (
     LdapGroup,
     LdapUser,
@@ -15,6 +23,19 @@ _logger = get_task_logger(__name__)
 
 @shared_task
 def create_ldap_group(groupname, gid, descr):
+    """
+    This task creates an :py:class:`LDAP group <ldapentities.models.LdapGroup>`
+    if it does not exist yet.
+
+    If a group with the given name exists its group id and description
+    attributes are updated.
+
+    :param str groupname: the group name
+    :param int gid: the group id
+    :param str descr: description text for the group
+    :return: the distinguished name of the group
+    :rtype: str
+    """
     try:
         ldapgroup = LdapGroup.objects.get(name=groupname)
         _logger.info(
@@ -30,6 +51,28 @@ def create_ldap_group(groupname, gid, descr):
 
 @shared_task
 def create_ldap_user(username, uid, gid, gecos, homedir, shell, password):
+    """
+    This task creates an :py:class:`LDAP user <ldapentities.models.LdapUser>`
+    if it does not exist yet.
+
+    The task is rejected if the primary group of the user is not defined.
+
+    The user's fields are updated if the user already exists.
+
+    :param str username: the user name
+    :param int uid: the user id
+    :param int gid: the user's primary group's id
+    :param str gecos: the text for the GECOS field
+    :param str homedir: the user's home directory
+    :param str shell: the user's login shell
+    :param str or None password: the clear text password, if :py:const:`None`
+        is passed the password is not touched
+    :raises celery.exceptions.Reject: if the specified primary group does not
+        exist
+    :return: the distinguished name of the user
+    :rtype: str
+
+    """
     try:
         ldapuser = LdapUser.objects.get(username=username)
         _logger.info(
@@ -64,6 +107,19 @@ def create_ldap_user(username, uid, gid, gecos, homedir, shell, password):
 
 @shared_task(bind=True)
 def add_ldap_user_to_group(self, username, groupname):
+    """
+    This task adds the specified user to the given group.
+
+    This task does nothing if the user is already member of the group.
+
+    :param str username: the user name
+    :param str groupname: the group name
+    :raises celery.exceptions.Retry: if the user does not exist yet,
+        :py:func:`create_ldap_user` should be called before
+    :return: True if the user has been added to the group otherwise False
+    :rtype: boolean
+
+    """
     try:
         ldapgroup = LdapGroup.objects.get(name=groupname)
         ldapuser = LdapUser.objects.get(username=username)
@@ -80,19 +136,40 @@ def add_ldap_user_to_group(self, username, groupname):
             _logger.info('ldap user {0} is already in group {1}'.format(
                 ldapuser.username, ldapgroup.dn)
             )
+        return True
+    return False
 
 
 @shared_task
 def remove_ldap_user_from_group(username, groupname):
+    """
+    This task removes the given user from the given group.
+
+    :param str username: the user name
+    :param str groupname: the group name
+    :return: True if the user has been removed, False otherwise
+    :rtype: boolean
+
+    """
     ldapgroup = LdapGroup.objects.get(name=groupname)
     ldapuser = LdapUser.objects.get(username=username)
-    if ldapuser.username in ldapgroup.members:
+    performdelete = ldapuser.username in ldapgroup.members
+    if performdelete:
         ldapgroup.members.remove(ldapuser.username)
     ldapgroup.save()
+    return performdelete
 
 
 @shared_task
 def delete_ldap_user(username):
+    """
+    This task deletes the given user.
+
+    :param str username: the user name
+    :return: True if the user has been deleted, False otherwise
+    :rtype: boolean
+
+    """
     try:
         ldapuser = LdapUser.objects.get(username=username)
     except LdapUser.DoesNotExist:
@@ -111,10 +188,20 @@ def delete_ldap_user(username):
                 ldapgroup.members.remove(ldapuser.username)
                 ldapgroup.save()
         ldapuser.delete()
+        return True
+    return False
 
 
 @shared_task
 def delete_ldap_group_if_empty(groupname):
+    """
+    This task deletes the given group.
+
+    :param str groupname: the group name
+    :return: True if the user has been deleted, False otherwise
+    :rtype: boolean
+
+    """
     try:
         ldapgroup = LdapGroup.objects.get(name=groupname)
     except LdapGroup.DoesNotExist:
@@ -124,7 +211,9 @@ def delete_ldap_group_if_empty(groupname):
     else:
         if len(ldapgroup.members) == 0:
             ldapgroup.delete()
+            return True
         else:
             _logger.info('ldap group {0} still has {1} members'.format(
                 ldapgroup.dn, len(ldapgroup.members))
             )
+    return False