GET parameter `?api_key=<api_key>` to url. By default this is only

enabled on RSS/ATOM feed views.

API ACCESS

++++++++++

All clients are required to send JSON-RPC spec JSON data::

    {   

        "id:"<id>",

        "api_key":"<api_key>",

        "method":"<method_name>",

        "args":{"<arg_key>":"<arg_val>"}

    }

Example call for autopulling remotes repos using curl::

    curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

Simply provide

 - *id* A value of any type, which is used to match the response with the request that it is replying to.

 - *api_key* for access and permission validation.

 - *method* is name of method to call

 - *args* is an key:value list of arguments to pass to method

.. note::

    api_key can be found in your user account page

RhodeCode API will return always a JSON-RPC response::

    {   

        "id":<id>, # matching id sent by request

        "result": "<result>"|null, # JSON formatted result, null if any errors

        "error": "null"|<error_message> # JSON formatted error (if any)

    }

All responses from API will be `HTTP/1.0 200 OK`, if there's an error while

calling api *error* key from response will contain failure description

and result will be null.

API METHODS

+++++++++++

pull

----

Pulls given repo from remote location. Can be used to automatically keep

remote repos up to date. This command can be executed only using api_key

belonging to user with admin rights

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repo_name" : "<reponame>"

              }

OUTPUT::

    result : "Pulled from <reponame>"

    error :  null

get_user

--------

Get's an user by username or user_id, Returns empty result if user is not found.

This command can be executed only using api_key belonging to user with admin 

rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_user"

    args :    { 

                "userid" : "<username or user_id>"

              }

OUTPUT::

    result: None if user does not exist or 

            {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

            }

    error:  null

get_users

---------

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

belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users"

    args :    { }

OUTPUT::

    result: [

              {

                "id" :       "<id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "active" :   "<bool>",

                "admin" :    "<bool>",

              },

    	      …

            ]

    error:  null

create_user

-----------

Creates new user. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "create_user"

    args :    {

                "username" :  "<username>",

                "password" :  "<password>",

                "email" :     "<useremail>",

                "firstname" : "<firstname> = None",

                "lastname" :  "<lastname> = None",

                "active" :    "<bool> = True",

                "admin" :     "<bool> = False",

                "ldap_dn" :   "<ldap_dn> = None"

              }

OUTPUT::

    result: {

              "id" : "<new_user_id>",

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

            }

    error:  null

update_user

-----------

updates current one if such user exists. This command can 

be executed only using api_key belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "update_user"

    args :    {

                "userid" : "<user_id or username>",

                "username" :  "<username>",

                "password" :  "<password>",

                "email" :     "<useremail>",

                "firstname" : "<firstname>",

                "lastname" :  "<lastname>",

                "active" :    "<bool>",

                "admin" :     "<bool>",

                "ldap_dn" :   "<ldap_dn>"

              }

OUTPUT::

    result: {

              "id" : "<edited_user_id>",

              "msg" : "updated user <username>"

            }

    error:  null

get_users_group

---------------

Gets an existing users group. This command can be executed only using api_key

belonging to user with admin rights.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users_group"

    args :    {

                "group_name" : "<name>"

              }

