# Additional mappings that are not present in the pygments lexers

# used for building stats

# format is {'ext':['Names']} eg. {'py':['Python']} note: there can be

# more than one name for extension

# NOTE: that this will overide any mappings in LANGUAGES_EXTENSIONS_MAP

# build by pygments

EXTRA_MAPPINGS = {}

# additional lexer definitions for custom files

# it's overrides pygments lexers, and uses defined name of lexer to colorize the

# files. Format is {'ext': 'lexer_name'}

# List of lexers can be printed running:

# python -c "import pprint;from pygments import lexers;pprint.pprint([(x[0], x[1]) for x in lexers.get_all_lexers()]);"

EXTRA_LEXERS = {}

#==============================================================================

# WHOOSH INDEX EXTENSIONS

#==============================================================================

# if INDEX_EXTENSIONS is [] it'll use pygments lexers extensions by default.

# To set your own just add to this list extensions to index with content

INDEX_EXTENSIONS = []

# additional extensions for indexing besides the default from pygments

# those gets added to INDEX_EXTENSIONS

EXTRA_INDEX_EXTENSIONS = []

#==============================================================================

# POST CREATE REPOSITORY HOOK

#==============================================================================

# this function will be executed after each repository is created

def _crrepohook(*args, **kwargs):

    """

    Post create repository HOOK

    kwargs available:

     :param repo_name:

     :param repo_type:

     :param description:

     :param private:

     :param created_on:

     :param enable_downloads:

     :param repo_id:

     :param enable_statistics:

     :param clone_uri:

     :param fork_id:

     :param group_id:

     :param created_by:

    """

    return 0

CREATE_REPO_HOOK = _crrepohook

#==============================================================================

# PRE CREATE USER HOOK

#==============================================================================

# this function will be executed before each user is created

def _pre_cruserhook(*args, **kwargs):

    """

    Pre create user HOOK, it returns a tuple of bool, reason.

    If bool is False the user creation will be stopped and reason

    will be displayed to the user.

    kwargs available:

    :param username:

    :param password:

    :param email:

    :param firstname:

    :param lastname:

    :param active:

    :param admin:

    :param created_by:

    """

    reason = 'allowed'

    return True, reason

PRE_CREATE_USER_HOOK = _pre_cruserhook

#==============================================================================

# POST CREATE USER HOOK

#==============================================================================

# this function will be executed after each user is created

def _cruserhook(*args, **kwargs):

    """

    Post create user HOOK

    kwargs available:

      :param username:

      :param full_name_or_username:

      :param full_contact:

      :param user_id:

      :param name:

      :param firstname:

      :param short_contact:

      :param admin:

      :param lastname:

      :param ip_addresses:

      :param ldap_dn:

      :param email:

      :param api_key:

      :param last_login:

      :param full_name:

      :param active:

      :param password:

      :param emails:

      :param inherit_default_permissions:

      :param created_by:

    """

    return 0

CREATE_USER_HOOK = _cruserhook

#==============================================================================

# POST DELETE REPOSITORY HOOK

#==============================================================================

# this function will be executed after each repository deletion

def _dlrepohook(*args, **kwargs):

    """

    Post delete repository HOOK

    kwargs available:

     :param repo_name:

     :param repo_type:

     :param description:

     :param private:

     :param created_on:

     :param enable_downloads:

     :param repo_id:

     :param enable_statistics:

     :param clone_uri:

     :param fork_id:

     :param group_id:

     :param deleted_by:

     :param deleted_on:

    """

    return 0

DELETE_REPO_HOOK = _dlrepohook

#==============================================================================

# POST DELETE USER HOOK

#==============================================================================

# this function will be executed after each user is deleted

def _dluserhook(*args, **kwargs):

    """

    Post delete user HOOK

    kwargs available:

      :param username:

      :param full_name_or_username:

      :param full_contact:

      :param user_id:

      :param name:

      :param firstname:

      :param short_contact:

      :param admin:

      :param lastname:

      :param ip_addresses:

      :param ldap_dn:

      :param email:

      :param api_key:

      :param last_login:

      :param full_name:

      :param active:

      :param password:

      :param emails:

      :param inherit_default_permissions:

      :param deleted_by:

    """

    return 0

DELETE_USER_HOOK = _dluserhook

#==============================================================================

# POST PUSH HOOK

#==============================================================================

# this function will be executed after each push it's executed after the

# build-in hook that Kallithea uses for logging pushes

def _pushhook(*args, **kwargs):

    """

    Post push hook

    kwargs available:

      :param server_url: url of instance that triggered this hook

      :param config: path to .ini config used

      :param scm: type of VS 'git' or 'hg'

      :param username: name of user who pushed

      :param ip: ip of who pushed

      :param action: push

      :param repository: repository name

      :param pushed_revs: list of pushed revisions

    """

    return 0

