docs: update API documentation.

docs/api/methods/pull-request-methods.rst

@@ -1,376 +1,371 b''
 .. _pull-request-methods-ref:
 
 pull_request methods
 ====================
 
 close_pull_request 
 ------------------
 
 .. py:function:: close_pull_request(apiuser, repoid, pullrequestid, userid=<Optional:<OptionalAttr:apiuser>>)
 
    Close the pull request specified by `pullrequestid`.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param repoid: Repository name or repository ID to which the pull
        request belongs.
    :type repoid: str or int
    :param pullrequestid: ID of the pull request to be closed.
    :type pullrequestid: int
    :param userid: Close the pull request as this user.
    :type userid: Optional(str or int)
 
    Example output:
 
    .. code-block:: bash
 
      "id": <id_given_in_input>,
-     "result":
-       {
+       "result": {
            "pull_request_id":  "<int>",
            "closed":           "<bool>"
        },
      "error": null
 
 
 comment_pull_request 
 --------------------
 
 .. py:function:: comment_pull_request(apiuser, repoid, pullrequestid, message=<Optional:None>, commit_id=<Optional:None>, status=<Optional:None>, comment_type=<Optional:u'note'>, resolves_comment_id=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)
 
    Comment on the pull request specified with the `pullrequestid`,
    in the |repo| specified by the `repoid`, and optionally change the
    review status.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param repoid: The repository name or repository ID.
    :type repoid: str or int
    :param pullrequestid: The pull request ID.
    :type pullrequestid: int
    :param commit_id: Specify the commit_id for which to set a comment. If
        given commit_id is different than latest in the PR status
        change won't be performed.
    :type commit_id: str
    :param message: The text content of the comment.
    :type message: str
    :param status: (**Optional**) Set the approval status of the pull
        request. One of: 'not_reviewed', 'approved', 'rejected',
        'under_review'
    :type status: str
    :param comment_type: Comment type, one of: 'note', 'todo'
    :type comment_type: Optional(str), default: 'note'
    :param userid: Comment on the pull request as this user
    :type userid: Optional(str or int)
 
    Example output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
-     result :
-       {
+       result : {
            "pull_request_id":  "<Integer>",
            "comment_id":       "<Integer>",
            "status": {"given": <given_status>,
                       "was_changed": <bool status_was_actually_changed> },
-       }
+       },
      error :  null
 
 
 create_pull_request 
 -------------------
 
 .. py:function:: create_pull_request(apiuser, source_repo, target_repo, source_ref, target_ref, title, description=<Optional:''>, reviewers=<Optional:None>)
 
    Creates a new pull request.
 
    Accepts refs in the following formats:
 
        * branch:<branch_name>:<sha>
        * branch:<branch_name>
        * bookmark:<bookmark_name>:<sha> (Mercurial only)
        * bookmark:<bookmark_name> (Mercurial only)
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param source_repo: Set the source repository name.
    :type source_repo: str
    :param target_repo: Set the target repository name.
    :type target_repo: str
    :param source_ref: Set the source ref name.
    :type source_ref: str
    :param target_ref: Set the target ref name.
    :type target_ref: str
    :param title: Set the pull request title.
    :type title: str
    :param description: Set the pull request description.
    :type description: Optional(str)
    :param reviewers: Set the new pull request reviewers list.
    :type reviewers: Optional(list)
        Accepts username strings or objects of the format:
-       {
-           'username': 'nick', 'reasons': ['original author']
-       }
+
+           {'username': 'nick', 'reasons': ['original author']}
 
 
 get_pull_request 
 ----------------
 
 .. py:function:: get_pull_request(apiuser, repoid, pullrequestid)
 
    Get a pull request based on the given ID.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param repoid: Repository name or repository ID from where the pull
        request was opened.
    :type repoid: str or int
    :param pullrequestid: ID of the requested pull request.
    :type pullrequestid: int
 
    Example output:
 
    .. code-block:: bash
 
      "id": <id_given_in_input>,
      "result":
        {
            "pull_request_id":   "<pull_request_id>",
            "url":               "<url>",
            "title":             "<title>",
            "description":       "<description>",
            "status" :           "<status>",
            "created_on":        "<date_time_created>",
            "updated_on":        "<date_time_updated>",
            "commit_ids":        [
                                     ...
                                     "<commit_id>",
                                     "<commit_id>",
                                     ...
                                 ],
            "review_status":    "<review_status>",
            "mergeable":         {
                                     "status":  "<bool>",
                                     "message": "<message>",
                                 },
            "source":            {
                                     "clone_url":     "<clone_url>",
                                     "repository":    "<repository_name>",
                                     "reference":
                                     {
                                         "name":      "<name>",
                                         "type":      "<type>",
                                         "commit_id": "<commit_id>",
                                     }
                                 },
            "target":            {
                                     "clone_url":   "<clone_url>",
                                     "repository":    "<repository_name>",
                                     "reference":
                                     {
                                         "name":      "<name>",
                                         "type":      "<type>",
                                         "commit_id": "<commit_id>",
                                     }
                                 },
            "merge":             {
                                     "clone_url":   "<clone_url>",
                                     "reference":
                                     {
                                         "name":      "<name>",
                                         "type":      "<type>",
                                         "commit_id": "<commit_id>",
                                     }
                                 },
           "author":             <user_obj>,
           "reviewers":          [
                                     ...
                                     {
                                        "user":          "<user_obj>",
                                        "review_status": "<review_status>",
                                     }
                                     ...
                                 ]
        },
       "error": null
 
 
 get_pull_requests 
 -----------------
 
 .. py:function:: get_pull_requests(apiuser, repoid, status=<Optional:'new'>)
 
    Get all pull requests from the repository specified in `repoid`.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param repoid: Repository name or repository ID.
    :type repoid: str or int
    :param status: Only return pull requests with the specified status.
        Valid options are.
        * ``new`` (default)
        * ``open``
        * ``closed``
    :type status: str
 
    Example output:
 
    .. code-block:: bash
 
      "id": <id_given_in_input>,
      "result":
        [
            ...
            {
                "pull_request_id":   "<pull_request_id>",
                "url":               "<url>",
                "title" :            "<title>",
                "description":       "<description>",
                "status":            "<status>",
                "created_on":        "<date_time_created>",
                "updated_on":        "<date_time_updated>",
                "commit_ids":        [
                                         ...
                                         "<commit_id>",
                                         "<commit_id>",
                                         ...
                                     ],
                "review_status":    "<review_status>",
                "mergeable":         {
                                        "status":      "<bool>",
                                        "message:      "<message>",
                                     },
                "source":            {
                                         "clone_url":     "<clone_url>",
                                         "reference":
                                         {
                                             "name":      "<name>",
                                             "type":      "<type>",
                                             "commit_id": "<commit_id>",
                                         }
                                     },
                "target":            {
                                         "clone_url":   "<clone_url>",
                                         "reference":
                                         {
                                             "name":      "<name>",
                                             "type":      "<type>",
                                             "commit_id": "<commit_id>",
                                         }
                                     },
                "merge":             {
                                         "clone_url":   "<clone_url>",
                                         "reference":
                                         {
                                             "name":      "<name>",
                                             "type":      "<type>",
                                             "commit_id": "<commit_id>",
                                         }
                                     },
               "author":             <user_obj>,
               "reviewers":          [
                                         ...
                                         {
                                            "user":          "<user_obj>",
                                            "review_status": "<review_status>",
                                         }
                                         ...
                                     ]
            }
            ...
        ],
      "error": null
 
 
 merge_pull_request 
 ------------------
 
 .. py:function:: merge_pull_request(apiuser, repoid, pullrequestid, userid=<Optional:<OptionalAttr:apiuser>>)
 
    Merge the pull request specified by `pullrequestid` into its target
    repository.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param repoid: The Repository name or repository ID of the
        target repository to which the |pr| is to be merged.
    :type repoid: str or int
    :param pullrequestid: ID of the pull request which shall be merged.
    :type pullrequestid: int
    :param userid: Merge the pull request as this user.
    :type userid: Optional(str or int)
 
    Example output:
 
    .. code-block:: bash
 
      "id": <id_given_in_input>,
-     "result":
-       {
+       "result": {
            "executed":         "<bool>",
            "failure_reason":   "<int>",
            "merge_commit_id":  "<merge_commit_id>",
            "possible":         "<bool>",
            "merge_ref":        {
                                    "commit_id": "<commit_id>",
                                    "type":      "<type>",
                                    "name":      "<name>"
                                }
        },
      "error": null
 
 
 update_pull_request 
 -------------------
 
 .. py:function:: update_pull_request(apiuser, repoid, pullrequestid, title=<Optional:''>, description=<Optional:''>, reviewers=<Optional:None>, update_commits=<Optional:None>, close_pull_request=<Optional:None>)
 
    Updates a pull request.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param repoid: The repository name or repository ID.
    :type repoid: str or int
    :param pullrequestid: The pull request ID.
    :type pullrequestid: int
    :param title: Set the pull request title.
    :type title: str
    :param description: Update pull request description.
    :type description: Optional(str)
    :param reviewers: Update pull request reviewers list with new value.
    :type reviewers: Optional(list)
    :param update_commits: Trigger update of commits for this pull request
    :type: update_commits: Optional(bool)
    :param close_pull_request: Close this pull request with rejected state
    :type: close_pull_request: Optional(bool)
 
    Example output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
-     result :
-       {
+       result : {
            "msg": "Updated pull request `63`",
            "pull_request": <pull_request_object>,
            "updated_reviewers": {
              "added": [
                "username"
              ],
              "removed": []
            },
            "updated_commits": {
              "added": [
                "<sha1_hash>"
              ],
              "common": [
                "<sha1_hash>",
                "<sha1_hash>",
              ],
              "removed": []
            }
        }
      error :  null
 
 

docs/api/methods/server-methods.rst

@@ -1,158 +1,210 b''
 .. _server-methods-ref:
 
 server methods
 ==============
 
 cleanup_sessions 
 ----------------
 
 .. py:function:: cleanup_sessions(apiuser, older_then=<Optional:60>)
 
    Triggers a session cleanup action.
 
    If the ``older_then`` option is set, only sessions that hasn't been
    accessed in the given number of days will be removed.
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param older_then: Deletes session that hasn't been accessed
        in given number of days.
    :type older_then: Optional(int)
 
    Example output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result: {
        "backend": "<type of backend>",
        "sessions_removed": <number_of_removed_sessions>
      }
      error :  null
 
    Example error output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : null
      error :  {
        'Error occurred during session cleanup'
      }
 
 
 get_ip 
 ------
 
 .. py:function:: get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
 
    Displays the IP Address as seen from the |RCE| server.
 
    * This command displays the IP Address, as well as all the defined IP
      addresses for the specified user. If the ``userid`` is not set, the
      data returned is for the user calling the method.
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from |authtoken|.
    :type apiuser: AuthUser
    :param userid: Sets the userid for which associated IP Address data
        is returned.
    :type userid: Optional(str or int)
 
    Example output:
 
    .. code-block:: bash
 
        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>"],
                                    },
                                    ...
                                 ]
        }
 
 
