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

#

# Kallithea documentation build configuration file, created by

# sphinx-quickstart on Sun Oct 10 16:46:37 2010.

#

# This file is execfile()d with the current directory set to its containing dir.

#

# Note that not all possible configuration values are present in this

# autogenerated file.

#

# All configuration values have a default; values that are commented out

# serve to show the default.

import os

import sys

from kallithea import __version__

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

sys.path.insert(0, os.path.abspath('..'))

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.

#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions

# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',

              'sphinx.ext.intersphinx', 'sphinx.ext.todo',

              'sphinx.ext.viewcode']

# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']

# The suffix of source filenames.

source_suffix = '.rst'

# The encoding of source files.

#source_encoding = 'utf-8-sig'

# The master toctree document.

master_doc = 'index'

# General information about the project.

# The version info for the project you're documenting, acts as replacement for

# |version| and |release|, also used in various other places throughout the

# built documents.

#

# The short X.Y version.

root = os.path.dirname(os.path.dirname(__file__))

sys.path.append(root)

version = __version__

# The full version, including alpha/beta/rc tags.

release = __version__

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

#language = None

# There are two options for replacing |today|: either, you set today to some

# non-false value, then it is used:

#today = ''

# Else, today_fmt is used as the format for a strftime call.

#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and

# directories to ignore when looking for source files.

exclude_patterns = ['_build']

# The reST default role (used for this markup: `text`) to use for all documents.

#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.

#add_function_parentheses = True

# If true, the current module name will be prepended to all description

# unit titles (such as .. function::).

#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the

# output. They are ignored by default.

#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.

pygments_style = 'sphinx'

highlight_language = 'none'

# A list of ignored prefixes for module index sorting.

#modindex_common_prefix = []

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for

# a list of builtin themes.

html_theme = 'nature'

# Theme options are theme-specific and customize the look and feel of a theme

# further.  For a list of options available for each theme, see the

# documentation.

#html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.

html_theme_path = ['theme']

# The name for this set of Sphinx documents.  If None, it defaults to

# "<project> v<release> documentation".

#html_title = None

# A shorter title for the navigation bar.  Default is the same as html_title.

#html_short_title = None

# The name of an image file (relative to this directory) to place at the top

# of the sidebar.

#html_logo = None

# The name of an image file (within the static path) to use as favicon of the

# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

# pixels large.

#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,

# relative to this directory. They are copied after the builtin static files,

# so a file named "default.css" will overwrite the builtin "default.css".

#html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

# using the given strftime format.

#html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to

# typographically correct entities.

#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.

#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to

# template names.

#html_additional_pages = {}

# If false, no module index is generated.

#html_domain_indices = True

# If false, no index is generated.

#html_use_index = True

# If true, the index is split into individual pages for each letter.

#html_split_index = False

# If true, links to the reST sources are added to the pages.

#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

#html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.

#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will

# contain a <link> tag referring to it.  The value of this option must be the

# base URL from which the finished HTML is served.

#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").

#html_file_suffix = None

# Output file base name for HTML help builder.

htmlhelp_basename = 'Kallithea-docs'

# -- Options for LaTeX output --------------------------------------------------

# The paper size ('letter' or 'a4').

#latex_paper_size = 'letter'

# The font size ('10pt', '11pt' or '12pt').

#latex_font_size = '10pt'

# Grouping the document tree into LaTeX files. List of tuples

# (source start file, target name, title, author, documentclass [howto/manual]).

latex_documents = [

]

# The name of an image file (relative to this directory) to place at the top of

# the title page.

#latex_logo = None

# For "manual" documents, if this is true, then toplevel headings are parts,

# not chapters.

#latex_use_parts = False

# If true, show page references after internal links.

#latex_show_pagerefs = False

# If true, show URL addresses after external links.

#latex_show_urls = False

# Additional stuff for the LaTeX preamble.

#latex_preamble = ''

# Documents to append as an appendix to all manuals.

#latex_appendices = []

# If false, no module index is generated.

#latex_domain_indices = True

# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples

# (source start file, name, description, authors, manual section).

man_pages = [

]

# Example configuration for intersphinx: refer to the Python standard library.

intersphinx_mapping = {'http://docs.python.org/': None}

from kallithea.model.user_group import UserGroupModel

log = logging.getLogger(__name__)

def store_update(updates, attr, name):

    """

    Stores param in updates dict if it's not instance of Optional

    allows easy updates of passed in params

    """

    if not isinstance(attr, Optional):

        updates[name] = attr

def get_user_or_error(userid):

    """

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

    :param userid:

    """

    user = UserModel().get_user(userid)

    if user is None:

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

    return user

def get_repo_or_error(repoid):

    """

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

    :param repoid:

    """

    repo = RepoModel().get_repo(repoid)

    if repo is None:

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

    return repo