PUSH_HOOK = _pushhook

#==============================================================================

# POST PULL HOOK

#==============================================================================

# this function will be executed after each push it's executed after the

# build-in hook that Kallithea uses for logging pulls

def _pullhook(*args, **kwargs):

    """

    Post pull hook

    kwargs available::

      :param server_url: url of instance that triggered this hook

      :param config: path to .ini config used

      :param scm: type of VS 'git' or 'hg'

      :param username: name of user who pulled

      :param ip: ip of who pulled

      :param action: pull

      :param repository: repository name

    """

    return 0

PULL_HOOK = _pullhook

# -*- 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.my_account

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

my account controller for Kallithea admin

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: August 20, 2013

:author: marcink

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

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

"""

import logging

import traceback

import formencode

from sqlalchemy import func

from formencode import htmlfill

from pylons import request, tmpl_context as c

from pylons.i18n.translation import _

from webob.exc import HTTPFound

from kallithea.config.routing import url

from kallithea.lib import helpers as h

from kallithea.lib import auth_modules

from kallithea.lib.auth import LoginRequired, NotAnonymous, AuthUser

from kallithea.lib.base import BaseController, render

from kallithea.lib.utils2 import generate_api_key, safe_int

from kallithea.lib.compat import json

from kallithea.model.db import Repository, UserEmailMap, User, UserFollowing

from kallithea.model.forms import UserForm, PasswordChangeForm

from kallithea.model.user import UserModel

from kallithea.model.repo import RepoModel

from kallithea.model.api_key import ApiKeyModel

from kallithea.model.meta import Session

log = logging.getLogger(__name__)

class MyAccountController(BaseController):

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

    # To properly map this controller, ensure your config/routing.py

    # file has a resource setup:

    #     map.resource('setting', 'settings', controller='admin/settings',

    #         path_prefix='/admin', name_prefix='admin_')

    @LoginRequired()

    @NotAnonymous()

    def __before__(self):

        super(MyAccountController, self).__before__()

    def __load_data(self):

        c.user = User.get(self.authuser.user_id)

        if c.user.username == User.DEFAULT_USER:

            h.flash(_("You can't edit this user since it's"

                      " crucial for entire application"), category='warning')

            raise HTTPFound(location=url('users'))

    def _load_my_repos_data(self, watched=False):

        if watched:

            admin = False

            repos_list = Session().query(Repository) \

                         .join(UserFollowing) \

                         .filter(UserFollowing.user_id ==

                                 self.authuser.user_id).all()

        else:

            admin = True

            repos_list = Session().query(Repository) \

                                 self.authuser.user_id).all()

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

                                                   admin=admin)

        #json used to render the grid

        return json.dumps(repos_data)

    def my_account(self):

        c.active = 'profile'

        self.__load_data()

        c.perm_user = AuthUser(user_id=self.authuser.user_id)

        c.ip_addr = self.ip_addr

        managed_fields = auth_modules.get_managed_fields(c.user)

        def_user_perms = User.get_default_user().AuthUser.permissions['global']

        if 'hg.register.none' in def_user_perms:

            managed_fields.extend(['username', 'firstname', 'lastname', 'email'])

        c.readonly = lambda n: 'readonly' if n in managed_fields else None

        defaults = c.user.get_dict()

        update = False

        if request.POST:

            _form = UserForm(edit=True,

                             old_data={'user_id': self.authuser.user_id,

                                       'email': self.authuser.email})()

            form_result = {}

            try:

                post_data = dict(request.POST)

                post_data['new_password'] = ''

                post_data['password_confirmation'] = ''

                form_result = _form.to_python(post_data)

                # skip updating those attrs for my account

                skip_attrs = ['admin', 'active', 'extern_type', 'extern_name',

                              'new_password', 'password_confirmation',

                             ] + managed_fields

                UserModel().update(self.authuser.user_id, form_result,

                                   skip_attrs=skip_attrs)

                h.flash(_('Your account was updated successfully'),

                        category='success')

                Session().commit()

                update = True

            except formencode.Invalid as errors:

                return htmlfill.render(

                    render('admin/my_account/my_account.html'),

                    defaults=errors.value,

                    errors=errors.error_dict or {},

                    prefix_error=False,

                    encoding="UTF-8",

                    force_defaults=False)

            except Exception:

                log.error(traceback.format_exc())

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

                        % form_result.get('username'), category='error')

        if update:

            raise HTTPFound(location='my_account')

        return htmlfill.render(

            render('admin/my_account/my_account.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False)

    def my_account_password(self):

        c.active = 'password'

        self.__load_data()

        managed_fields = auth_modules.get_managed_fields(c.user)

        c.can_change_password = 'password' not in managed_fields

        if request.POST and c.can_change_password:

            _form = PasswordChangeForm(self.authuser.username)()

            try:

                form_result = _form.to_python(request.POST)

                UserModel().update(self.authuser.user_id, form_result)

                Session().commit()

                h.flash(_("Successfully updated password"), category='success')

            except formencode.Invalid as errors:

                return htmlfill.render(

                    render('admin/my_account/my_account.html'),

                    defaults=errors.value,

                    errors=errors.error_dict or {},

                    prefix_error=False,

                    encoding="UTF-8",

                    force_defaults=False)

            except Exception:

                log.error(traceback.format_exc())

                h.flash(_('Error occurred during update of user password'),

                        category='error')

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

    def my_account_repos(self):

        c.active = 'repos'

        self.__load_data()

        #json used to render the grid

from kallithea.lib.auth import LoginRequired, \

    HasRepoGroupPermissionAnyDecorator, HasRepoGroupPermissionAny, \

    HasPermissionAny

from kallithea.lib.base import BaseController, render

from kallithea.model.db import RepoGroup, Repository

from kallithea.model.scm import RepoGroupList, AvailableRepoGroupChoices

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 kallithea.lib.utils2 import safe_int

from sqlalchemy.sql.expression import func

log = logging.getLogger(__name__)

class RepoGroupsController(BaseController):

    @LoginRequired()

    def __before__(self):

        super(RepoGroupsController, self).__before__()

    def __load_defaults(self, extras=(), exclude=()):

        """extras is used for keeping current parent ignoring permissions

        exclude is used for not moving group to itself TODO: also exclude descendants

        Note: only admin can create top level groups

        """

        repo_groups = AvailableRepoGroupChoices([], ['group.admin'], extras)

        exclude_group_ids = set(rg.group_id for rg in exclude)

        c.repo_groups = [rg for rg in repo_groups

                         if rg[0] not in exclude_group_ids]

        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'):

        _list = RepoGroup.query(sorted=True).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": h.escape(repo_gr.group_description),

                "repos": repo_count,

                "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):

        self.__load_defaults()

        # permissions for can create group based on parent_id are checked

        # here in the Form

        repo_group_form = RepoGroupForm(repo_groups=c.repo_groups)

        try:

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

            gr = 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, # TODO: make editable

                copy_permissions=form_result['group_copy_permissions']

            )

            Session().commit()

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

        except formencode.Invalid as 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",

                force_defaults=False)

        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

            raise HTTPFound(location=url('repos_groups', parent_group=parent_group_id))

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

                category='success')

        raise HTTPFound(location=url('repos_group_home', group_name=gr.group_name))

    def new(self):

        if HasPermissionAny('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 HasRepoGroupPermissionAny('group.admin')(group_name, 'group create'):

                pass

            else:

                raise HTTPForbidden()

        self.__load_defaults()

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

    @HasRepoGroupPermissionAnyDecorator('group.admin')

    def update(self, group_name):

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

        self.__load_defaults(extras=[c.repo_group.parent_group],

                             exclude=[c.repo_group])

        # TODO: kill allow_empty_group - it is only used for redundant form validation!

        if HasPermissionAny('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

        repo_group_form = RepoGroupForm(

            edit=True,

            old_data=c.repo_group.get_dict(),

            repo_groups=c.repo_groups,

            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 !

:created_on: Jan 25, 2011

:author: marcink

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

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

"""