+get_method 
+----------
+
+.. py:function:: get_method(apiuser, pattern=<Optional:'*'>)
+
+   Returns list of all available API methods. By default match pattern
+   os "*" but any other pattern can be specified. eg *comment* will return
+   all methods with comment inside them. If just single method is matched
+   returned data will also include method specification
+
+   This command can only be run using an |authtoken| with admin rights to
+   the specified repository.
+
+   This command takes the following options:
+
+   :param apiuser: This is filled automatically from the |authtoken|.
+   :type apiuser: AuthUser
+   :param pattern: pattern to match method names against
+   :type older_then: Optional("*")
+
+   Example output:
+
+   .. code-block:: bash
+
+     id : <id_given_in_input>
+     "result": [
+       "changeset_comment",
+       "comment_pull_request",
+       "comment_commit"
+     ]
+     error :  null
+
+   .. code-block:: bash
+
+     id : <id_given_in_input>
+     "result": [
+       "comment_commit",
+       {
+         "apiuser": "<RequiredType>",
+         "comment_type": "<Optional:u'note'>",
+         "commit_id": "<RequiredType>",
+         "message": "<RequiredType>",
+         "repoid": "<RequiredType>",
+         "request": "<RequiredType>",
+         "resolves_comment_id": "<Optional:None>",
+         "status": "<Optional:None>",
+         "userid": "<Optional:<OptionalAttr:apiuser>>"
+       }
+     ]
+     error :  null
+
+
 get_server_info 
 ---------------
 
 .. py:function:: get_server_info(apiuser)
 
    Returns the |RCE| server information.
 
    This includes the running version of |RCE| and all installed
    packages. This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
 
    Example output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : {
        'modules': [<module name>,...]
        'py_version': <python version>,
        'platform': <platform type>,
        'rhodecode_version': <rhodecode version>
      }
      error :  null
 
 
 rescan_repos 
 ------------
 
 .. py:function:: rescan_repos(apiuser, remove_obsolete=<Optional:False>)
 
    Triggers a rescan of the specified repositories.
 
    * If the ``remove_obsolete`` option is set, it also deletes repositories
      that are found in the database but not on the file system, so called
      "clean zombies".
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param remove_obsolete: Deletes repositories from the database that
        are not found on the filesystem.
    :type remove_obsolete: Optional(``True`` | ``False``)
 
    Example output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : {
        'added': [<added repository name>,...]
        'removed': [<removed repository name>,...]
      }
      error :  null
 
    Example error output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : null
      error :  {
        'Error occurred during rescan repositories action'
      }
 
 

docs/api/methods/user-methods.rst