OUTPUT::

    result : None if group not exist

             {

               "id" :         "<id>",

               "group_name" : "<groupname>",

               "active":      "<bool>",

               "members" :  [

                              { "id" :       "<userid>",

.. _changelog:

=========

Changelog

=========

1.3.4 (**2012-XX-XX**)

----------------------

:status: in-progress

:branch: beta

news

++++

- Whoosh logging is now controlled by the .ini files logging setup

- added clone-url into edit form on /settings page

- added help text into repo add/edit forms

- created rcextensions module with additional mappings (ref #322) and

  post push/pull/create repo hooks callbacks

- implemented #377 Users view for his own permissions on account page

- #399 added inheritance of permissions for users group on repos groups

- #401 repository group is automatically pre-selected when adding repos 

  inside a repository group

- added alternative HTTP 403 response when client failed to authenticate. Helps 

  solving issues with Mercurial and LDAP

- #402 removed group prefix from repository name when listing repositories 

  inside a group

- added gravatars into permission view and permissions autocomplete

- #347 when running multiple RhodeCode instances, properly invalidates cache 

  for all registered servers

fixes

+++++

- fixed #390 cache invalidation problems on repos inside group

- fixed #385 clone by ID url was loosing proxy prefix in URL

- fixed some unicode problems with waitress

- fixed issue with escaping < and > in changeset commits

- fixed error occurring during recursive group creation in API 

  create_repo function

- fixed #393 py2.5 fixes for routes url generator

- fixed #397 Private repository groups shows up before login

- fixed #396 fixed problems with revoking users in nested groups

1.3.3 (**2012-03-02**)

----------------------

news

++++

fixes

+++++

- fixed some python2.5 compatibility issues 

- fixed issues with removed repos was accidentally added as groups, after

  full rescan of paths

- fixes #376 Cannot edit user (using container auth)

- fixes #378 Invalid image urls on changeset screen with proxy-prefix 

  configuration

- fixed initial sorting of repos inside repo group

- fixes issue when user tried to resubmit same permission into user/user_groups

- bumped beaker version that fixes #375 leap error bug

- fixed raw_changeset for git. It was generated with hg patch headers

- fixed vcs issue with last_changeset for filenodes

- fixed missing commit after hook delete

- fixed #372 issues with git operation detection that caused a security issue 

  for git repos

1.3.2 (**2012-02-28**)

----------------------

news

++++

fixes

+++++

- fixed git protocol issues with repos-groups

- fixed git remote repos validator that prevented from cloning remote git repos

- fixes #370 ending slashes fixes for repo and groups

- fixes #368 improved git-protocol detection to handle other clients

- fixes #366 When Setting Repository Group To Blank Repo Group Wont Be 

  Moved To Root

- fixes #371 fixed issues with beaker/sqlalchemy and non-ascii cache keys 

- fixed #373 missing cascade drop on user_group_to_perm table

1.3.1 (**2012-02-27**)

----------------------

news

++++

fixes

+++++

- redirection loop occurs when remember-me wasn't checked during login

- fixes issues with git blob history generation 

- don't fetch branch for git in file history dropdown. Causes unneeded slowness

1.3.0 (**2012-02-26**)

----------------------

news

++++

- code review, inspired by github code-comments 

- #215 rst and markdown README files support

- #252 Container-based and proxy pass-through authentication support

- #44 branch browser. Filtering of changelog by branches

- mercurial bookmarks support

- new hover top menu, optimized to add maximum size for important views

- configurable clone url template with possibility to specify  protocol like 

  ssh:// or http:// and also manually alter other parts of clone_url.

- enabled largefiles extension by default

- optimized summary file pages and saved a lot of unused space in them

- #239 option to manually mark repository as fork

- #320 mapping of commit authors to RhodeCode users

- #304 hashes are displayed using monospace font    

- diff configuration, toggle white lines and context lines

- #307 configurable diffs, whitespace toggle, increasing context lines

- sorting on branches, tags and bookmarks using YUI datatable

- improved file filter on files page

- implements #330 api method for listing nodes ar particular revision

- #73 added linking issues in commit messages to chosen issue tracker url

  based on user defined regular expression

- added linking of changesets in commit messages  

- new compact changelog with expandable commit messages

- firstname and lastname are optional in user creation

- #348 added post-create repository hook

- #212 global encoding settings is now configurable from .ini files 

- #227 added repository groups permissions

- markdown gets codehilite extensions

- new API methods, delete_repositories, grante/revoke permissions for groups 

  and repos

        self._error = None

        try:

            self._func = self._find_method()

        except AttributeError, e:

            return jsonrpc_error(message=str(e))

        # now that we have a method, add self._req_params to

        # self.kargs and dispatch control to WGIController

        argspec = inspect.getargspec(self._func)

        arglist = argspec[0][1:]

        defaults = map(type, argspec[3] or [])

        default_empty = types.NotImplementedType

        # kw arguments required by this method

        func_kwargs = dict(izip_longest(reversed(arglist), reversed(defaults),

                                        fillvalue=default_empty))

        # this is little trick to inject logged in user for

        # perms decorators to work they expect the controller class to have

        # rhodecode_user attribute set

        self.rhodecode_user = auth_u

        # This attribute will need to be first param of a method that uses

        # api_key, which is translated to instance of user at that name

        USER_SESSION_ATTR = 'apiuser'

        if USER_SESSION_ATTR not in arglist:

            return jsonrpc_error(message='This method [%s] does not support '

                                 'authentication (missing %s param)' %

                                 (self._func.__name__, USER_SESSION_ATTR))

        # get our arglist and check if we provided them as args

        for arg, default in func_kwargs.iteritems():

            if arg == USER_SESSION_ATTR:

                # USER_SESSION_ATTR is something translated from api key and

                # this is checked before so we don't need validate it

                continue

            # skip the required param check if it's default value is

            # NotImplementedType (default_empty)

            if (default == default_empty and arg not in self._request_params):

                return jsonrpc_error(

                    message=(

                        'Missing non optional `%s` arg in JSON DATA' % arg

                    )

                )

        self._rpc_args = {USER_SESSION_ATTR: u}

        self._rpc_args.update(self._request_params)

        self._rpc_args['action'] = self._req_method

        self._rpc_args['environ'] = environ

        self._rpc_args['start_response'] = start_response

        status = []

        headers = []

        exc_info = []

        def change_content(new_status, new_headers, new_exc_info=None):

            status.append(new_status)

            headers.extend(new_headers)

            exc_info.append(new_exc_info)

        output = WSGIController.__call__(self, environ, change_content)

        output = list(output)

        headers.append(('Content-Length', str(len(output[0]))))

        replace_header(headers, 'Content-Type', 'application/json')

        start_response(status[0], headers, exc_info[0])

        return output

    def _dispatch_call(self):

        """

        Implement dispatch interface specified by WSGIController

        """

        try:

            raw_response = self._inspect_call(self._func)

            if isinstance(raw_response, HTTPError):

                self._error = str(raw_response)

        except JSONRPCError, e:

            self._error = str(e)

        except Exception, e:

            log.error('Encountered unhandled exception: %s' \

                      % traceback.format_exc())

            json_exc = JSONRPCError('Internal server error')

            self._error = str(json_exc)

        if self._error is not None:

            raw_response = None

        response = dict(id=self._req_id, result=raw_response,

                        error=self._error)

        try:

            return json.dumps(response)

        except TypeError, e:

            return json.dumps(

                dict(

                    result=None,

                    error="Error encoding response"

                )

            )

    def _find_method(self):

        """

        Return method named by `self._req_method` in controller if able

        """

        log.debug('Trying to find JSON-RPC method: %s' % self._req_method)

        if self._req_method.startswith('_'):

            raise AttributeError("Method not allowed")

        try:

            func = getattr(self, self._req_method, None)

        except UnicodeEncodeError:

            raise AttributeError("Problem decoding unicode in requested "

                                 "method name.")

        if isinstance(func, types.MethodType):

            return func

        else:

            raise AttributeError("No such method: %s" % self._req_method)

# -*- coding: utf-8 -*-

"""

    rhodecode.controllers.api

    ~~~~~~~~~~~~~~~~~~~~~~~~~

    API controller for RhodeCode

    :created_on: Aug 20, 2011

    :author: marcink

    :copyright: (C) 2011-2012 Marcin Kuzminski <marcin@python-works.com>

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software; you can redistribute it and/or

# modify it under the terms of the GNU General Public License

# as published by the Free Software Foundation; version 2

# of the License or (at your opinion) any later version of the license.

#

# 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 General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

# MA  02110-1301, USA.

import traceback

import logging

from rhodecode.controllers.api import JSONRPCController, JSONRPCError

from rhodecode.lib.auth import HasPermissionAllDecorator, \

from rhodecode.model.meta import Session

from rhodecode.model.scm import ScmModel

from rhodecode.model.repo import RepoModel

from rhodecode.model.user import UserModel

from rhodecode.model.users_group import UsersGroupModel

from rhodecode.lib.utils import map_groups

log = logging.getLogger(__name__)

class ApiController(JSONRPCController):

    """

    API Controller

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

    API_KEY propagated as instance of user object

    Preferably this should be first argument also

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

    errors that happens

    """

    @HasPermissionAllDecorator('hg.admin')

    def pull(self, apiuser, repo_name):

        """

        Dispatch pull action on given repo

        :param user:

        :param repo_name:

        """

        if Repository.is_valid(repo_name) is False:

            raise JSONRPCError('Unknown repo "%s"' % repo_name)

        try:

            ScmModel().pull_changes(repo_name, self.rhodecode_user.username)

            return 'Pulled from %s' % repo_name

        except Exception:

            raise JSONRPCError('Unable to pull changes from "%s"' % repo_name)

    @HasPermissionAllDecorator('hg.admin')

    def get_user(self, apiuser, userid):

        """"

        Get a user by username

        :param apiuser:

        :param username:

        """

        user = UserModel().get_user(userid)

        if user is None:

            return user

        return dict(

            id=user.user_id,

            username=user.username,

            firstname=user.name,

            lastname=user.lastname,

            email=user.email,

            active=user.active,

            admin=user.admin,

        )

    @HasPermissionAllDecorator('hg.admin')

    def get_users(self, apiuser):

        """"

        Get all users

        :param apiuser:

        """

        result = []

        for user in User.getAll():

            result.append(

                dict(

                    id=user.user_id,

                    username=user.username,

                    firstname=user.name,

                    lastname=user.lastname,

                    email=user.email,

                    active=user.active,

                    admin=user.admin,

                )

            )

        return result

    @HasPermissionAllDecorator('hg.admin')

    def create_user(self, apiuser, username, email, password, firstname=None,

                    lastname=None, active=True, admin=False, ldap_dn=None):

        """

        Create new user

        :param apiuser:

        :param username:

        :param password:

        :param email:

        :param name:

        :param lastname:

        :param active:

        :param admin:

        :param ldap_dn:

        """

        if User.get_by_username(username):

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

        if User.get_by_email(email, case_insensitive=True):

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

        if ldap_dn:

            # generate temporary password if ldap_dn

            password = PasswordGenerator().gen_password(length=8)

        try:

            usr = UserModel().create_or_update(

                username, password, email, firstname,

                lastname, active, admin, ldap_dn

            )

            Session.commit()

            return dict(

                id=usr.user_id,

                msg='created new user %s' % username

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to create user %s' % username)

    @HasPermissionAllDecorator('hg.admin')

    def update_user(self, apiuser, userid, username, password, email,

                    firstname, lastname, active, admin, ldap_dn):

        """

        Updates given user

        :param apiuser:

        :param username:

        :param password:

        :param email:

        :param name:

        :param lastname:

        :param active:

        :param admin:

        :param ldap_dn:

        """

        if not UserModel().get_user(userid):

            raise JSONRPCError("user %s does not exist" % username)

        try:

            usr = UserModel().create_or_update(

                username, password, email, firstname,

                lastname, active, admin, ldap_dn

            )

            Session.commit()

            return dict(

                id=usr.user_id,

                msg='updated user %s' % username

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update user %s' % username)

    @HasPermissionAllDecorator('hg.admin')

    def get_users_group(self, apiuser, group_name):

        """"

        Get users group by name

        :param apiuser:

        :param group_name:

        """

        users_group = UsersGroup.get_by_group_name(group_name)

        if not users_group:

            return None

        members = []

        for user in users_group.members:

            user = user.user

            members.append(dict(id=user.user_id,

                            username=user.username,

                            firstname=user.name,

# -*- coding: utf-8 -*-

"""

    rhodecode.lib.compat

    ~~~~~~~~~~~~~~~~~~~~

    Python backward compatibility functions and common libs

    :created_on: Oct 7, 2011

    :author: marcink

    :copyright: (C) 2010-2010 Marcin Kuzminski <marcin@python-works.com>

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# 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 General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

import os

from rhodecode import __platform__, PLATFORM_WIN

#==============================================================================

# json

#==============================================================================

try:

    import json

except ImportError:

    import simplejson as json

#==============================================================================

# izip_longest

#==============================================================================

try:

    from itertools import izip_longest

except ImportError:

    import itertools

        fillvalue = kwds.get("fillvalue")

        def sentinel(counter=([fillvalue] * (len(args) - 1)).pop):

        fillers = itertools.repeat(fillvalue)

        iters = [itertools.chain(it, sentinel(), fillers)

                    for it in args]

        try:

            for tup in itertools.izip(*iters):

                yield tup

        except IndexError:

            pass

#==============================================================================

# OrderedDict

#==============================================================================

# Python Software Foundation License

# XXX: it feels like using the class with "is" and "is not" instead of "==" and

# "!=" should be faster.

class _Nil(object):

    def __repr__(self):

        return "nil"

    def __eq__(self, other):

        if (isinstance(other, _Nil)):

            return True

        else:

            return NotImplemented

    def __ne__(self, other):

        if (isinstance(other, _Nil)):