import logging

import traceback

import formencode

from formencode import htmlfill

from pylons import request, tmpl_context as c, config

from pylons.i18n.translation import _

from webob.exc import HTTPFound

from sqlalchemy.orm import joinedload

from sqlalchemy.sql.expression import func

from webob.exc import HTTPInternalServerError

import kallithea

from kallithea.config.routing import url

from kallithea.lib import helpers as h

from kallithea.lib.exceptions import UserGroupsAssignedException, \

    RepoGroupAssignmentError

from kallithea.lib.utils2 import safe_unicode, safe_int

from kallithea.lib.auth import LoginRequired, \

    HasUserGroupPermissionAnyDecorator, HasPermissionAnyDecorator

from kallithea.lib.base import BaseController, render

from kallithea.model.scm import UserGroupList

from kallithea.model.user_group import UserGroupModel

from kallithea.model.repo import RepoModel

from kallithea.model.db import User, UserGroup, UserGroupToPerm, \

    UserGroupRepoToPerm, UserGroupRepoGroupToPerm

from kallithea.model.forms import UserGroupForm, UserGroupPermsForm, \

    CustomDefaultPermissionsForm

from kallithea.model.meta import Session

from kallithea.lib.utils import action_logger

from kallithea.lib.compat import json

log = logging.getLogger(__name__)

