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)