@@ -1,297 +1,325 b''
 .. _user-methods-ref:
 
 user methods
 ============
 
 create_user 
 -----------
 
 .. py:function:: create_user(apiuser, username, email, password=<Optional:''>, firstname=<Optional:''>, lastname=<Optional:''>, active=<Optional:True>, admin=<Optional:False>, extern_name=<Optional:'rhodecode'>, extern_type=<Optional:'rhodecode'>, force_password_change=<Optional:False>, create_personal_repo_group=<Optional:None>)
 
    Creates a new user and returns the new user object.
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param username: Set the new username.
    :type username: str or int
    :param email: Set the user email address.
    :type email: str
    :param password: Set the new user password.
    :type password: Optional(str)
    :param firstname: Set the new user firstname.
    :type firstname: Optional(str)
    :param lastname: Set the new user surname.
    :type lastname: Optional(str)
    :param active: Set the user as active.
    :type active: Optional(``True`` | ``False``)
    :param admin: Give the new user admin rights.
    :type admin: Optional(``True`` | ``False``)
    :param extern_name: Set the authentication plugin name.
        Using LDAP this is filled with LDAP UID.
    :type extern_name: Optional(str)
    :param extern_type: Set the new user authentication plugin.
    :type extern_type: Optional(str)
    :param force_password_change: Force the new user to change password
        on next login.
    :type force_password_change: Optional(``True`` | ``False``)
    :param create_personal_repo_group: Create personal repo group for this user
    :type create_personal_repo_group: Optional(``True`` | ``False``)
