"""
This module defines task stubs for the tasks implemented on the Celery
workers.

"""
from __future__ import absolute_import

from celery import shared_task


@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
    """


@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

    """


@shared_task
def add_ldap_user_to_group(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

    """


@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

    """


@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

    """


@shared_task
def delete_ldap_group_if_empty(groupname):
    """
    This task deletes the given group if it is empty.

    :param str groupname: the group name
    :return: True if the user has been deleted, False otherwise
    :rtype: boolean

    """


@shared_task
def delete_ldap_group(groupname):
    """
    This taks deletes the given group.

    :param str groupname: the group name
    :return: True if the user has been deleted, False otherwise
    :rtype: boolean

    """


@shared_task
def setup_file_sftp_userdir(username):
    """
    This task creates the home directory for an SFTP user if it does not exist
    yet.

    :param str username: the user name
    :raises Exception: if the SFTP directory of the user cannot be created
    :return: the created directory name
    :rtype: str

    """


@shared_task
def delete_file_sftp_userdir(username):
    """
    This task recursively deletes the home directory of an SFTP user if it
    does not exist yet.

    :param str username: the user name
    :raises Exception: if the SFTP directory of the user cannot be removed
    :return: the removed directory name
    :rtype: str

    """


@shared_task
def setup_file_mail_userdir(username):
    """
    This task creates the mail base directory for a user if it does not exist
    yet.

    :param str username: the user name
    :raises Exception: if the mail base directory for the user cannot be
        created
    :return: the created directory name
    :rtype: str

    """


@shared_task
def delete_file_mail_userdir(username):
    """
    This task recursively deletes the mail base directory for a user if it
    does not exist yet.

    :param str username: the user name
    :raises Exception: if the mail base directory of the user cannot be removed
    :return: the removed directory name
    :rtype: str

    """


@shared_task
def create_file_mailbox(username, mailboxname):
    """
    This task creates a new mailbox directory for the given user and mailbox
    name.

    :param str username: the user name
    :param str mailboxname: the mailbox name
    :raises GVAFileException: if the mailbox directory cannot be created
    :return: the created mailbox directory name
    :rtype: str

    """


@shared_task
def delete_file_mailbox(username, mailboxname):
    """
    This task deletes the given mailbox of the given user.

    :param str username: the user name
    :param str mailboxname: the mailbox name
    :raises GVAFileException: if the mailbox directory cannot be deleted
    :return: the deleted mailbox directory name
    :rtype: str

    """