def get_repo_group_or_error(repogroupid):

    """

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

    :param repogroupid:

    """

    repo_group = RepoGroup.guess_instance(repogroupid)

    if repo_group is None:

        raise JSONRPCError(

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

    return repo_group

def get_user_group_or_error(usergroupid):

    """

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

    :param usergroupid:

    """

    user_group = UserGroupModel().get_group(usergroupid)

    if user_group is None:

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

    return user_group

def get_perm_or_error(permid, prefix=None):

    """

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

    :param permid:

    """

    perm = Permission.get_by_key(permid)

    if perm is None:

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

    if prefix:

        if not perm.permission_name.startswith(prefix):

            raise JSONRPCError('permission `%s` is invalid, '

                               'should start with %s' % (permid, prefix))

    return perm

def get_gist_or_error(gistid):

    """

    Get gist by id or gist_access_id or return JsonRPCError if not found

    :param gistid:

    """

    gist = GistModel().get_gist(gistid)

    if gist is None:

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

    return gist

class ApiController(JSONRPCController):

    """

    API Controller

    The authenticated user can be found as request.authuser.

    Example function::

        def func(arg1, arg2,...):

            pass

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

    errors that happens.

    """

    @HasPermissionAnyDecorator('hg.admin')

    def test(self, args):

        return args

    @HasPermissionAnyDecorator('hg.admin')

    def pull(self, repoid, clone_uri=Optional(None)):

        """

        Triggers a pull from remote location on given repo. 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

        :param repoid: repository name or repository id

        :type repoid: str or int

        :param clone_uri: repository URI to pull from (optional)

        :type clone_uri: str

        OUTPUT::

          id : <id_given_in_input>

          result : {

            "msg": "Pulled from `<repository name>`"

            "repository": "<repository name>"

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "Unable to pull changes from `<reponame>`"

          }

        """

        repo = get_repo_or_error(repoid)

        try:

            ScmModel().pull_changes(repo.repo_name,

                                    request.authuser.username,

                                    request.ip_addr,

                                    clone_uri=Optional.extract(clone_uri))

            return dict(

                msg='Pulled from `%s`' % repo.repo_name,

                repository=repo.repo_name

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

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

            )

    @HasPermissionAnyDecorator('hg.admin')

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

        """

        Triggers rescan repositories action. If remove_obsolete is set

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

        aka "clean zombies". This command can be executed only using api_key

        belonging to user with admin rights.

        :param remove_obsolete: deletes repositories from

            database that are not found on the filesystem

        :type remove_obsolete: Optional(bool)

        OUTPUT::

          id : <id_given_in_input>

          result : {

            'added': [<added repository name>,...]

            'removed': [<removed repository name>,...]

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            'Error occurred during rescan repositories action'

          }

        """

        try:

            rm_obsolete = Optional.extract(remove_obsolete)

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

                                            remove_obsolete=rm_obsolete)

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

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'Error occurred during rescan repositories action'

            )

    def invalidate_cache(self, repoid):

        """

        Invalidate cache for repository.

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

        rights or regular user that have write or admin or write access to repository.

        :param repoid: repository name or repository id

        :type repoid: str or int

        OUTPUT::

          id : <id_given_in_input>

          result : {

            'msg': Cache for repository `<repository name>` was invalidated,

            'repository': <repository name>

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            'Error occurred during cache invalidation action'

          }

        """

        repo = get_repo_or_error(repoid)

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

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

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

        try:

            ScmModel().mark_for_invalidation(repo.repo_name)

            return dict(

                msg='Cache for repository `%s` was invalidated' % (repoid,),

                repository=repo.repo_name

            )

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError(

                'Error occurred during cache invalidation action'

            )

    @HasPermissionAnyDecorator('hg.admin')

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

        """

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

        defined IP addresses for given user. If userid is not passed data is

        returned for user who's calling this function.

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

        admin rights.

        :param userid: username to show ips for

        :type userid: Optional(str or int)

        OUTPUT::

            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>"],

                                        },

                                        ...

                                     ]

            }

        """

        if isinstance(userid, Optional):

            userid = request.authuser.user_id

        user = get_user_or_error(userid)

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

        return dict(

            server_ip_addr=request.ip_addr,

            user_ips=ips

        )

    # alias for old

    show_ip = get_ip

    @HasPermissionAnyDecorator('hg.admin')

    def get_server_info(self):

        """

        return server info, including Kallithea version and installed packages

        OUTPUT::

          id : <id_given_in_input>

          result : {

            'modules': [<module name>,...]

            'py_version': <python version>,

            'platform': <platform type>,

            'kallithea_version': <kallithea version>

          }

          error :  null

        """

        return Setting.get_server_info()

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

        """

        Gets a user by username or user_id, Returns empty result if user is

        not found. If userid param is skipped it is set to id of user who is

        calling this method. This command can be executed only using api_key

        belonging to user with admin rights, or regular users that cannot

        specify different userid than theirs

        :param userid: user to get data for

        :type userid: Optional(str or int)

        OUTPUT::

            id : <id_given_in_input>

            result: None if user does not exist or

                    {

                        "user_id" :     "<user_id>",

                        "api_key" :     "<api_key>",

                        "api_keys":     "[<list of all API keys including additional ones>]"

                        "username" :    "<username>",

                        "firstname":    "<firstname>",

                        "lastname" :    "<lastname>",

                        "email" :       "<email>",

                        "emails":       "[<list of all emails including additional ones>]",

                        "ip_addresses": "[<ip_address_for_user>,...]",

                        "active" :      "<bool: user active>",

                        "admin" :       "<bool: user is admin>",

                        "extern_name" : "<extern_name>",

                        "extern_type" : "<extern type>

                        "last_login":   "<last_login>",

                        "permissions": {

                            "global": ["hg.create.repository",

                                       "repository.read",

                                       "hg.register.manual_activate"],

                            "repositories": {"repo1": "repository.none"},

                            "repositories_groups": {"Group1": "group.read"}

                         },

                    }

            error:  null

        """

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

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

            # he is not allowed to do that

            if not isinstance(userid, Optional) and userid != request.authuser.user_id:

                raise JSONRPCError(

                    'userid is not the same as your user'

                )

        if isinstance(userid, Optional):

            userid = request.authuser.user_id

        user = get_user_or_error(userid)

        data = user.get_api_data()

        data['permissions'] = AuthUser(user_id=user.user_id).permissions

        return data

    @HasPermissionAnyDecorator('hg.admin')

    def get_users(self):

        """

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

        belonging to user with admin rights.

        OUTPUT::

            id : <id_given_in_input>

            result: [<user_object>, ...]

            error:  null

        """

        return [

            user.get_api_data()

            for user in User.query()

                .order_by(User.username)

                .filter_by(is_default_user=False)

        ]

    @HasPermissionAnyDecorator('hg.admin')

    def create_user(self, username, email, password=Optional(''),

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

                    extern_type=Optional(User.DEFAULT_AUTH_TYPE),

                    extern_name=Optional('')):

        """

        Creates new user. Returns new user object. This command can

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

        :param username: new username

        :type username: str or int

        :param email: email

        :type email: str

        :param password: password

        :type password: Optional(str)

        :param firstname: firstname

        :type firstname: Optional(str)

        :param lastname: lastname

        :type lastname: Optional(str)

        :param active: active

        :type active: Optional(bool)

        :param admin: admin

        :type admin: Optional(bool)

        :param extern_name: name of extern

        :type extern_name: Optional(str)

        :param extern_type: extern_type

        :type extern_type: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

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

                      "user": <user_obj>

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "user `<username>` already exist"

            or

            "email `<email>` already exist"

            or

            "failed to create user `<username>`"

          }

        """

        if User.get_by_username(username):

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

        if User.get_by_email(email):

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

        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)

            )

            Session().commit()

            return dict(

                msg='created new user `%s`' % username,

                user=user.get_api_data()

            )

        except Exception:

            log.error(traceback.format_exc())

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

    @HasPermissionAnyDecorator('hg.admin')

    def update_user(self, 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 given user if such user exists. This command can

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

        :param userid: userid to update

        :type userid: str or int

        :param username: new username

        :type username: str or int

        :param email: email

        :type email: str

        :param password: password

        :type password: Optional(str)

        :param firstname: firstname

        :type firstname: Optional(str)

        :param lastname: lastname

        :type lastname: Optional(str)

        :param active: active

        :type active: Optional(bool)

        :param admin: admin

        :type admin: Optional(bool)

        :param extern_name:

        :type extern_name: Optional(str)

        :param extern_type:

        :type extern_type: Optional(str)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "updated user ID:<userid> <username>",

                      "user": <user_object>,

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to update user `<username>`"

          }

        """

        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 dict(

                msg='updated user ID:%s %s' % (user.user_id, user.username),

                user=user.get_api_data()

            )

        except DefaultUserException:

            log.error(traceback.format_exc())

            raise JSONRPCError('editing default user is forbidden')

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to update user `%s`' % (userid,))

    @HasPermissionAnyDecorator('hg.admin')

    def delete_user(self, userid):

        """

        deletes given user if such user exists. This command can

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

        :param userid: user to delete

        :type userid: str or int

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg" : "deleted user ID:<userid> <username>",

                      "user": null

                    }

            error:  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to delete user ID:<userid> <username>"

          }

        """

        user = get_user_or_error(userid)

        try:

            UserModel().delete(userid)

            Session().commit()

            return dict(

                msg='deleted user ID:%s %s' % (user.user_id, user.username),

                user=None

            )

        except Exception:

            log.error(traceback.format_exc())

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

                               % (user.user_id, user.username))

    # permission check inside

    def get_user_group(self, usergroupid):

        """

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

        belonging to user with admin rights or user who has at least

        read access to user group.

        :param usergroupid: id of user_group to edit

        :type usergroupid: str or int

        OUTPUT::

            id : <id_given_in_input>

            result : None if group not exist

                     {

                       "users_group_id" : "<id>",

                       "group_name" :     "<groupname>",

                       "active":          "<bool>",

                       "members" :  [<user_obj>,...]

                     }

            error : null

        """

        user_group = get_user_group_or_error(usergroupid)

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

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

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

        data = user_group.get_api_data()

        return data

    # permission check inside

    def get_user_groups(self):

        """

        Lists all existing user groups. This command can be executed only using

        api_key belonging to user with admin rights or user who has at least

        read access to user group.

        OUTPUT::