# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""

kallithea.controllers.admin.repo_groups

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Repository groups controller for Kallithea

This file was forked by the Kallithea project in July 2014.

Original author and date, and relevant copyright and licensing information is below:

:created_on: Mar 23, 2010

:author: marcink

:copyright: (c) 2013 RhodeCode GmbH, and others.

:license: GPLv3, see LICENSE.md for more details.

"""

import logging

import traceback

import formencode

import itertools

from formencode import htmlfill

from pylons import request, tmpl_context as c, url

from pylons.controllers.util import abort, redirect

from pylons.i18n.translation import _, ungettext

import kallithea

from kallithea.lib import helpers as h

from kallithea.lib.compat import json

from kallithea.lib.auth import LoginRequired, HasPermissionAnyDecorator,\

    HasRepoGroupPermissionAnyDecorator, HasRepoGroupPermissionAll,\

    HasPermissionAll

from kallithea.lib.base import BaseController, render

from kallithea.model.db import RepoGroup, Repository

from kallithea.model.scm import RepoGroupList

from kallithea.model.repo_group import RepoGroupModel

from kallithea.model.forms import RepoGroupForm, RepoGroupPermsForm

from kallithea.model.meta import Session

from kallithea.model.repo import RepoModel

from webob.exc import HTTPInternalServerError, HTTPNotFound

from kallithea.lib.utils2 import safe_int

from sqlalchemy.sql.expression import func

log = logging.getLogger(__name__)

class RepoGroupsController(BaseController):

    """REST Controller styled on the Atom Publishing Protocol"""

    @LoginRequired()

    def __before__(self):

        super(RepoGroupsController, self).__before__()

    def __load_defaults(self, allow_empty_group=False, exclude_group_ids=[]):

        if HasPermissionAll('hg.admin')('group edit'):

            #we're global admin, we're ok and we can create TOP level groups

            allow_empty_group = True

        #override the choices for this form, we need to filter choices

        #and display only those we have ADMIN right

        groups_with_admin_rights = RepoGroupList(RepoGroup.query().all(),

                                                 perm_set=['group.admin'])

        c.repo_groups = RepoGroup.groups_choices(groups=groups_with_admin_rights,

                                                 show_empty_group=allow_empty_group)

        # exclude filtered ids

        c.repo_groups = filter(lambda x: x[0] not in exclude_group_ids,

                               c.repo_groups)

        c.repo_groups_choices = map(lambda k: unicode(k[0]), c.repo_groups)

        repo_model = RepoModel()

        c.users_array = repo_model.get_users_js()

        c.user_groups_array = repo_model.get_user_groups_js()

    def __load_data(self, group_id):

        """

        Load defaults settings for edit, and update

        :param group_id:

        """

        repo_group = RepoGroup.get_or_404(group_id)

        data = repo_group.get_dict()

        data['group_name'] = repo_group.name

        # fill repository group users

        for p in repo_group.repo_group_to_perm:

            data.update({'u_perm_%s' % p.user.username:

                             p.permission.permission_name})

        # fill repository group groups

        for p in repo_group.users_group_to_perm:

            data.update({'g_perm_%s' % p.users_group.users_group_name:

                             p.permission.permission_name})

        return data

    def _revoke_perms_on_yourself(self, form_result):

        _up = filter(lambda u: c.authuser.username == u[0],

                     form_result['perms_updates'])

        _new = filter(lambda u: c.authuser.username == u[0],

                      form_result['perms_new'])

        if _new and _new[0][1] != 'group.admin' or _up and _up[0][1] != 'group.admin':

            return True

        return False

    def index(self, format='html'):

        """GET /repo_groups: All items in the collection"""

        # url('repos_groups')

        _list = RepoGroup.query()\

                    .order_by(func.lower(RepoGroup.group_name))\

                    .all()

        group_iter = RepoGroupList(_list, perm_set=['group.admin'])

        repo_groups_data = []

        total_records = len(group_iter)

        _tmpl_lookup = kallithea.CONFIG['pylons.app_globals'].mako_lookup

        template = _tmpl_lookup.get_template('data_table/_dt_elements.html')

        repo_group_name = lambda repo_group_name, children_groups: (

            template.get_def("repo_group_name")

            .render(repo_group_name, children_groups, _=_, h=h, c=c)

        )

        repo_group_actions = lambda repo_group_id, repo_group_name, gr_count: (

            template.get_def("repo_group_actions")

            .render(repo_group_id, repo_group_name, gr_count, _=_, h=h, c=c,

                    ungettext=ungettext)

        )

        for repo_gr in group_iter:

            children_groups = map(h.safe_unicode,

                itertools.chain((g.name for g in repo_gr.parents),

                                (x.name for x in [repo_gr])))

            repo_count = repo_gr.repositories.count()

            repo_groups_data.append({

                "raw_name": repo_gr.group_name,

                "group_name": repo_group_name(repo_gr.group_name, children_groups),

                "desc": repo_gr.group_description,

                "repos": repo_count,

                "owner": h.person(repo_gr.user),

                "action": repo_group_actions(repo_gr.group_id, repo_gr.group_name,

                                             repo_count)

            })

        c.data = json.dumps({

            "totalRecords": total_records,

            "startIndex": 0,

            "sort": None,

            "dir": "asc",

            "records": repo_groups_data

        })

        return render('admin/repo_groups/repo_groups.html')

    def create(self):

        """POST /repo_groups: Create a new item"""

        # url('repos_groups')

        self.__load_defaults()

        # permissions for can create group based on parent_id are checked

        # here in the Form

        repo_group_form = RepoGroupForm(available_groups=

                                map(lambda k: unicode(k[0]), c.repo_groups))()

        try:

            form_result = repo_group_form.to_python(dict(request.POST))

            RepoGroupModel().create(

                group_name=form_result['group_name'],

                group_description=form_result['group_description'],

                parent=form_result['group_parent_id'],

                owner=self.authuser.user_id,

                copy_permissions=form_result['group_copy_permissions']

            )

            Session().commit()

            h.flash(_('Created repository group %s') \

                    % form_result['group_name'], category='success')

            #TODO: in futureaction_logger(, '', '', '', self.sa)

        except formencode.Invalid, errors:

            return htmlfill.render(

                render('admin/repo_groups/repo_group_add.html'),

                defaults=errors.value,

                errors=errors.error_dict or {},

                prefix_error=False,

                encoding="UTF-8")

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('Error occurred during creation of repository group %s') \

                    % request.POST.get('group_name'), category='error')

        parent_group_id = form_result['group_parent_id']

        #TODO: maybe we should get back to the main view, not the admin one

        return redirect(url('repos_groups', parent_group=parent_group_id))

    def new(self):

        """GET /repo_groups/new: Form to create a new item"""

        # url('new_repos_group')

        if HasPermissionAll('hg.admin')('group create'):

            #we're global admin, we're ok and we can create TOP level groups

            pass

        else:

            # we pass in parent group into creation form, thus we know

            # what would be the group, we can check perms here !

            group_id = safe_int(request.GET.get('parent_group'))

            group = RepoGroup.get(group_id) if group_id else None

            group_name = group.group_name if group else None

            if HasRepoGroupPermissionAll('group.admin')(group_name, 'group create'):

                pass

            else:

                return abort(403)

        self.__load_defaults()

        return render('admin/repo_groups/repo_group_add.html')

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def update(self, group_name):

        """PUT /repo_groups/group_name: Update an existing item"""

        # Forms posted to this method should contain a hidden field:

        #    <input type="hidden" name="_method" value="PUT" />

        # Or using helpers:

        #    h.form(url('repos_group', group_name=GROUP_NAME),

        #           method='put')

        # url('repos_group', group_name=GROUP_NAME)

        c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        if HasPermissionAll('hg.admin')('group edit'):

            #we're global admin, we're ok and we can create TOP level groups

            allow_empty_group = True

        elif not c.repo_group.parent_group:

            allow_empty_group = True

        else:

            allow_empty_group = False

        self.__load_defaults(allow_empty_group=allow_empty_group,

                             exclude_group_ids=[c.repo_group.group_id])

        repo_group_form = RepoGroupForm(

            edit=True,

            old_data=c.repo_group.get_dict(),

            available_groups=c.repo_groups_choices,

            can_create_in_root=allow_empty_group,

        )()

        try:

            form_result = repo_group_form.to_python(dict(request.POST))

            new_gr = RepoGroupModel().update(group_name, form_result)

            Session().commit()

            h.flash(_('Updated repository group %s') \

                    % form_result['group_name'], category='success')

            # we now have new name !

            group_name = new_gr.group_name

            #TODO: in future action_logger(, '', '', '', self.sa)

        except formencode.Invalid, errors:

            return htmlfill.render(

                render('admin/repo_groups/repo_group_edit.html'),

                defaults=errors.value,

                errors=errors.error_dict or {},

                prefix_error=False,

                encoding="UTF-8")

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('Error occurred during update of repository group %s') \

                    % request.POST.get('group_name'), category='error')

        return redirect(url('edit_repo_group', group_name=group_name))

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def delete(self, group_name):

        """DELETE /repo_groups/group_name: Delete an existing item"""

        # Forms posted to this method should contain a hidden field:

        #    <input type="hidden" name="_method" value="DELETE" />

        # Or using helpers:

        #    h.form(url('repos_group', group_name=GROUP_NAME),

        #           method='delete')

        # url('repos_group', group_name=GROUP_NAME)

        gr = c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        repos = gr.repositories.all()

        if repos:

                      'deleted') % len(repos), category='warning')

            return redirect(url('repos_groups'))

        children = gr.children.all()

        if children:

            h.flash(_('This group contains %s subgroups and cannot be deleted'

                      % (len(children))), category='warning')

            return redirect(url('repos_groups'))

        try:

            RepoGroupModel().delete(group_name)

            Session().commit()

            h.flash(_('Removed repository group %s') % group_name,

                    category='success')

            #TODO: in future action_logger(, '', '', '', self.sa)

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('Error occurred during deletion of repository group %s')

                    % group_name, category='error')

        if gr.parent_group:

            return redirect(url('repos_group_home', group_name=gr.parent_group.group_name))

        return redirect(url('repos_groups'))

    def show_by_name(self, group_name):

        """

        This is a proxy that does a lookup group_name -> id, and shows

        the group by id view instead

        """

        group_name = group_name.rstrip('/')

        id_ = RepoGroup.get_by_group_name(group_name)

        if id_:

            return self.show(group_name)

        raise HTTPNotFound

    @HasRepoGroupPermissionAnyDecorator('group.read', 'group.write',

                                         'group.admin')

    def show(self, group_name):

        """GET /repo_groups/group_name: Show a specific item"""

        # url('repos_group', group_name=GROUP_NAME)

        c.active = 'settings'

        c.group = c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        c.group_repos = c.group.repositories.all()

        #overwrite our cached list with current filter

        c.repo_cnt = 0

        groups = RepoGroup.query().order_by(RepoGroup.group_name)\

            .filter(RepoGroup.group_parent_id == c.group.group_id).all()

        c.groups = self.scm_model.get_repo_groups(groups)

        c.repos_list = Repository.query()\

                        .filter(Repository.group_id == c.group.group_id)\

                        .order_by(func.lower(Repository.repo_name))\

                        .all()

        repos_data = RepoModel().get_repos_as_dict(repos_list=c.repos_list,

                                                   admin=False)

        #json used to render the grid

        c.data = json.dumps(repos_data)

        return render('admin/repo_groups/repo_group_show.html')

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def edit(self, group_name):

        """GET /repo_groups/group_name/edit: Form to edit an existing item"""

        # url('edit_repo_group', group_name=GROUP_NAME)

        c.active = 'settings'

        c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        #we can only allow moving empty group if it's already a top-level

        #group, ie has no parents, or we're admin

        if HasPermissionAll('hg.admin')('group edit'):

            #we're global admin, we're ok and we can create TOP level groups

            allow_empty_group = True

        elif not c.repo_group.parent_group:

            allow_empty_group = True

        else:

            allow_empty_group = False

        self.__load_defaults(allow_empty_group=allow_empty_group,

                             exclude_group_ids=[c.repo_group.group_id])

        defaults = self.__load_data(c.repo_group.group_id)

        return htmlfill.render(

            render('admin/repo_groups/repo_group_edit.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False

        )

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def edit_repo_group_advanced(self, group_name):

        """GET /repo_groups/group_name/edit: Form to edit an existing item"""

        # url('edit_repo_group', group_name=GROUP_NAME)

        c.active = 'advanced'

        c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        return render('admin/repo_groups/repo_group_edit.html')

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def edit_repo_group_perms(self, group_name):

        """GET /repo_groups/group_name/edit: Form to edit an existing item"""

        # url('edit_repo_group', group_name=GROUP_NAME)

        c.active = 'perms'

        c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        self.__load_defaults()

        defaults = self.__load_data(c.repo_group.group_id)

        return htmlfill.render(

            render('admin/repo_groups/repo_group_edit.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False

        )

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def update_perms(self, group_name):

        """

        Update permissions for given repository group

        :param group_name:

        """

        c.repo_group = RepoGroupModel()._get_repo_group(group_name)

        valid_recursive_choices = ['none', 'repos', 'groups', 'all']

        form_result = RepoGroupPermsForm(valid_recursive_choices)().to_python(request.POST)

        if not c.authuser.is_admin:

            if self._revoke_perms_on_yourself(form_result):

                msg = _('Cannot revoke permission for yourself as admin')

                h.flash(msg, category='warning')

                return redirect(url('edit_repo_group_perms', group_name=group_name))

        recursive = form_result['recursive']

        # iterate over all members(if in recursive mode) of this groups and

        # set the permissions !

        # this can be potentially heavy operation

        RepoGroupModel()._update_permissions(c.repo_group,

                                             form_result['perms_new'],

                                             form_result['perms_updates'],

                                             recursive)

        #TODO: implement this

        #action_logger(self.authuser, 'admin_changed_repo_permissions',

        #              repo_name, self.ip_addr, self.sa)

        Session().commit()

        h.flash(_('Repository Group permissions updated'), category='success')

        return redirect(url('edit_repo_group_perms', group_name=group_name))

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def delete_perms(self, group_name):

        """

        DELETE an existing repository group permission user

        :param group_name:

        """

        try:

            obj_type = request.POST.get('obj_type')

            obj_id = None

            if obj_type == 'user':

                obj_id = safe_int(request.POST.get('user_id'))

            elif obj_type == 'user_group':

                obj_id = safe_int(request.POST.get('user_group_id'))

            if not c.authuser.is_admin:

                if obj_type == 'user' and c.authuser.user_id == obj_id:

                    msg = _('Cannot revoke permission for yourself as admin')

                    h.flash(msg, category='warning')

                    raise Exception('revoke admin permission on self')

            recursive = request.POST.get('recursive', 'none')

            if obj_type == 'user':

                RepoGroupModel().delete_permission(repo_group=group_name,

                                                   obj=obj_id, obj_type='user',

                                                   recursive=recursive)

            elif obj_type == 'user_group':

                RepoGroupModel().delete_permission(repo_group=group_name,

                                                   obj=obj_id,

                                                   obj_type='user_group',

                                                   recursive=recursive)

            Session().commit()

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('An error occurred during revoking of permission'),

                    category='error')

            raise HTTPInternalServerError()

            "user `<username>` already exist"

            or

            "email `<email>` already exist"

            or

            "failed to create user `<username>`"

          }

        """

        if UserModel().get_by_username(username):

            raise JSONRPCError("user `%s` already exist" % (username,))

        if UserModel().get_by_email(email, case_insensitive=True):

            raise JSONRPCError("email `%s` already exist" % (email,))

        if Optional.extract(extern_name):

            # generate temporary password if user is external

            password = PasswordGenerator().gen_password(length=8)

        try:

            user = UserModel().create_or_update(

                username=Optional.extract(username),

                password=Optional.extract(password),

                email=Optional.extract(email),

                firstname=Optional.extract(firstname),

                lastname=Optional.extract(lastname),

                active=Optional.extract(active),

                admin=Optional.extract(admin),

                extern_type=Optional.extract(extern_type),

                extern_name=Optional.extract(extern_name)

            )

            Session().commit()

            return dict(

                msg='created new user `%s`' % username,

                user=user.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create user `%s`' % (username,))

    @HasPermissionAllDecorator('hg.admin')

    def update_user(self, apiuser, userid, username=Optional(None),

                    email=Optional(None),password=Optional(None),

                    firstname=Optional(None), lastname=Optional(None),

                    active=Optional(None), admin=Optional(None),

                    extern_type=Optional(None), extern_name=Optional(None),):

        """

        updates given user if such user exists. This command can

        be executed only using api_key belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param userid: userid to update

        :type userid: str or int

        :param username: new username

        :type username: str or int

        :param email: email

        :type email: str

        :param password: password

        :type password: Optional(str)

        :param firstname: firstname

        :type firstname: Optional(str)

        :param lastname: lastname

        :type lastname: Optional(str)

        :param active: active

        :type active: Optional(bool)

        :param admin: admin

        :type admin: Optional(bool)

        :param extern_name:

        :type extern_name: Optional(str)

        :param extern_type:

        :type extern_type: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "updated user ID:<userid> <username>",

                      "user": <user_object>,

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to update user `<username>`"

          }

        """

        user = get_user_or_error(userid)

        # only non optional arguments will be stored in updates

        updates = {}

        try:

            store_update(updates, username, 'username')

            store_update(updates, password, 'password')

            store_update(updates, email, 'email')

            store_update(updates, firstname, 'name')

            store_update(updates, lastname, 'lastname')

            store_update(updates, active, 'active')

            store_update(updates, admin, 'admin')

            store_update(updates, extern_name, 'extern_name')

            store_update(updates, extern_type, 'extern_type')

            user = UserModel().update_user(user, **updates)

            Session().commit()

            return dict(

                msg='updated user ID:%s %s' % (user.user_id, user.username),

                user=user.get_api_data()

            )

        except DefaultUserException:

            log.error(traceback.format_exc())

            raise JSONRPCError('editing default user is forbidden')

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update user `%s`' % (userid,))

    @HasPermissionAllDecorator('hg.admin')

    def delete_user(self, apiuser, userid):

        """

        deletes givenuser if such user exists. This command can

        be executed only using api_key belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param userid: user to delete

        :type userid: str or int

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "deleted user ID:<userid> <username>",

                      "user": null

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to delete user ID:<userid> <username>"

          }

        """

        user = get_user_or_error(userid)

        try:

            UserModel().delete(userid)

            Session().commit()

            return dict(

                msg='deleted user ID:%s %s' % (user.user_id, user.username),

                user=None

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to delete user ID:%s %s'

                               % (user.user_id, user.username))

    # permission check inside

    def get_user_group(self, apiuser, usergroupid):

        """

        Gets an existing user group. This command can be executed only using api_key

        belonging to user with admin rights or user who has at least

        read access to user group.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param usergroupid: id of user_group to edit

        :type usergroupid: str or int

        OUTPUT::

            id : <id_given_in_input>

            result : None if group not exist

                     {

                       "users_group_id" : "<id>",

                       "group_name" :     "<groupname>",

                       "active":          "<bool>",

                       "members" :  [<user_obj>,...]

                     }

            error : null

        """

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have at least read permission for this user group !

            _perms = ('usergroup.read', 'usergroup.write', 'usergroup.admin',)

            if not HasUserGroupPermissionAny(*_perms)(

                    user=apiuser, user_group_name=user_group.users_group_name):

                raise JSONRPCError('user group `%s` does not exist' % (usergroupid,))

        data = user_group.get_api_data()

        return data

    # permission check inside

    def get_user_groups(self, apiuser):

        """

        Lists all existing user groups. This command can be executed only using

        api_key belonging to user with admin rights or user who has at least

        read access to user group.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        OUTPUT::

            id : <id_given_in_input>

            result : [<user_group_obj>,...]

            error : null

        """

        result = []

        _perms = ('usergroup.read', 'usergroup.write', 'usergroup.admin',)

        extras = {'user': apiuser}

        for user_group in UserGroupList(UserGroupModel().get_all(),

                                        perm_set=_perms, extra_kwargs=extras):

            result.append(user_group.get_api_data())

        return result

    @HasPermissionAnyDecorator('hg.admin', 'hg.usergroup.create.true')

    def create_user_group(self, apiuser, group_name, description=Optional(''),

                          owner=Optional(OAttr('apiuser')), active=Optional(True)):

        """

        Creates new user group. This command can be executed only using api_key

        belonging to user with admin rights or an user who has create user group

        permission

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param group_name: name of new user group

        :type group_name: str

        :param description: group description

        :type description: str

        :param owner: owner of group. If not passed apiuser is the owner

        :type owner: Optional(str or int)

        :param active: group is active

        :type active: Optional(bool)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg": "created new user group `<groupname>`",

                      "user_group": <user_group_object>

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "user group `<group name>` already exist"

            or

            "failed to create group `<group name>`"

          }

        """

        if UserGroupModel().get_by_name(group_name):

            raise JSONRPCError("user group `%s` already exist" % (group_name,))

        try:

            if isinstance(owner, Optional):

                owner = apiuser.user_id

            owner = get_user_or_error(owner)

            active = Optional.extract(active)

            description = Optional.extract(description)

            ug = UserGroupModel().create(name=group_name, description=description,

                                         owner=owner, active=active)

            Session().commit()

            return dict(

                msg='created new user group `%s`' % group_name,

                user_group=ug.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create group `%s`' % (group_name,))

    # permission check inside

    def update_user_group(self, apiuser, usergroupid, group_name=Optional(''),

                          description=Optional(''), owner=Optional(None),

                          active=Optional(True)):

        """

        Updates given usergroup.  This command can be executed only using api_key

        belonging to user with admin rights or an admin of given user group

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param usergroupid: id of user group to update

        :type usergroupid: str or int

        :param group_name: name of new user group

        :type group_name: str

        :param description: group description

        :type description: str

        :param owner: owner of group.

        :type owner: Optional(str or int)

        :param active: group is active

        :type active: Optional(bool)

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg": 'updated user group ID:<user group id> <user group name>',

            "user_group": <user_group_object>

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to update user group `<user group name>`"

          }

        """

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this user group !

            _perms = ('usergroup.admin',)

            if not HasUserGroupPermissionAny(*_perms)(

                    user=apiuser, user_group_name=user_group.users_group_name):

                raise JSONRPCError('user group `%s` does not exist' % (usergroupid,))

        if not isinstance(owner, Optional):

            owner = get_user_or_error(owner)

        updates = {}

        store_update(updates, group_name, 'users_group_name')

        store_update(updates, description, 'user_group_description')

        store_update(updates, owner, 'user')

        store_update(updates, active, 'users_group_active')

        try:

            UserGroupModel().update(user_group, updates)

            Session().commit()

            return dict(

                msg='updated user group ID:%s %s' % (user_group.users_group_id,

                                                     user_group.users_group_name),

                user_group=user_group.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update user group `%s`' % (usergroupid,))

    # permission check inside

    def delete_user_group(self, apiuser, usergroupid):

        """

        Delete given user group by user group id or name.

        This command can be executed only using api_key

        belonging to user with admin rights or an admin of given user group

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param usergroupid:

        :type usergroupid: int

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg": "deleted user group ID:<user_group_id> <user_group_name>"

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to delete user group ID:<user_group_id> <user_group_name>"

            or

            "RepoGroup assigned to <repo_groups_list>"

          }

        """

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAnyApi('hg.admin')(user=apiuser):

            # check if we have admin permission for this user group !

            _perms = ('usergroup.admin',)

            if not HasUserGroupPermissionAny(*_perms)(

                    user=apiuser, user_group_name=user_group.users_group_name):

                raise JSONRPCError('user group `%s` does not exist' % (usergroupid,))

        try:

            UserGroupModel().delete(user_group)

            Session().commit()