)

    # permission check inside

    def revoke_user_group_permission_from_repo_group(

            self, repogroupid, usergroupid,

            apply_to_children='none'):

        """

        Revoke permission for user group on given repository. This command can be

        executed only using api_key belonging to user with admin rights, or

        user who has admin right to given repository group.

        OUTPUT::

            id : <id_given_in_input>

            result : {

                      "msg" : "Revoked perm (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",

                      "success" : true

                     }

            error : null

        """

        repo_group = get_repo_group_or_error(repogroupid)

        user_group = get_user_group_or_error(usergroupid)

        if not HasPermissionAny('hg.admin')():

            if not HasRepoGroupPermissionLevel('admin')(repo_group.group_name):

                raise JSONRPCError(

                    'repository group `%s` does not exist' % (repogroupid,))

            if not HasUserGroupPermissionLevel('read')(user_group.users_group_name):

                raise JSONRPCError(

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

        try:

            RepoGroupModel().delete_permission(repo_group=repo_group,

                                               obj=user_group,

                                               obj_type="user_group",

                                               recursive=apply_to_children)

            meta.Session().commit()

            return dict(

                msg='Revoked perm (recursive:%s) for user group: `%s` in repo group: `%s`' % (

                    apply_to_children, user_group.users_group_name, repo_group.name

                ),

                success=True

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'failed to edit permission for user group: `%s` in repo group: `%s`' % (

                    user_group.users_group_name, repo_group.name

                )

            )

    def get_gist(self, gistid):

        """

        Get given gist by id

        """

        gist = get_gist_or_error(gistid)

        if not HasPermissionAny('hg.admin')():

            if gist.owner_id != request.authuser.user_id:

                raise JSONRPCError('gist `%s` does not exist' % (gistid,))

        return gist.get_api_data()

    def get_gists(self, userid=None):

        """

        Get all gists for given user. If userid is empty returned gists

        are for user who called the api

        """

        if not HasPermissionAny('hg.admin')():

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

            # he is not allowed to do that

            if userid is not None and userid != request.authuser.user_id:

                raise JSONRPCError(

                    'userid is not the same as your user'

                )

        if userid is None:

            user_id = request.authuser.user_id

        else:

            user_id = get_user_or_error(userid).user_id

        return [

            gist.get_api_data()

            for gist in db.Gist().query()

                .filter_by(is_expired=False)

                .filter(db.Gist.owner_id == user_id)

                .order_by(db.Gist.created_on.desc())

        ]

    def create_gist(self, files, owner=None,

                    gist_type=db.Gist.GIST_PUBLIC, lifetime=-1,

                    description=''):

        """

        Creates new Gist

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg" : "created new gist",

            "gist" : <gist_object>

          }

          error : null

        """

        try:

            if owner is None:

                owner = request.authuser.user_id

            owner = get_user_or_error(owner)

            gist = GistModel().create(description=description,

                                      owner=owner,

                                      ip_addr=request.ip_addr,

                                      gist_mapping=files,

                                      gist_type=gist_type,

                                      lifetime=lifetime)

            meta.Session().commit()

            return dict(

                msg='created new gist',

                gist=gist.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create gist')

    # permission check inside

    def delete_gist(self, gistid):

        """

        Deletes existing gist

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg" : "deleted gist ID: <gist_id>",

            "gist" : null

          }

          error : null

        """

        gist = get_gist_or_error(gistid)

        if not HasPermissionAny('hg.admin')():

            if gist.owner_id != request.authuser.user_id:

                raise JSONRPCError('gist `%s` does not exist' % (gistid,))

        try:

            GistModel().delete(gist)

            meta.Session().commit()

            return dict(

                msg='deleted gist ID:%s' % (gist.gist_access_id,),

                gist=None

            )

        except Exception:

            log.error(traceback.format_exc())

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

                               % (gist.gist_access_id,))

    # permission check inside

    def get_changesets(self, repoid, start=None, end=None, start_date=None,

                       end_date=None, branch_name=None, reverse=False, with_file_list=False, max_revisions=None):

        """

        TODO

        """

        repo = get_repo_or_error(repoid)

        if not HasRepoPermissionLevel('read')(repo.repo_name):

            raise JSONRPCError('Access denied to repo %s' % repo.repo_name)

        format = "%Y-%m-%dT%H:%M:%S"

        try:

            return [e.__json__(with_file_list) for e in

                repo.scm_instance.get_changesets(start,

                                                 end,

                                                 datetime.strptime(start_date, format) if start_date else None,

                                                 datetime.strptime(end_date, format) if end_date else None,

                                                 branch_name,

                                                 reverse, max_revisions)]

        except EmptyRepositoryError as e:

            raise JSONRPCError('Repository is empty')

    # permission check inside

    def get_changeset(self, repoid, raw_id, with_reviews=False):

        """

        TODO

        """

        repo = get_repo_or_error(repoid)

        if not HasRepoPermissionLevel('read')(repo.repo_name):

            raise JSONRPCError('Access denied to repo %s' % repo.repo_name)

        changeset = repo.get_changeset(raw_id)

        if isinstance(changeset, EmptyChangeset):

            raise JSONRPCError('Changeset %s does not exist' % raw_id)

        info = dict(changeset.as_dict())

        if with_reviews:

            reviews = ChangesetStatusModel().get_statuses(

            info["reviews"] = reviews

        return info

    # permission check inside

    def get_pullrequest(self, pullrequest_id):

        """

        Get given pull request by id

        """

        pull_request = db.PullRequest.get(pullrequest_id)

        if pull_request is None:

            raise JSONRPCError('pull request `%s` does not exist' % (pullrequest_id,))

        if not HasRepoPermissionLevel('read')(pull_request.org_repo.repo_name):

            raise JSONRPCError('not allowed')

        return pull_request.get_api_data()

    # permission check inside

    def comment_pullrequest(self, pull_request_id, comment_msg='', status=None, close_pr=False):

        """

        Add comment, close and change status of pull request.

        """

        apiuser = get_user_or_error(request.authuser.user_id)

        pull_request = db.PullRequest.get(pull_request_id)

        if pull_request is None:

            raise JSONRPCError('pull request `%s` does not exist' % (pull_request_id,))

        if (not HasRepoPermissionLevel('read')(pull_request.org_repo.repo_name)):

            raise JSONRPCError('No permission to add comment. User needs at least reading permissions'

                               ' to the source repository.')

        owner = apiuser.user_id == pull_request.owner_id

        reviewer = apiuser.user_id in [reviewer.user_id for reviewer in pull_request.reviewers]

        if close_pr and not (apiuser.admin or owner):

            raise JSONRPCError('No permission to close pull request. User needs to be admin or owner.')

        if status and not (apiuser.admin or owner or reviewer):

            raise JSONRPCError('No permission to change pull request status. User needs to be admin, owner or reviewer.')

        if pull_request.is_closed():

            raise JSONRPCError('pull request is already closed')

        comment = ChangesetCommentsModel().create(

            text=comment_msg,

            repo=pull_request.org_repo.repo_id,

            author=apiuser.user_id,

            pull_request=pull_request.pull_request_id,

            f_path=None,

            line_no=None,

            status_change=db.ChangesetStatus.get_status_lbl(status),

            closing_pr=close_pr

        )

        userlog.action_logger(apiuser,

                      'user_commented_pull_request:%s' % pull_request_id,

                      pull_request.org_repo, request.ip_addr)

        if status:

            ChangesetStatusModel().set_status(

                pull_request.org_repo_id,

                status,

                apiuser.user_id,

                comment,

                pull_request=pull_request_id

            )

        if close_pr:

            PullRequestModel().close_pull_request(pull_request_id)

            userlog.action_logger(apiuser,

                          'user_closed_pull_request:%s' % pull_request_id,

                          pull_request.org_repo, request.ip_addr)

        meta.Session().commit()

        return True

    # permission check inside

    def edit_reviewers(self, pull_request_id, add=None, remove=None):

        """

        Add and/or remove one or more reviewers to a pull request, by username

        or user ID. Reviewers are specified either as a single-user string or

        as a JSON list of one or more strings.

        """

        if add is None and remove is None:

            raise JSONRPCError('''Invalid request. Neither 'add' nor 'remove' is specified.''')

        pull_request = db.PullRequest.get(pull_request_id)

        if pull_request is None:

            raise JSONRPCError('pull request `%s` does not exist' % (pull_request_id,))

        apiuser = get_user_or_error(request.authuser.user_id)

        is_owner = apiuser.user_id == pull_request.owner_id

        is_repo_admin = HasRepoPermissionLevel('admin')(pull_request.other_repo.repo_name)

        if not (apiuser.admin or is_repo_admin or is_owner):

            raise JSONRPCError('No permission to edit reviewers of this pull request. User needs to be admin or pull request owner.')

        if pull_request.is_closed():

            raise JSONRPCError('Cannot edit reviewers of a closed pull request.')

        if not isinstance(add, list):

            add = [add]

        if not isinstance(remove, list):

            remove = [remove]

        # look up actual user objects from given name or id. Bail out if unknown.

        add_objs = set(get_user_or_error(user) for user in add if user is not None)

        remove_objs = set(get_user_or_error(user) for user in remove if user is not None)

        new_reviewers = redundant_reviewers = set()

        if add_objs:

            new_reviewers, redundant_reviewers = PullRequestModel().add_reviewers(apiuser, pull_request, add_objs)

        if remove_objs:

            PullRequestModel().remove_reviewers(apiuser, pull_request, remove_objs)

        meta.Session().commit()

        return {

            'added': [x.username for x in new_reviewers],

            'already_present': [x.username for x in redundant_reviewers],

            # NOTE: no explicit check that removed reviewers were actually present.

            'removed': [x.username for x in remove_objs],

        }