diff --git a/docs/code.rst b/docs/code.rst index f079065..1b90499 100644 --- a/docs/code.rst +++ b/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: diff --git a/docs/conf.py b/docs/conf.py index 1b5e738..472a042 100644 --- a/docs/conf.py +++ b/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'] diff --git a/gvaldap/osusers/admin.py b/gvaldap/osusers/admin.py deleted file mode 100644 index 8c38f3f..0000000 --- a/gvaldap/osusers/admin.py +++ /dev/null @@ -1,3 +0,0 @@ -from django.contrib import admin - -# Register your models here. diff --git a/gvaldap/osusers/models.py b/gvaldap/osusers/models.py index e69de29..d1ff455 100644 --- a/gvaldap/osusers/models.py +++ b/gvaldap/osusers/models.py @@ -0,0 +1,3 @@ +""" +Empty models module required for Django to accept this as an app. +""" diff --git a/gvaldap/osusers/tasks.py b/gvaldap/osusers/tasks.py index b1be4c1..591d22a 100644 --- a/gvaldap/osusers/tasks.py +++ b/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 ` + 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 ` + 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