Defines an optional parameter::

        param = param.getval() if isinstance(param, Optional) else param

        param = param() if isinstance(param, Optional) else param

    is equivalent of::

        param = Optional.extract(param)

    """

    def __init__(self, type_):

        self.type_ = type_

    def __repr__(self):

        return '<Optional:%s>' % self.type_.__repr__()

    def __call__(self):

        return self.getval()

    def getval(self):

        """

        returns value from this Optional instance

        """

        return self.type_

    @classmethod

    def extract(cls, val):

        if isinstance(val, cls):

            return val.getval()

        return val

def get_user_or_error(userid):

    """

    Get user by id or name or return JsonRPCError if not found

    :param userid:

    """

    user = UserModel().get_user(userid)

    if user is None:

        raise JSONRPCError("user `%s` does not exist" % userid)

    return user

def get_repo_or_error(repoid):

    """

    Get repo by id or name or return JsonRPCError if not found

    """

    repo = RepoModel().get_repo(repoid)

    if repo is None:

        raise JSONRPCError('repository `%s` does not exist' % (repoid))

    return repo

def get_users_group_or_error(usersgroupid):

    """

    Get user group by id or name or return JsonRPCError if not found

    :param userid:

    """

    users_group = UserGroupModel().get_group(usersgroupid)

    if users_group is None:

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

    return users_group

def get_perm_or_error(permid):

    """

    Get permission by id or name or return JsonRPCError if not found

    :param userid:

    """

    perm = Permission.get_by_key(permid)

    if perm is None:

        raise JSONRPCError('permission `%s` does not exist' % (permid))

    return perm

class ApiController(JSONRPCController):

    """

    API Controller

    Each method needs to have USER as argument this is then based on given

    API_KEY propagated as instance of user object

    Preferably this should be first argument also

    Each function should also **raise** JSONRPCError for any

    errors that happens

    """

    @HasPermissionAllDecorator('hg.admin')

        Dispatch pull action on given repo

        :param apiuser:

        :param repoid:

        """

        repo = get_repo_or_error(repoid)

        try:

            ScmModel().pull_changes(repo.repo_name,

                                    self.rhodecode_user.username)

            return 'Pulled from `%s`' % repo.repo_name

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'Unable to pull changes from `%s`' % repo.repo_name

            )

    @HasPermissionAllDecorator('hg.admin')

    def rescan_repos(self, apiuser, remove_obsolete=Optional(False)):

        """

        Dispatch rescan repositories action. If remove_obsolete is set

        than also delete repos that are in database but not in the filesystem.

        aka "clean zombies"

        :param apiuser:

        :param remove_obsolete:

        """

        try:

            rm_obsolete = Optional.extract(remove_obsolete)

            added, removed = repo2db_mapper(ScmModel().repo_scan(),

                                            remove_obsolete=rm_obsolete)

            return {'added': added, 'removed': removed}

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'Error occurred during rescan repositories action'

            )

    def invalidate_cache(self, apiuser, repoid):

        """

        Dispatch cache invalidation action on given repo

        :param apiuser:

        :param repoid:

        """

        repo = get_repo_or_error(repoid)

            # check if we have admin permission for this repo !

            if HasRepoPermissionAnyApi('repository.admin',

                                       'repository.write')(user=apiuser,

                                            repo_name=repo.repo_name) is False:

                raise JSONRPCError('repository `%s` does not exist' % (repoid))

        try:

            ScmModel().mark_for_invalidation(repo.repo_name)

            return ('Caches of repository `%s` was invalidated' % repoid)

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'Error occurred during cache invalidation action'

            )

    def lock(self, apiuser, repoid, locked=Optional(None),

             userid=Optional(OAttr('apiuser'))):

        """

        Set locking state on particular repository by given user, if

        this command is runned by non-admin account userid is set to user

        who is calling this method

        :param apiuser:

        :param repoid:

        :param userid:

        :param locked:

        """

        repo = get_repo_or_error(repoid)

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

            pass

        elif HasRepoPermissionAnyApi('repository.admin',

                                     'repository.write')(user=apiuser,

                                                         repo_name=repo.repo_name):

            #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'

                )

        else:

            raise JSONRPCError('repository `%s` does not exist' % (repoid))

        if isinstance(userid, Optional):

            userid = apiuser.user_id

        user = get_user_or_error(userid)

        if isinstance(locked, Optional):

            lockobj = Repository.getlock(repo)

            if lockobj[0] is None:

                _d = {

                    'repo': repo.repo_name,

                    'locked': False,

                    'locked_since': None,

                    'locked_by': None,

                    'msg': 'Repo `%s` not locked.' % repo.repo_name

                }

                return _d

            else:

                userid, time_ = lockobj

                lock_user = get_user_or_error(userid)

                _d = {

                    'repo': repo.repo_name,

                    'locked': True,

                    'locked_since': time_,

                    'locked_by': lock_user.username,

                    'msg': ('Repo `%s` locked by `%s`. '

                            % (repo.repo_name,

                               json.dumps(time_to_datetime(time_))))

                }

                return _d

        # force locked state through a flag

        else:

            locked = str2bool(locked)

            try:

                if locked:

                    lock_time = time.time()

                    Repository.lock(repo, user.user_id, lock_time)

                else:

                    lock_time = None

                    Repository.unlock(repo)

                _d = {

                    'repo': repo.repo_name,

                    'locked': locked,

                    'locked_since': lock_time,

                    'locked_by': user.username,

                    'msg': ('User `%s` set lock state for repo `%s` to `%s`'

                            % (user.username, repo.repo_name, locked))

                }

                return _d

            except Exception:

                log.error(traceback.format_exc())

                raise JSONRPCError(

                    'Error occurred locking repository `%s`' % repo.repo_name

                )

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

        """

        Get all locks for given userid, if

        this command is runned by non-admin account userid is set to user

        who is calling this method, thus returning locks for himself

        :param apiuser:

        :param userid:

        """

            #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'

                )

        ret = []

        if isinstance(userid, Optional):

            user = None

        else:

            user = get_user_or_error(userid)

        #show all locks

        for r in Repository.getAll():

            userid, time_ = r.locked

            if time_:

                _api_data = r.get_api_data()

                # if we use userfilter just show the locks for this user

                if user:

                    if safe_int(userid) == user.user_id:

                        ret.append(_api_data)

                else:

                    ret.append(_api_data)

        return ret

    @HasPermissionAllDecorator('hg.admin')

    def show_ip(self, apiuser, userid):

        """

        Shows IP address as seen from RhodeCode server, together with all

        defined IP addresses for given user

        :param apiuser:

        :param userid:

        """

        user = get_user_or_error(userid)

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

        return dict(

            ip_addr_server=self.ip_addr,

            user_ips=ips

        )

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

        """"

        Get a user by username, or userid, if userid is given

        :param apiuser:

        :param userid:

        """

            #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

    @HasPermissionAllDecorator('hg.admin')

    def get_users(self, apiuser):

        """"

        Get all users

        :param apiuser:

        """

        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

    @HasPermissionAllDecorator('hg.admin')

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

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

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

                    ldap_dn=Optional(None)):

        """

        Create new user

        :param apiuser:

        :param username:

        :param email:

        :param password:

        :param firstname:

        :param lastname:

        :param active:

        :param admin:

        :param ldap_dn:

                msg=msg

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to add member to user group `%s`' % (

                    users_group.users_group_name

                )

            )

    @HasPermissionAllDecorator('hg.admin')

    def remove_user_from_users_group(self, apiuser, usersgroupid, userid):

        """

        Remove user from a group

        :param apiuser:

        :param usersgroupid:

        :param userid:

        """

        user = get_user_or_error(userid)

        users_group = get_users_group_or_error(usersgroupid)

        try:

            success = UserGroupModel().remove_user_from_group(users_group,

                                                               user)

            msg = 'removed member `%s` from user group `%s`' % (

                        user.username, users_group.users_group_name

                    )

            msg = msg if success else "User wasn't in group"

            Session().commit()

            return dict(success=success, msg=msg)

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to remove member from user group `%s`' % (

                        users_group.users_group_name

                    )

            )

    def get_repo(self, apiuser, repoid):

        """"

        Get repository by name

        :param apiuser:

        :param repoid:

        """

        repo = get_repo_or_error(repoid)

            # check if we have admin permission for this repo !

                raise JSONRPCError('repository `%s` does not exist' % (repoid))

        members = []

        followers = []

        for user in repo.repo_to_perm:

            perm = user.permission.permission_name

            user = user.user

            user_data = user.get_api_data()

            user_data['type'] = "user"

            user_data['permission'] = perm

            members.append(user_data)

        for users_group in repo.users_group_to_perm:

            perm = users_group.permission.permission_name

            users_group = users_group.users_group

            users_group_data = users_group.get_api_data()

            users_group_data['type'] = "users_group"

            users_group_data['permission'] = perm

            members.append(users_group_data)

        for user in repo.followers:

            followers.append(user.user.get_api_data())

        data = repo.get_api_data()

        data['members'] = members

        data['followers'] = followers

        return data

    def get_repos(self, apiuser):

        """"

        Get all repositories

        :param apiuser:

        """

        result = []

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

            repos = RepoModel().get_all_user_repos(user=apiuser)

        else:

            repos = RepoModel().get_all()

        for repo in repos:

            result.append(repo.get_api_data())

        return result

    @HasPermissionAllDecorator('hg.admin')

    def get_repo_nodes(self, apiuser, repoid, revision, root_path,

                       ret_type='all'):

        """

        returns a list of nodes and it's children

        for a given path at given revision. It's possible to specify ret_type

        to show only files or dirs

        :param apiuser:

        :param repoid: name or id of repository

        :param revision: revision for which listing should be done

        :param root_path: path from which start displaying

        :param ret_type: return type 'all|files|dirs' nodes

        """

        repo = get_repo_or_error(repoid)

        try:

            _d, _f = ScmModel().get_nodes(repo, revision, root_path,

                                          flat=False)

            _map = {

                'all': _d + _f,

                'files': _f,

                'dirs': _d,

            }

            return _map[ret_type]

        except KeyError:

            raise JSONRPCError('ret_type must be one of %s' % _map.keys())

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to get repo: `%s` nodes' % repo.repo_name

            )