class UserGroupsController(BaseController):

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

    @LoginRequired()

    def __before__(self):

        super(UserGroupsController, self).__before__()

        c.available_permissions = config['available_permissions']

    def __load_data(self, user_group_id):

        c.group_members_obj = sorted((x.user for x in c.user_group.members),

                                     key=lambda u: u.username.lower())

        c.group_members = [(x.user_id, x.username) for x in c.group_members_obj]

        c.available_members = sorted(((x.user_id, x.username) for x in

                                      User.query().all()),

                                     key=lambda u: u[1].lower())

    def __load_defaults(self, user_group_id):

        """

        Load defaults settings for edit, and update

        :param user_group_id:

        """

        user_group = UserGroup.get_or_404(user_group_id)

        data = user_group.get_dict()

        return data

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

        _list = UserGroup.query() \

                        .order_by(func.lower(UserGroup.users_group_name)) \

                        .all()

        group_iter = UserGroupList(_list, perm_set=['usergroup.admin'])

        user_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')

        user_group_name = lambda user_group_id, user_group_name: (

            template.get_def("user_group_name")

            .render(user_group_id, user_group_name, _=_, h=h, c=c)

        )

        user_group_actions = lambda user_group_id, user_group_name: (

            template.get_def("user_group_actions")

            .render(user_group_id, user_group_name, _=_, h=h, c=c)

        )

        for user_gr in group_iter:

            user_groups_data.append({

                "raw_name": user_gr.users_group_name,

                "group_name": user_group_name(user_gr.users_group_id,

                                              user_gr.users_group_name),

                "desc": h.escape(user_gr.user_group_description),

                "members": len(user_gr.members),

                "active": h.boolicon(user_gr.users_group_active),

                "action": user_group_actions(user_gr.users_group_id, user_gr.users_group_name)

            })

        c.data = json.dumps({

            "totalRecords": total_records,

            "startIndex": 0,

            "sort": None,

            "dir": "asc",

            "records": user_groups_data

        })

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

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

    def create(self):

        users_group_form = UserGroupForm()()

        try:

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

            ug = UserGroupModel().create(name=form_result['users_group_name'],

                                         description=form_result['user_group_description'],

                                         owner=self.authuser.user_id,

                                         active=form_result['users_group_active'])

            gr = form_result['users_group_name']

            action_logger(self.authuser,

                          'admin_created_users_group:%s' % gr,

                          None, self.ip_addr, self.sa)

            h.flash(h.literal(_('Created user group %s') % h.link_to(h.escape(gr), url('edit_users_group', id=ug.users_group_id))),

                category='success')

            Session().commit()

        except formencode.Invalid as errors:

            return htmlfill.render(

                render('admin/user_groups/user_group_add.html'),

                defaults=errors.value,

                errors=errors.error_dict or {},

                prefix_error=False,

                encoding="UTF-8",

                force_defaults=False)

        except Exception:

            log.error(traceback.format_exc())

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

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

        raise HTTPFound(location=url('users_groups'))

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

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

        return render('admin/user_groups/user_group_add.html')

    @HasUserGroupPermissionAnyDecorator('usergroup.admin')

    def update(self, id):

        c.user_group = UserGroup.get_or_404(id)

        c.active = 'settings'

        self.__load_data(id)

        available_members = [safe_unicode(x[0]) for x in c.available_members]

        users_group_form = UserGroupForm(edit=True,

                                         old_data=c.user_group.get_dict(),

                                         available_members=available_members)()

        try:

            form_result = users_group_form.to_python(request.POST)

            UserGroupModel().update(c.user_group, form_result)

            gr = form_result['users_group_name']

            action_logger(self.authuser,

                          'admin_updated_users_group:%s' % gr,

                          None, self.ip_addr, self.sa)

            h.flash(_('Updated user group %s') % gr, category='success')

            Session().commit()

        except formencode.Invalid as errors:

            ug_model = UserGroupModel()

            defaults = errors.value

            e = errors.error_dict or {}

            defaults.update({

                'create_repo_perm': ug_model.has_perm(id,

                                                      'hg.create.repository'),

                'fork_repo_perm': ug_model.has_perm(id,

                                                    'hg.fork.repository'),

            })

            return htmlfill.render(

                render('admin/user_groups/user_group_edit.html'),

                defaults=defaults,

                errors=e,

                prefix_error=False,

                encoding="UTF-8",

                force_defaults=False)

        except Exception:

            log.error(traceback.format_exc())

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

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

        raise HTTPFound(location=url('edit_users_group', id=id))

    @HasUserGroupPermissionAnyDecorator('usergroup.admin')

        :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 = self.authuser.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, 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 usergroupid: id of user group to update