+
    Example output:
 
    .. code-block:: bash
 
        id : <id_given_in_input>
        result: {
                  "msg" : "created new user `<username>`",
                  "user": <user_obj>
                }
        error:  null
 
    Example error output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : null
      error :  {
        "user `<username>` already exist"
        or
        "email `<email>` already exist"
        or
        "failed to create user `<username>`"
      }
 
 
 delete_user 
 -----------
 
 .. py:function:: delete_user(apiuser, userid)
 
    Deletes the specified user from the |RCE| user database.
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    .. important::
 
       Ensure all open pull requests and open code review
       requests to this user are close.
 
       Also ensure all repositories, or repository groups owned by this
       user are reassigned before deletion.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param userid: Set the user to delete.
    :type userid: str or int
 
    Example output:
 
    .. code-block:: bash
 
        id : <id_given_in_input>
        result: {
                  "msg" : "deleted user ID:<userid> <username>",
                  "user": null
                }
        error:  null
 
    Example error output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : null
      error :  {
        "failed to delete user ID:<userid> <username>"
      }
 
 
 get_user 
 --------
 
 .. py:function:: get_user(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
 
    Returns the information associated with a username or userid.
 
    * If the ``userid`` is not set, this command returns the information
      for the ``userid`` calling the method.
 
    .. note::
 
       Normal users may only run this command against their ``userid``. For
       full privileges you must run this command using an |authtoken| with
       admin rights.
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param userid: Sets the userid for which data will be returned.
    :type userid: Optional(str or int)
 
    Example output:
 
    .. code-block:: bash
 
        {
          "error": null,
          "id": <id>,
          "result": {
            "active": true,
            "admin": false,
-           "api_key": "api-key",
            "api_keys": [ list of keys ],
+           "auth_tokens": [ list of tokens with details ],
            "email": "[e-mail]",
            "emails": [
              "[e-mail]"
            ],
            "extern_name": "rhodecode",
            "extern_type": "rhodecode",
            "firstname": "username",
            "ip_addresses": [],
            "language": null,
            "last_login": "Timestamp",
+           "last_activity": "Timestamp",
            "lastname": "surnae",
            "permissions": {
              "global": [
                "hg.inherit_default_perms.true",
                "usergroup.read",
                "hg.repogroup.create.false",
                "hg.create.none",
                "hg.password_reset.enabled",
                "hg.extern_activate.manual",
                "hg.create.write_on_repogroup.false",
                "hg.usergroup.create.false",
                "group.none",
                "repository.none",
                "hg.register.none",
                "hg.fork.repository"
              ],
              "repositories": { "username/example": "repository.write"},
              "repositories_groups": { "user-group/repo": "group.none" },
              "user_groups": { "user_group_name": "usergroup.read" }
            },
            "user_id": 32,
            "username": "username"
          }
        }
 
 
+get_user_audit_logs 
+-------------------
+
+.. py:function:: get_user_audit_logs(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
+
+   Fetches all action logs made by the specified user.
+
+   This command takes the following options:
+
+   :param apiuser: This is filled automatically from the |authtoken|.
+   :type apiuser: AuthUser
+   :param userid: Sets the userid whose list of locked |repos| will be
+       displayed.
+   :type userid: Optional(str or int)
+
+   Example output:
+
+   .. code-block:: bash
+
+       id : <id_given_in_input>
+       result : {
+           [action, action,...]
+       }
+       error :  null
+
+
 get_user_locks 
 --------------
 
 .. py:function:: get_user_locks(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)
 
    Displays all repositories locked by the specified user.
 
    * If this command is run by a non-admin user, it returns
      a list of |repos| locked by that user.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
    :param userid: Sets the userid whose list of locked |repos| will be
        displayed.
    :type userid: Optional(str or int)
 
    Example output:
 
    .. code-block:: bash
 
        id : <id_given_in_input>
        result : {
            [repo_object, repo_object,...]
        }
        error :  null
 
 
 get_users 
 ---------
 
 .. py:function:: get_users(apiuser)
 
    Lists all users in the |RCE| user database.
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from the |authtoken|.
    :type apiuser: AuthUser
 
    Example output:
 
    .. code-block:: bash
 
        id : <id_given_in_input>
            result: [<user_object>, ...]
        error:  null
 
 
 update_user 
 -----------
 
 .. py:function:: update_user(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 the details for the specified user, if that user exists.
 
    This command can only be run using an |authtoken| with admin rights to
    the specified repository.
 
    This command takes the following options:
 
    :param apiuser: This is filled automatically from |authtoken|.
    :type apiuser: AuthUser
    :param userid: Set the ``userid`` to update.
    :type userid: str or int
    :param username: Set the new username.
    :type username: str or int
    :param email: Set the new email.
    :type email: str
    :param password: Set the new password.
    :type password: Optional(str)
    :param firstname: Set the new first name.
    :type firstname: Optional(str)
    :param lastname: Set the new surname.
    :type lastname: Optional(str)
    :param active: Set the new user as active.
    :type active: Optional(``True`` | ``False``)
    :param admin: Give the user admin rights.
    :type admin: Optional(``True`` | ``False``)
    :param extern_name: Set the authentication plugin user name.
        Using LDAP this is filled with LDAP UID.
    :type extern_name: Optional(str)
    :param extern_type: Set the authentication plugin type.
    :type extern_type: Optional(str)
 
 
    Example output:
 
    .. code-block:: bash
 
        id : <id_given_in_input>
        result: {
                  "msg" : "updated user ID:<userid> <username>",
                  "user": <user_object>,
                }
        error:  null
 
    Example error output:
 
    .. code-block:: bash
 
      id : <id_given_in_input>
      result : null
      error :  {
        "failed to update user `<username>`"
      }
 
 

rhodecode/api/views/pull_request_api.py

@@ -1,731 +1,725 b''
 # -*- coding: utf-8 -*-
 
 # Copyright (C) 2011-2017 RhodeCode GmbH
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License, version 3
 # (only), as published by the Free Software Foundation.
 #
 # 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 Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 # This program is dual-licensed. If you wish to learn more about the
 # RhodeCode Enterprise Edition, including its added features, Support services,
 # and proprietary license terms, please see https://rhodecode.com/licenses/
 
 
 import logging
 
 from rhodecode.api import jsonrpc_method, JSONRPCError
 from rhodecode.api.utils import (
     has_superadmin_permission, Optional, OAttr, get_repo_or_error,
     get_pull_request_or_error, get_commit_or_error, get_user_or_error,
     validate_repo_permissions, resolve_ref_or_error)
 from rhodecode.lib.auth import (HasRepoPermissionAnyApi)
 from rhodecode.lib.base import vcs_operation_context
 from rhodecode.lib.utils2 import str2bool
 from rhodecode.model.changeset_status import ChangesetStatusModel
 from rhodecode.model.comment import CommentsModel
 from rhodecode.model.db import Session, ChangesetStatus, ChangesetComment
 from rhodecode.model.pull_request import PullRequestModel, MergeCheck
 from rhodecode.model.settings import SettingsModel
 
 log = logging.getLogger(__name__)
 
 
 @jsonrpc_method()
 def get_pull_request(request, apiuser, repoid, pullrequestid):
     """
     Get a pull request based on the given ID.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param repoid: Repository name or repository ID from where the pull
         request was opened.
     :type repoid: str or int
     :param pullrequestid: ID of the requested pull request.
     :type pullrequestid: int
 
     Example output:
 
     .. code-block:: bash
 
       "id": <id_given_in_input>,
       "result":
         {
             "pull_request_id":   "<pull_request_id>",
             "url":               "<url>",
             "title":             "<title>",
             "description":       "<description>",
             "status" :           "<status>",
             "created_on":        "<date_time_created>",
             "updated_on":        "<date_time_updated>",
             "commit_ids":        [
                                      ...
                                      "<commit_id>",
                                      "<commit_id>",
                                      ...
                                  ],
             "review_status":    "<review_status>",
             "mergeable":         {
                                      "status":  "<bool>",
                                      "message": "<message>",
                                  },
             "source":            {
                                      "clone_url":     "<clone_url>",
                                      "repository":    "<repository_name>",
                                      "reference":
                                      {
                                          "name":      "<name>",
                                          "type":      "<type>",
                                          "commit_id": "<commit_id>",
                                      }
                                  },
             "target":            {
                                      "clone_url":   "<clone_url>",
                                      "repository":    "<repository_name>",
                                      "reference":
                                      {
                                          "name":      "<name>",
                                          "type":      "<type>",
                                          "commit_id": "<commit_id>",
                                      }
                                  },
             "merge":             {
                                      "clone_url":   "<clone_url>",
                                      "reference":
                                      {
                                          "name":      "<name>",
                                          "type":      "<type>",
                                          "commit_id": "<commit_id>",
                                      }
                                  },
            "author":             <user_obj>,
            "reviewers":          [
                                      ...
                                      {
                                         "user":          "<user_obj>",
                                         "review_status": "<review_status>",
                                      }
                                      ...
                                  ]
         },
        "error": null
     """
     get_repo_or_error(repoid)
     pull_request = get_pull_request_or_error(pullrequestid)
     if not PullRequestModel().check_user_read(
             pull_request, apiuser, api=True):
         raise JSONRPCError('repository `%s` does not exist' % (repoid,))
     data = pull_request.get_api_data()
     return data
 
 
 @jsonrpc_method()
 def get_pull_requests(request, apiuser, repoid, status=Optional('new')):
     """
     Get all pull requests from the repository specified in `repoid`.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param repoid: Repository name or repository ID.
     :type repoid: str or int
     :param status: Only return pull requests with the specified status.
         Valid options are.
         * ``new`` (default)
         * ``open``
         * ``closed``
     :type status: str
 
     Example output:
 
     .. code-block:: bash
 
       "id": <id_given_in_input>,
       "result":
         [
             ...
             {
                 "pull_request_id":   "<pull_request_id>",
                 "url":               "<url>",
                 "title" :            "<title>",
                 "description":       "<description>",
                 "status":            "<status>",
                 "created_on":        "<date_time_created>",
                 "updated_on":        "<date_time_updated>",
                 "commit_ids":        [
                                          ...
                                          "<commit_id>",
                                          "<commit_id>",
                                          ...
                                      ],
                 "review_status":    "<review_status>",
                 "mergeable":         {
                                         "status":      "<bool>",
                                         "message:      "<message>",
                                      },
                 "source":            {
                                          "clone_url":     "<clone_url>",
                                          "reference":
                                          {
                                              "name":      "<name>",
                                              "type":      "<type>",
                                              "commit_id": "<commit_id>",
                                          }
                                      },
                 "target":            {
                                          "clone_url":   "<clone_url>",
                                          "reference":
                                          {
                                              "name":      "<name>",
                                              "type":      "<type>",
                                              "commit_id": "<commit_id>",
                                          }
                                      },
                 "merge":             {
                                          "clone_url":   "<clone_url>",
                                          "reference":
                                          {
                                              "name":      "<name>",
                                              "type":      "<type>",
                                              "commit_id": "<commit_id>",
                                          }
                                      },
                "author":             <user_obj>,
                "reviewers":          [
                                          ...
                                          {
                                             "user":          "<user_obj>",
                                             "review_status": "<review_status>",
                                          }
                                          ...
                                      ]
             }
             ...
         ],
       "error": null
 
     """
     repo = get_repo_or_error(repoid)
     if not has_superadmin_permission(apiuser):
         _perms = (
             'repository.admin', 'repository.write', 'repository.read',)
         validate_repo_permissions(apiuser, repoid, repo, _perms)
 
     status = Optional.extract(status)
     pull_requests = PullRequestModel().get_all(repo, statuses=[status])
     data = [pr.get_api_data() for pr in pull_requests]
     return data
 
 
 @jsonrpc_method()
 def merge_pull_request(request, apiuser, repoid, pullrequestid,
                        userid=Optional(OAttr('apiuser'))):
     """
     Merge the pull request specified by `pullrequestid` into its target
     repository.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param repoid: The Repository name or repository ID of the
         target repository to which the |pr| is to be merged.
     :type repoid: str or int
     :param pullrequestid: ID of the pull request which shall be merged.
     :type pullrequestid: int
     :param userid: Merge the pull request as this user.
     :type userid: Optional(str or int)
 
     Example output:
 
     .. code-block:: bash
 
       "id": <id_given_in_input>,
-      "result":
-        {
+        "result": {
             "executed":         "<bool>",
             "failure_reason":   "<int>",
             "merge_commit_id":  "<merge_commit_id>",
             "possible":         "<bool>",
             "merge_ref":        {
                                     "commit_id": "<commit_id>",
                                     "type":      "<type>",
                                     "name":      "<name>"
                                 }
         },
       "error": null
-
     """
     repo = get_repo_or_error(repoid)
     if not isinstance(userid, Optional):
         if (has_superadmin_permission(apiuser) or
                 HasRepoPermissionAnyApi('repository.admin')(
                     user=apiuser, repo_name=repo.repo_name)):
             apiuser = get_user_or_error(userid)
         else:
             raise JSONRPCError('userid is not the same as your user')
 
     pull_request = get_pull_request_or_error(pullrequestid)
 
     check = MergeCheck.validate(pull_request, user=apiuser)
     merge_possible = not check.failed
 
     if not merge_possible:
         reasons = ','.join([msg for _e, msg in check.errors])
         raise JSONRPCError(
             'merge not possible for following reasons: {}'.format(reasons))
 
     target_repo = pull_request.target_repo
     extras = vcs_operation_context(
         request.environ, repo_name=target_repo.repo_name,
         username=apiuser.username, action='push',
         scm=target_repo.repo_type)
     merge_response = PullRequestModel().merge(
         pull_request, apiuser, extras=extras)
     if merge_response.executed:
         PullRequestModel().close_pull_request(
             pull_request.pull_request_id, apiuser)
 
         Session().commit()
 
     # In previous versions the merge response directly contained the merge
     # commit id. It is now contained in the merge reference object. To be
     # backwards compatible we have to extract it again.
     merge_response = merge_response._asdict()
     merge_response['merge_commit_id'] = merge_response['merge_ref'].commit_id
 
     return merge_response
 
 
 @jsonrpc_method()
 def close_pull_request(request, apiuser, repoid, pullrequestid,
                        userid=Optional(OAttr('apiuser'))):
     """
     Close the pull request specified by `pullrequestid`.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param repoid: Repository name or repository ID to which the pull
         request belongs.
     :type repoid: str or int
     :param pullrequestid: ID of the pull request to be closed.
     :type pullrequestid: int
     :param userid: Close the pull request as this user.
     :type userid: Optional(str or int)
 
     Example output:
 
     .. code-block:: bash
 
       "id": <id_given_in_input>,
-      "result":
-        {
+        "result": {
             "pull_request_id":  "<int>",
             "closed":           "<bool>"
         },
       "error": null
 
     """
     repo = get_repo_or_error(repoid)
     if not isinstance(userid, Optional):
         if (has_superadmin_permission(apiuser) or
                 HasRepoPermissionAnyApi('repository.admin')(
                     user=apiuser, repo_name=repo.repo_name)):
             apiuser = get_user_or_error(userid)
         else:
             raise JSONRPCError('userid is not the same as your user')
 
     pull_request = get_pull_request_or_error(pullrequestid)
     if not PullRequestModel().check_user_update(
             pull_request, apiuser, api=True):
         raise JSONRPCError(
             'pull request `%s` close failed, no permission to close.' % (
                 pullrequestid,))
     if pull_request.is_closed():
         raise JSONRPCError(
             'pull request `%s` is already closed' % (pullrequestid,))
 
     PullRequestModel().close_pull_request(
         pull_request.pull_request_id, apiuser)
     Session().commit()
     data = {
         'pull_request_id': pull_request.pull_request_id,
         'closed': True,
     }
     return data
 
 
 @jsonrpc_method()
 def comment_pull_request(
         request, apiuser, repoid, pullrequestid, message=Optional(None),
         commit_id=Optional(None), status=Optional(None),
         comment_type=Optional(ChangesetComment.COMMENT_TYPE_NOTE),
         resolves_comment_id=Optional(None),
         userid=Optional(OAttr('apiuser'))):
     """
     Comment on the pull request specified with the `pullrequestid`,
     in the |repo| specified by the `repoid`, and optionally change the
     review status.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param repoid: The repository name or repository ID.
     :type repoid: str or int
     :param pullrequestid: The pull request ID.
     :type pullrequestid: int
     :param commit_id: Specify the commit_id for which to set a comment. If
         given commit_id is different than latest in the PR status
         change won't be performed.
     :type commit_id: str
     :param message: The text content of the comment.
     :type message: str
     :param status: (**Optional**) Set the approval status of the pull
         request. One of: 'not_reviewed', 'approved', 'rejected',
         'under_review'
     :type status: str
     :param comment_type: Comment type, one of: 'note', 'todo'
     :type comment_type: Optional(str), default: 'note'
     :param userid: Comment on the pull request as this user
     :type userid: Optional(str or int)
 
     Example output:
 
     .. code-block:: bash
 
       id : <id_given_in_input>
-      result :
-        {
+        result : {
             "pull_request_id":  "<Integer>",
             "comment_id":       "<Integer>",
             "status": {"given": <given_status>,
                        "was_changed": <bool status_was_actually_changed> },
-        }
+        },
       error :  null
     """
     repo = get_repo_or_error(repoid)
     if not isinstance(userid, Optional):
         if (has_superadmin_permission(apiuser) or
                 HasRepoPermissionAnyApi('repository.admin')(
                     user=apiuser, repo_name=repo.repo_name)):
             apiuser = get_user_or_error(userid)
         else:
             raise JSONRPCError('userid is not the same as your user')
 
     pull_request = get_pull_request_or_error(pullrequestid)
     if not PullRequestModel().check_user_read(
             pull_request, apiuser, api=True):
         raise JSONRPCError('repository `%s` does not exist' % (repoid,))
     message = Optional.extract(message)
     status = Optional.extract(status)
     commit_id = Optional.extract(commit_id)
     comment_type = Optional.extract(comment_type)
     resolves_comment_id = Optional.extract(resolves_comment_id)
 
     if not message and not status:
         raise JSONRPCError(
             'Both message and status parameters are missing. '
             'At least one is required.')
 
     if (status not in (st[0] for st in ChangesetStatus.STATUSES) and
             status is not None):
         raise JSONRPCError('Unknown comment status: `%s`' % status)
 
     if commit_id and commit_id not in pull_request.revisions:
         raise JSONRPCError(
             'Invalid commit_id `%s` for this pull request.' % commit_id)
 
     allowed_to_change_status = PullRequestModel().check_user_change_status(
         pull_request, apiuser)
 
     # if commit_id is passed re-validated if user is allowed to change status
     # based on latest commit_id from the PR
     if commit_id:
         commit_idx = pull_request.revisions.index(commit_id)
         if commit_idx != 0:
             allowed_to_change_status = False
 
     if resolves_comment_id:
         comment = ChangesetComment.get(resolves_comment_id)
         if not comment:
             raise JSONRPCError(
                 'Invalid resolves_comment_id `%s` for this pull request.'
                 % resolves_comment_id)
         if comment.comment_type != ChangesetComment.COMMENT_TYPE_TODO:
             raise JSONRPCError(
                 'Comment `%s` is wrong type for setting status to resolved.'
                 % resolves_comment_id)
 
     text = message
     status_label = ChangesetStatus.get_status_lbl(status)
     if status and allowed_to_change_status:
         st_message = ('Status change %(transition_icon)s %(status)s'
                       % {'transition_icon': '>', 'status': status_label})
         text = message or st_message
 
     rc_config = SettingsModel().get_all_settings()
     renderer = rc_config.get('rhodecode_markup_renderer', 'rst')
 
     status_change = status and allowed_to_change_status
     comment = CommentsModel().create(
         text=text,
         repo=pull_request.target_repo.repo_id,
         user=apiuser.user_id,
         pull_request=pull_request.pull_request_id,
         f_path=None,
         line_no=None,
         status_change=(status_label if status_change else None),
         status_change_type=(status if status_change else None),
         closing_pr=False,
         renderer=renderer,
         comment_type=comment_type,
         resolves_comment_id=resolves_comment_id
     )
 
     if allowed_to_change_status and status:
         ChangesetStatusModel().set_status(
             pull_request.target_repo.repo_id,
             status,
             apiuser.user_id,
             comment,
             pull_request=pull_request.pull_request_id
         )
         Session().flush()
 
     Session().commit()
     data = {
         'pull_request_id': pull_request.pull_request_id,
         'comment_id': comment.comment_id if comment else None,
         'status': {'given': status, 'was_changed': status_change},
     }
     return data
 
 
 @jsonrpc_method()
 def create_pull_request(
         request, apiuser, source_repo, target_repo, source_ref, target_ref,
         title, description=Optional(''), reviewers=Optional(None)):
     """
     Creates a new pull request.
 
     Accepts refs in the following formats:
 
         * branch:<branch_name>:<sha>
         * branch:<branch_name>
         * bookmark:<bookmark_name>:<sha> (Mercurial only)
         * bookmark:<bookmark_name> (Mercurial only)
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param source_repo: Set the source repository name.
     :type source_repo: str
     :param target_repo: Set the target repository name.
     :type target_repo: str
     :param source_ref: Set the source ref name.
     :type source_ref: str
     :param target_ref: Set the target ref name.
     :type target_ref: str
     :param title: Set the pull request title.
     :type title: str
     :param description: Set the pull request description.
     :type description: Optional(str)
     :param reviewers: Set the new pull request reviewers list.
     :type reviewers: Optional(list)
         Accepts username strings or objects of the format:
-        {
-            'username': 'nick', 'reasons': ['original author']
-        }
+
+            {'username': 'nick', 'reasons': ['original author']}
     """
 
     source = get_repo_or_error(source_repo)
     target = get_repo_or_error(target_repo)
     if not has_superadmin_permission(apiuser):
         _perms = ('repository.admin', 'repository.write', 'repository.read',)
         validate_repo_permissions(apiuser, source_repo, source, _perms)
 
     full_source_ref = resolve_ref_or_error(source_ref, source)
     full_target_ref = resolve_ref_or_error(target_ref, target)
     source_commit = get_commit_or_error(full_source_ref, source)
     target_commit = get_commit_or_error(full_target_ref, target)
     source_scm = source.scm_instance()
     target_scm = target.scm_instance()
 
     commit_ranges = target_scm.compare(
         target_commit.raw_id, source_commit.raw_id, source_scm,
         merge=True, pre_load=[])
 
     ancestor = target_scm.get_common_ancestor(
         target_commit.raw_id, source_commit.raw_id, source_scm)
 
     if not commit_ranges:
         raise JSONRPCError('no commits found')
 
     if not ancestor:
         raise JSONRPCError('no common ancestor found')
 
     reviewer_objects = Optional.extract(reviewers) or []
     if not isinstance(reviewer_objects, list):
         raise JSONRPCError('reviewers should be specified as a list')
 
     reviewers_reasons = []
     for reviewer_object in reviewer_objects:
         reviewer_reasons = []
         if isinstance(reviewer_object, (basestring, int)):
             reviewer_username = reviewer_object
         else:
             reviewer_username = reviewer_object['username']
             reviewer_reasons = reviewer_object.get('reasons', [])
 
         user = get_user_or_error(reviewer_username)
         reviewers_reasons.append((user.user_id, reviewer_reasons))
 
     pull_request_model = PullRequestModel()
     pull_request = pull_request_model.create(
         created_by=apiuser.user_id,
         source_repo=source_repo,
         source_ref=full_source_ref,
         target_repo=target_repo,
         target_ref=full_target_ref,
         revisions=reversed(
             [commit.raw_id for commit in reversed(commit_ranges)]),
         reviewers=reviewers_reasons,
         title=title,
         description=Optional.extract(description)
     )
 
     Session().commit()
     data = {
         'msg': 'Created new pull request `{}`'.format(title),
         'pull_request_id': pull_request.pull_request_id,
     }
     return data
 
 
 @jsonrpc_method()
 def update_pull_request(
         request, apiuser, repoid, pullrequestid, title=Optional(''),
         description=Optional(''), reviewers=Optional(None),
         update_commits=Optional(None), close_pull_request=Optional(None)):
     """
     Updates a pull request.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param repoid: The repository name or repository ID.
     :type repoid: str or int
     :param pullrequestid: The pull request ID.
     :type pullrequestid: int
     :param title: Set the pull request title.
     :type title: str
     :param description: Update pull request description.
     :type description: Optional(str)
     :param reviewers: Update pull request reviewers list with new value.
     :type reviewers: Optional(list)
     :param update_commits: Trigger update of commits for this pull request
     :type: update_commits: Optional(bool)
     :param close_pull_request: Close this pull request with rejected state
     :type: close_pull_request: Optional(bool)
 
     Example output:
 
     .. code-block:: bash
 
       id : <id_given_in_input>
-      result :
-        {
+        result : {
             "msg": "Updated pull request `63`",
             "pull_request": <pull_request_object>,
             "updated_reviewers": {
               "added": [
                 "username"
               ],
               "removed": []
             },
             "updated_commits": {
               "added": [
                 "<sha1_hash>"
               ],
               "common": [
                 "<sha1_hash>",
                 "<sha1_hash>",
               ],
               "removed": []
             }
         }
       error :  null
     """
 
     repo = get_repo_or_error(repoid)
     pull_request = get_pull_request_or_error(pullrequestid)
     if not PullRequestModel().check_user_update(
             pull_request, apiuser, api=True):
         raise JSONRPCError(
             'pull request `%s` update failed, no permission to update.' % (
                 pullrequestid,))
     if pull_request.is_closed():
         raise JSONRPCError(
             'pull request `%s` update failed, pull request is closed' % (
                 pullrequestid,))
 
     reviewer_objects = Optional.extract(reviewers) or []
     if not isinstance(reviewer_objects, list):
         raise JSONRPCError('reviewers should be specified as a list')
 
     reviewers_reasons = []
     reviewer_ids = set()
     for reviewer_object in reviewer_objects:
         reviewer_reasons = []
         if isinstance(reviewer_object, (int, basestring)):
             reviewer_username = reviewer_object
         else:
             reviewer_username = reviewer_object['username']
             reviewer_reasons = reviewer_object.get('reasons', [])
 
         user = get_user_or_error(reviewer_username)
         reviewer_ids.add(user.user_id)
         reviewers_reasons.append((user.user_id, reviewer_reasons))
 
     title = Optional.extract(title)
     description = Optional.extract(description)
     if title or description:
         PullRequestModel().edit(
             pull_request, title or pull_request.title,
             description or pull_request.description)
         Session().commit()
 
     commit_changes = {"added": [], "common": [], "removed": []}
     if str2bool(Optional.extract(update_commits)):
         if PullRequestModel().has_valid_update_type(pull_request):
             update_response = PullRequestModel().update_commits(
                 pull_request)
             commit_changes = update_response.changes or commit_changes
         Session().commit()
 
     reviewers_changes = {"added": [], "removed": []}
     if reviewer_ids:
         added_reviewers, removed_reviewers = \
             PullRequestModel().update_reviewers(pull_request, reviewers_reasons)
 
         reviewers_changes['added'] = sorted(
             [get_user_or_error(n).username for n in added_reviewers])
         reviewers_changes['removed'] = sorted(
             [get_user_or_error(n).username for n in removed_reviewers])
         Session().commit()
 
     if str2bool(Optional.extract(close_pull_request)):
         PullRequestModel().close_pull_request_with_comment(
             pull_request, apiuser, repo)
         Session().commit()
 
     data = {
         'msg': 'Updated pull request `{}`'.format(
             pull_request.pull_request_id),
         'pull_request': pull_request.get_api_data(),
         'updated_commits': commit_changes,
         'updated_reviewers': reviewers_changes
     }
 
     return data

rhodecode/api/views/user_api.py

@@ -1,514 +1,515 b''
 # -*- coding: utf-8 -*-
 
 # Copyright (C) 2011-2017 RhodeCode GmbH
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU Affero General Public License, version 3
 # (only), as published by the Free Software Foundation.
 #
 # 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 Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 # This program is dual-licensed. If you wish to learn more about the
 # RhodeCode Enterprise Edition, including its added features, Support services,
 # and proprietary license terms, please see https://rhodecode.com/licenses/
 
 import logging
 
 from rhodecode.api import jsonrpc_method, JSONRPCError, JSONRPCForbidden
 from rhodecode.api.utils import (
     Optional, OAttr, has_superadmin_permission, get_user_or_error, store_update)
 from rhodecode.lib.auth import AuthUser, PasswordGenerator
 from rhodecode.lib.exceptions import DefaultUserException
 from rhodecode.lib.utils2 import safe_int, str2bool
 from rhodecode.model.db import Session, User, Repository
 from rhodecode.model.user import UserModel
 
 log = logging.getLogger(__name__)
 
 
 @jsonrpc_method()
 def get_user(request, apiuser, userid=Optional(OAttr('apiuser'))):
     """
     Returns the information associated with a username or userid.
 
     * If the ``userid`` is not set, this command returns the information
       for the ``userid`` calling the method.
 
     .. note::
 
        Normal users may only run this command against their ``userid``. For
        full privileges you must run this command using an |authtoken| with
        admin rights.
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param userid: Sets the userid for which data will be returned.
     :type userid: Optional(str or int)
 
     Example output:
 
     .. code-block:: bash
 
         {
           "error": null,
           "id": <id>,
           "result": {
             "active": true,
             "admin": false,
             "api_keys": [ list of keys ],
             "auth_tokens": [ list of tokens with details ],
             "email": "[e-mail]",
             "emails": [
               "[e-mail]"
             ],
             "extern_name": "rhodecode",
             "extern_type": "rhodecode",
             "firstname": "username",
             "ip_addresses": [],
             "language": null,
             "last_login": "Timestamp",
             "last_activity": "Timestamp",
             "lastname": "surnae",
             "permissions": {
               "global": [
                 "hg.inherit_default_perms.true",
                 "usergroup.read",
                 "hg.repogroup.create.false",
                 "hg.create.none",
                 "hg.password_reset.enabled",
                 "hg.extern_activate.manual",
                 "hg.create.write_on_repogroup.false",
                 "hg.usergroup.create.false",
                 "group.none",
                 "repository.none",
                 "hg.register.none",
                 "hg.fork.repository"
               ],
               "repositories": { "username/example": "repository.write"},
               "repositories_groups": { "user-group/repo": "group.none" },
               "user_groups": { "user_group_name": "usergroup.read" }
             },
             "user_id": 32,
             "username": "username"
           }
         }
     """
 
     if not has_superadmin_permission(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')
 
     userid = Optional.extract(userid, evaluate_locals=locals())
     userid = getattr(userid, 'user_id', userid)
 
     user = get_user_or_error(userid)
     data = user.get_api_data(include_secrets=True)
     data['permissions'] = AuthUser(user_id=user.user_id).permissions
     return data
 
 
 @jsonrpc_method()
 def get_users(request, apiuser):
     """
     Lists all users in the |RCE| user database.
 
     This command can only be run using an |authtoken| with admin rights to
     the specified repository.
 
     This command takes the following options:
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
 
     Example output:
 
     .. code-block:: bash
 
         id : <id_given_in_input>
             result: [<user_object>, ...]
         error:  null
     """
 
     if not has_superadmin_permission(apiuser):
         raise JSONRPCForbidden()
 
     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(include_secrets=True))
     return result
 
 
 @jsonrpc_method()
 def create_user(request, apiuser, username, email, password=Optional(''),
                 firstname=Optional(''), lastname=Optional(''),
                 active=Optional(True), admin=Optional(False),
                 extern_name=Optional('rhodecode'),
                 extern_type=Optional('rhodecode'),
                 force_password_change=Optional(False),
                 create_personal_repo_group=Optional(None)):
     """
     Creates a new user and returns the new user object.
 
     This command can only be run using an |authtoken| with admin rights to
     the specified repository.
 
     This command takes the following options:
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param username: Set the new username.
     :type username: str or int
     :param email: Set the user email address.
     :type email: str
     :param password: Set the new user password.
     :type password: Optional(str)
     :param firstname: Set the new user firstname.
     :type firstname: Optional(str)
     :param lastname: Set the new user surname.
     :type lastname: Optional(str)
     :param active: Set the user as active.
     :type active: Optional(``True`` | ``False``)
     :param admin: Give the new user admin rights.
     :type admin: Optional(``True`` | ``False``)
     :param extern_name: Set the authentication plugin name.
         Using LDAP this is filled with LDAP UID.
     :type extern_name: Optional(str)
     :param extern_type: Set the new user authentication plugin.
     :type extern_type: Optional(str)
     :param force_password_change: Force the new user to change password
         on next login.
     :type force_password_change: Optional(``True`` | ``False``)
     :param create_personal_repo_group: Create personal repo group for this user
     :type create_personal_repo_group: Optional(``True`` | ``False``)
+
     Example output:
 
     .. code-block:: bash
 
         id : <id_given_in_input>
         result: {
                   "msg" : "created new user `<username>`",
                   "user": <user_obj>
                 }
         error:  null
 
     Example error output:
 
     .. code-block:: bash
 
       id : <id_given_in_input>
       result : null
       error :  {
         "user `<username>` already exist"
         or
         "email `<email>` already exist"
         or
         "failed to create user `<username>`"
       }
 
     """
     if not has_superadmin_permission(apiuser):
         raise JSONRPCForbidden()
 
     if UserModel().get_by_username(username):
         raise JSONRPCError("user `%s` already exist" % (username,))
 
     if UserModel().get_by_email(email, case_insensitive=True):
         raise JSONRPCError("email `%s` already exist" % (email,))
 
     # generate random password if we actually given the
     # extern_name and it's not rhodecode
     if (not isinstance(extern_name, Optional) and
                 Optional.extract(extern_name) != 'rhodecode'):
         # generate temporary password if user is external
         password = PasswordGenerator().gen_password(length=16)
     create_repo_group = Optional.extract(create_personal_repo_group)
     if isinstance(create_repo_group, basestring):
         create_repo_group = str2bool(create_repo_group)
 
     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),
             force_password_change=Optional.extract(force_password_change),
             create_repo_group=create_repo_group
         )
         Session().commit()
         return {
             'msg': 'created new user `%s`' % username,
             'user': user.get_api_data(include_secrets=True)
         }
     except Exception:
         log.exception('Error occurred during creation of user')
         raise JSONRPCError('failed to create user `%s`' % (username,))
 
 
 @jsonrpc_method()
 def update_user(request, 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 the details for the specified user, if that user exists.
 
     This command can only be run using an |authtoken| with admin rights to
     the specified repository.
 
     This command takes the following options:
 
     :param apiuser: This is filled automatically from |authtoken|.
     :type apiuser: AuthUser
     :param userid: Set the ``userid`` to update.
     :type userid: str or int
     :param username: Set the new username.
     :type username: str or int
     :param email: Set the new email.
     :type email: str
     :param password: Set the new password.
     :type password: Optional(str)
     :param firstname: Set the new first name.
     :type firstname: Optional(str)
     :param lastname: Set the new surname.
     :type lastname: Optional(str)
     :param active: Set the new user as active.
     :type active: Optional(``True`` | ``False``)
     :param admin: Give the user admin rights.
     :type admin: Optional(``True`` | ``False``)
     :param extern_name: Set the authentication plugin user name.
         Using LDAP this is filled with LDAP UID.
     :type extern_name: Optional(str)
     :param extern_type: Set the authentication plugin type.
     :type extern_type: Optional(str)
 
 
     Example output:
 
     .. code-block:: bash
 
         id : <id_given_in_input>
         result: {
                   "msg" : "updated user ID:<userid> <username>",
                   "user": <user_object>,
                 }
         error:  null
 
     Example error output:
 
     .. code-block:: bash
 
       id : <id_given_in_input>
       result : null
       error :  {
         "failed to update user `<username>`"
       }
 
     """
     if not has_superadmin_permission(apiuser):
         raise JSONRPCForbidden()
 
     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 {
             'msg': 'updated user ID:%s %s' % (user.user_id, user.username),
             'user': user.get_api_data(include_secrets=True)
         }
     except DefaultUserException:
         log.exception("Default user edit exception")
         raise JSONRPCError('editing default user is forbidden')
     except Exception:
         log.exception("Error occurred during update of user")
         raise JSONRPCError('failed to update user `%s`' % (userid,))
 
 
 @jsonrpc_method()
 def delete_user(request, apiuser, userid):
     """
     Deletes the specified user from the |RCE| user database.
 
     This command can only be run using an |authtoken| with admin rights to
     the specified repository.
 
     .. important::
 
        Ensure all open pull requests and open code review
        requests to this user are close.
 
        Also ensure all repositories, or repository groups owned by this
        user are reassigned before deletion.
 
     This command takes the following options:
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param userid: Set the user to delete.
     :type userid: str or int
 
     Example output:
 
     .. code-block:: bash
 
         id : <id_given_in_input>
         result: {
                   "msg" : "deleted user ID:<userid> <username>",
                   "user": null
                 }
         error:  null
 
     Example error output:
 
     .. code-block:: bash
 
       id : <id_given_in_input>
       result : null
       error :  {
         "failed to delete user ID:<userid> <username>"
       }
 
     """
     if not has_superadmin_permission(apiuser):
         raise JSONRPCForbidden()
 
     user = get_user_or_error(userid)
 
     try:
         UserModel().delete(userid)
         Session().commit()
         return {
             'msg': 'deleted user ID:%s %s' % (user.user_id, user.username),
             'user': None
         }
     except Exception:
         log.exception("Error occurred during deleting of user")
         raise JSONRPCError(
             'failed to delete user ID:%s %s' % (user.user_id, user.username))
 
 
 @jsonrpc_method()
 def get_user_locks(request, apiuser, userid=Optional(OAttr('apiuser'))):
     """
     Displays all repositories locked by the specified user.
 
     * If this command is run by a non-admin user, it returns
       a list of |repos| locked by that user.
 
     This command takes the following options:
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param userid: Sets the userid whose list of locked |repos| will be
         displayed.
     :type userid: Optional(str or int)
 
     Example output:
 
     .. code-block:: bash
 
         id : <id_given_in_input>
         result : {
             [repo_object, repo_object,...]
         }
         error :  null
     """
 
     include_secrets = False
     if not has_superadmin_permission(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')
     else:
         include_secrets = True
 
     userid = Optional.extract(userid, evaluate_locals=locals())
     userid = getattr(userid, 'user_id', userid)
     user = get_user_or_error(userid)
 
     ret = []
 
     # show all locks
     for r in Repository.getAll():
         _user_id, _time, _reason = r.locked
         if _user_id and _time:
             _api_data = r.get_api_data(include_secrets=include_secrets)
             # if we use user filter just show the locks for this user
             if safe_int(_user_id) == user.user_id:
                 ret.append(_api_data)
 
     return ret
 
 
 @jsonrpc_method()
 def get_user_audit_logs(request, apiuser, userid=Optional(OAttr('apiuser'))):
     """
     Fetches all action logs made by the specified user.
 
     This command takes the following options:
 
     :param apiuser: This is filled automatically from the |authtoken|.
     :type apiuser: AuthUser
     :param userid: Sets the userid whose list of locked |repos| will be
         displayed.
     :type userid: Optional(str or int)
 
     Example output:
 
     .. code-block:: bash
 
         id : <id_given_in_input>
         result : {
             [action, action,...]
         }
         error :  null
     """
 
     if not has_superadmin_permission(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')
 
     userid = Optional.extract(userid, evaluate_locals=locals())
     userid = getattr(userid, 'user_id', userid)
     user = get_user_or_error(userid)
 
     ret = []
 
     # show all user actions
     for entry in UserModel().get_user_log(user, filter_term=None):
         ret.append(entry)
     return ret