id : <id_given_in_input>

            result : {

                         "server_ip_addr": "<ip_from_clien>",

                         "user_ips": [

                                        {

                                           "ip_addr": "<ip_with_mask>",

                                           "ip_range": ["<start_ip>", "<end_ip>"],

                                        },

                                        ...

                                     ]

            }

        """

        if isinstance(userid, Optional):

            userid = apiuser.user_id

        user = get_user_or_error(userid)

        ips = UserIpMap.query().filter(UserIpMap.user == user).all()

        return dict(

            server_ip_addr=self.ip_addr,

            user_ips=ips

        )

    # alias for old

    show_ip = get_ip

    @HasPermissionAnyDecorator('hg.admin')

    def get_server_info(self, apiuser):

        """

        return server info, including Kallithea version and installed packages

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        OUTPUT::

          id : <id_given_in_input>

          result : {

            'modules': [<module name>,...]

            'py_version': <python version>,

            'platform': <platform type>,

            'kallithea_version': <kallithea version>

          }

          error :  null

        """

        return Setting.get_server_info()

    def get_user(self, apiuser, userid=Optional(OAttr('apiuser'))):

        """

        Gets a user by username or user_id, Returns empty result if user is

        not found. If userid param is skipped it is set to id of user who is

        calling this method. This command can be executed only using api_key

        belonging to user with admin rights, or regular users that cannot

        specify different userid than theirs

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        :param userid: user to get data for

        :type userid: Optional(str or int)

        OUTPUT::

            id : <id_given_in_input>

            result: None if user does not exist or

                    {

                        "user_id" :     "<user_id>",

                        "api_key" :     "<api_key>",

                        "api_keys":     "[<list of all API keys including additional ones>]"

                        "username" :    "<username>",

                        "firstname":    "<firstname>",

                        "lastname" :    "<lastname>",

                        "email" :       "<email>",

                        "emails":       "[<list of all emails including additional ones>]",

                        "ip_addresses": "[<ip_address_for_user>,...]",

                        "active" :      "<bool: user active>",

                        "admin" :       "<bool: user is admin>",

                        "extern_name" : "<extern_name>",

                        "extern_type" : "<extern type>

                        "last_login":   "<last_login>",

                        "permissions": {

                            "global": ["hg.create.repository",

                                       "repository.read",

                                       "hg.register.manual_activate"],

                            "repositories": {"repo1": "repository.none"},

                            "repositories_groups": {"Group1": "group.read"}

                         },

                    }

            error:  null

        """

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

            # make sure normal user does not pass someone else userid,

            # he is not allowed to do that

            if not isinstance(userid, Optional) and userid != apiuser.user_id:

                raise JSONRPCError(

                    'userid is not the same as your user'

                )

        if isinstance(userid, Optional):

            userid = apiuser.user_id

        user = get_user_or_error(userid)

        data = user.get_api_data()

        data['permissions'] = AuthUser(user_id=user.user_id).permissions

        return data

    @HasPermissionAnyDecorator('hg.admin')

    def get_users(self, apiuser):

        """

        Lists all existing users. This command can be executed only using api_key

        belonging to user with admin rights.

        :param apiuser: filled automatically from apikey

        :type apiuser: AuthUser

        OUTPUT::

            id : <id_given_in_input>

            result: [<user_object>, ...]

            error:  null

        """

        result = []

        users_list = User.query().order_by(User.username) \

            .filter(User.username != User.DEFAULT_USER) \

            .all()

        for user in users_list:

            result.append(user.get_api_data())

        return result

    @HasPermissionAnyDecorator('hg.admin')

    def create_user(self, apiuser, username, email, password=Optional(''),

                    firstname=Optional(''), lastname=Optional(''),

                    active=Optional(True), admin=Optional(False),

                    extern_name=Optional(EXTERN_TYPE_INTERNAL),

                    extern_type=Optional(EXTERN_TYPE_INTERNAL)):

        """

        Creates new user. Returns new user object. 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 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: name of extern

        :type extern_name: Optional(str)

        :param extern_type: extern_type

        :type extern_type: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "created new user `<username>`",

                      "user": <user_obj>

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "user `<username>` already exist"

            or

            "email `<email>` already exist"

            or

            "failed to create user `<username>`"

          }

        """

        if User.get_by_username(username):

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

        if User.get_by_email(email):

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

        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,))

    @HasPermissionAnyDecorator('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,))

    @HasPermissionAnyDecorator('hg.admin')

    def delete_user(self, apiuser, userid):

        """

        deletes 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: 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