# -- 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.

# 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}

    @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

        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::

            id : <id_given_in_input>

            result : [<user_group_obj>,...]

            error : null

        """

        return [

            user_group.get_api_data()

            for user_group in UserGroupList(UserGroup.query().all(), perm_level='read')

        ]

    @HasPermissionAnyDecorator('hg.admin', 'hg.usergroup.create.true')

                          owner=Optional(OAttr('apiuser')), active=Optional(True)):

        """

        Creates new user group. This command can be executed only using api_key

        belonging to user with admin rights or an user who has create user group

        permission

        :param group_name: name of new user group

        :type group_name: str

        :param description: group description

        :type description: str

        :param owner: owner of group. If not passed apiuser is the owner

        :type owner: Optional(str or int)

        :param active: group is active

        :type active: Optional(bool)

        OUTPUT::

            id : <id_given_in_input>

            result: {

                      "msg": "created new user group `<groupname>`",

                      "user_group": <user_group_object>

                    }

            error:  null

        info = dict(changeset.as_dict())

        with_reviews = Optional.extract(with_reviews)

        if with_reviews:

            reviews = ChangesetStatusModel().get_statuses(

                                repo.repo_name, raw_id)

            info["reviews"] = reviews

        return info

    # permission check inside

    def get_pullrequest(self, pullrequest_id):

        """

        Get given pull request by id

        """

        pull_request = PullRequest.get(pullrequest_id)

        if pull_request is None:

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

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

            raise JSONRPCError('not allowed')

        return pull_request.get_api_data()

    # permission check inside

        """

        Add comment, close and change status of pull request.

        """

        apiuser = get_user_or_error(request.authuser.user_id)

        pull_request = PullRequest.get(pull_request_id)

        if pull_request is None:

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

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

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

                               ' to the source repository.')

        owner = apiuser.user_id == pull_request.owner_id

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

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

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

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

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

        if pull_request.is_closed():

            raise JSONRPCError('pull request is already closed')

        comment = ChangesetCommentsModel().create(

            text=comment_msg,

            repo=pull_request.org_repo.repo_id,

            author=apiuser.user_id,

            pull_request=pull_request.pull_request_id,

            'path': SCHEMA

        }.get(c.cur_type, SCHEMA)

        log.debug('IDX: %s', index_name)

        log.debug('SCHEMA: %s', schema_defn)

        if c.cur_query:

            cur_query = c.cur_query.lower()

            log.debug(cur_query)

        if c.cur_query:

            p = safe_int(request.GET.get('page'), 1)

            highlight_items = set()

            index_dir = config['index_dir']

            try:

                if not exists_in(index_dir, index_name):

                    raise EmptyIndexError

                idx = open_dir(index_dir, indexname=index_name)

                searcher = idx.searcher()

                qp = QueryParser(search_type, schema=schema_defn)

                if c.repo_name:

                    # use "repository_rawname:" instead of "repository:"

                    # for case-sensitive matching

                try:

                    query = qp.parse(cur_query)

                    # extract words for highlight

                    if isinstance(query, Phrase):

                        highlight_items.update(query.words)

                    elif isinstance(query, Prefix):

                        highlight_items.add(query.text)

                    else:

                        for i in query.all_terms():

                            if i[0] in ['content', 'message']:

                                highlight_items.add(i[1])

                    matcher = query.matcher(searcher)

                    log.debug('query: %s', query)

                    log.debug('hl terms: %s', highlight_items)

                    results = searcher.search(query)

                    res_ln = len(results)

                    c.runtime = '%s results (%.3f seconds)' % (

                        res_ln, results.runtime

                    )

                    repo_location = RepoModel().repos_path

                    c.formated_results = Page(

                admin=user_data["admin"],

                extern_name=user_data["extern_name"],

                extern_type=self.name,

            )

            # enforce user is just in given groups, all of them has to be ones

            # created from plugins. We store this info in _group_data JSON field

            groups = user_data['groups'] or []

            UserGroupModel().enforce_groups(user, groups, self.name)

            Session().commit()

        return user_data

def loadplugin(plugin):

    """

    Imports, instantiates, and returns the authentication plugin in the module named by plugin

    (e.g., plugin='kallithea.lib.auth_modules.auth_internal'). Returns an instance of the

    KallitheaAuthPluginBase subclass on success, raises exceptions on failure.

    raises:

        AttributeError -- no KallitheaAuthPlugin class in the module

        TypeError -- if the KallitheaAuthPlugin is not a subclass of ours KallitheaAuthPluginBase

        ImportError -- if we couldn't import the plugin at all

    """

    log.debug("Importing %s", plugin)

        if len(parts) == 2:

            _module, pn = parts

    PLUGIN_CLASS_NAME = "KallitheaAuthPlugin"

    try:

        module = importlib.import_module(plugin)

    except (ImportError, TypeError):

        log.error(traceback.format_exc())

        # TODO: make this more error prone, if by some accident we screw up

        # the plugin name, the crash is pretty bad and hard to recover

        raise

    log.debug("Loaded auth plugin from %s (module:%s, file:%s)",

              plugin, module.__name__, module.__file__)

    pluginclass = getattr(module, PLUGIN_CLASS_NAME)

    if not issubclass(pluginclass, KallitheaAuthPluginBase):

        raise TypeError("Authentication class %s.KallitheaAuthPlugin is not "

                        "a subclass of %s" % (plugin, KallitheaAuthPluginBase))

    plugin = pluginclass()

    if plugin.plugin_settings.__func__ != KallitheaAuthPluginBase.plugin_settings:

        raise TypeError("Authentication class %s.KallitheaAuthPluginBase "

                        "has overridden the plugin_settings method, which is "

                        "forbidden." % plugin)

    return plugin

            ('ga_code', '', 'unicode'),

            ('show_public_icon', True, 'bool'),

            ('show_private_icon', True, 'bool'),

            ('stylify_metalabels', False, 'bool'),

            ('dashboard_items', 100, 'int'), # TODO: call it page_size

            ('admin_grid_items', 25, 'int'),

            ('show_version', True, 'bool'),

            ('use_gravatar', True, 'bool'),

            ('gravatar_url', User.DEFAULT_GRAVATAR_URL, 'unicode'),

            ('clone_uri_tmpl', Repository.DEFAULT_CLONE_URI, 'unicode'),

            ('clone_ssh_tmpl', Repository.DEFAULT_CLONE_SSH, 'unicode'),

        ]

        for key, val, type_ in settings:

            sett = Setting(key, val, type_)

            self.sa.add(sett)

        self.create_auth_plugin_options()

        self.create_default_options()

        log.info('Populated Ui and Settings defaults')

    def create_user(self, username, password, email='', admin=False):

        log.info('creating user %s', username)

        UserModel().create_or_update(username, password, email,

                                     active=True, admin=admin,

                                     extern_type=User.DEFAULT_AUTH_TYPE)

    def create_default_user(self):

        log.info('creating default user')

        # create default user for handling default permissions.

        user = UserModel().create_or_update(username=User.DEFAULT_USER,

                                            password=str(uuid.uuid1())[:20],

                                            email='anonymous@kallithea-scm.org',

        # based on configuration options activate/deactivate this user which

        # controls anonymous access

        if self.cli_args.get('public_access') is False:

            log.info('Public access disabled')

            user.active = False

            Session().commit()

    def create_permissions(self):

        """

        Creates all permissions defined in the system

        """

        # module.(access|create|change|delete)_[name]

        # module.(none|read|write|admin)

        log.info('creating permissions')

        PermissionModel().create_permissions()

    def populate_default_permissions(self):

        """

        Populate default permissions. It will create only the default

        permissions that are missing, and not alter already defined ones

        """

        log.info('creating default user permissions')

        PermissionModel().create_default_permissions(user=User.DEFAULT_USER)

        timezone = (offset.days * 24 * 60) + (offset.seconds / 60)

        hour, minute = divmod(timezone, 60)

        return time_str + "%+03d%02d" % (hour, minute)

    else:

        return date.strftime('%a, %d %b %Y %H:%M:%S -0000')

# From ``django.utils.feedgenerator`` via webhelpers.feedgenerator

def rfc3339_date(date):

    if getattr(date, "tzinfo", False):

        time_str = date.strftime('%Y-%m-%dT%H:%M:%S')

        offset = date.tzinfo.utcoffset(date)

        timezone = (offset.days * 24 * 60) + (offset.seconds / 60)

        hour, minute = divmod(timezone, 60)

        return time_str + "%+03d:%02d" % (hour, minute)

    else:

        return date.strftime('%Y-%m-%dT%H:%M:%SZ')

# From ``django.utils.feedgenerator`` via webhelpers.feedgenerator

def get_tag_uri(url, date):

    "Creates a TagURI. See http://diveintomark.org/archives/2004/05/28/howto-atom-id"

    tag = re.sub('^http://', '', url)

    if date is not None:

        tag = re.sub('/', ',%s:/' % date.strftime('%Y-%m-%d'), tag, 1)

    tag = re.sub('#', '/', tag)

class Attributes(object):

    """Simple namespace for attribute dict access in mako and elsewhere"""

    def __init__(self, a_dict):

        self.__dict__ = a_dict

class _Feeder(object):

    content_type = None

    template = None  # subclass must provide a mako.template.Template

    @classmethod

    def render(cls, header, entries):

        try:

            latest_pubdate = max(

                pubdate for pubdate in (e.get('pubdate') for e in entries)

                if pubdate

            )

        except ValueError:  # max() arg is an empty sequence ... or worse

            latest_pubdate = datetime.datetime.now()

        return cls.template.render(

        res = self.searcher.stored_fields(docid[0])

        log.debug('result: %s', res)

        if self.search_type == 'content':

            full_repo_path = os.path.join(self.repo_location, res['repository'])

            f_path = res['path'].split(full_repo_path)[-1]

            f_path = f_path.lstrip(os.sep)

            content_short = self.get_short_content(res, docid[1])

            res.update({'content_short': content_short,

                        'content_short_hl': self.highlight(content_short),

                        'f_path': f_path

            })

        elif self.search_type == 'path':

            full_repo_path = os.path.join(self.repo_location, res['repository'])

            f_path = res['path'].split(full_repo_path)[-1]

            f_path = f_path.lstrip(os.sep)

            res.update({'f_path': f_path})

        elif self.search_type == 'message':

            res.update({'message_hl': self.highlight(res['message'])})

        log.debug('result: %s', res)

        return res

    def get_short_content(self, res, chunks):

    def get_chunks(self):

        """

        Smart function that implements chunking the content

        but not overlap chunks so it doesn't highlight the same

        close occurrences twice.

        """

        memory = [(0, 0)]

        try:

            supports_positions = self.matcher.supports('positions')

        except AttributeError:  # 'NoneType' object has no attribute 'supports' (because matcher never get a format)

            supports_positions = False

        if supports_positions:

            for span in self.matcher.spans():

                start = span.startchar or 0

                end = span.endchar or 0

                start_offseted = max(0, start - self.fragment_size)

                end_offseted = end + self.fragment_size

                if start_offseted < memory[-1][1]:

                    start_offseted = memory[-1][1]

                memory.append((start_offseted, end_offseted,))

                yield (start_offseted, end_offseted,)

        Just index the content of chosen files, skipping binary files

        """

        return (node.extension in INDEX_EXTENSIONS or node.name in INDEX_FILENAMES) and \

               not node.is_binary

    def get_node_mtime(self, node):

        return mktime(node.last_changeset.date.timetuple())

    def add_doc(self, writer, path, repo, repo_name, index_rev=None):

        """

        Adding doc to writer this function itself fetches data from

        the instance of vcs backend

        """

        try:

            node = self.get_node(repo, path, index_rev)

        except (ChangesetError, NodeDoesNotExistError):

            log.debug("    >> %s - not found in %s %s", path, repo, index_rev)

            return 0, 0

        indexed = indexed_w_content = 0

        if self.is_indexable_node(node):

            bytes_content = node.content

            if b'\0' in bytes_content:

                log.warning('    >> %s - no text content', path)

            else:

                log.debug('    >> %s', path)

                u_content = safe_str(bytes_content)

                indexed_w_content += 1

        else:

            log.debug('    >> %s - not indexable', path)

            # just index file name without it's content

            indexed += 1

        writer.add_document(

            fileid=path,

            owner=repo.contact,

            repository_rawname=repo_name,

            repository=repo_name,

            path=path,

            content=u_content,

            modtime=self.get_node_mtime(node),

            extension=node.extension

        )

        return indexed, indexed_w_content

    def index_changesets(self, writer, repo_name, repo, start_rev=None):

        """

        Add all changeset in the vcs repo starting at start_rev

        to the index writer

        :param writer: the whoosh index writer to add to

        :param repo_name: name of the repository from whence the

          changeset originates including the repository group

        :param repo: the vcs repository instance to index changesets for,

          the presumption is the repo has changesets to index

          the repo

        """

        if start_rev is None:

            start_rev = repo[0].raw_id

        log.debug('Indexing changesets in %s, starting at rev %s',

                  repo_name, start_rev)

        indexed = 0

        cs_iter = repo.get_changesets(start=start_rev)

        total = len(cs_iter)

        for cs in cs_iter:

            indexed += 1

            log.debug('    >> %s %s/%s', cs, indexed, total)

            writer.add_document(

                raw_id=cs.raw_id,

                owner=repo.contact,

                date=cs._timestamp,

                repository_rawname=repo_name,

                repository=repo_name,

                author=cs.author,

                message=cs.message,

                last=cs.last,

            )

        return indexed

    def index_files(self, file_idx_writer, repo_name, repo):

        """

        Index files for given repo_name

        :param file_idx_writer: the whoosh index writer to add to

        :param repo_name: name of the repository we're indexing

        :param repo: instance of vcs repo

        """

        i_cnt = iwc_cnt = 0

        log.debug('Building file index for %s @revision:%s', repo_name,

                                                self._get_index_revision(repo))

        index_rev = self._get_index_revision(repo)

        for idx_path in self.get_paths(repo):

            i, iwc = self.add_doc(file_idx_writer, idx_path, repo, repo_name, index_rev)

            i_cnt += i

            iwc_cnt += iwc

        log.debug('added %s files %s with content for repo %s',

                  i_cnt + iwc_cnt, iwc_cnt, repo.path)

        return i_cnt, iwc_cnt

    def update_changeset_index(self):

        idx = open_dir(self.index_location, indexname=CHGSET_IDX_NAME)

        with idx.searcher() as searcher:

            writer = idx.writer()

            writer_is_dirty = False

            try:

                indexed_total = 0

                repo_name = None

                for repo_name, repo in sorted(self.repo_paths.items()):

                    log.debug('Updating changeset index for repo %s', repo_name)

                    # skip indexing if there aren't any revs in the repo

                    num_of_revs = len(repo)

                    if num_of_revs < 1:

                        continue

                    qp = QueryParser('repository', schema=CHGSETS_SCHEMA)

                    results = searcher.search(q)

                    # default to scanning the entire repo

                    last_rev = 0

                    start_id = None

                    if len(results) > 0:

                        # assuming that there is only one result, if not this

                        # may require a full re-index.

                        start_id = results[0]['raw_id']

                        last_rev = repo.get_changeset(revision=start_id).revision

                    # there are new changesets to index or a new repo to index

                    if last_rev == 0 or num_of_revs > last_rev + 1:

                        # delete the docs in the index for the previous

                        # last changeset(s)

                        for hit in results:

                                            (repo_name, hit['raw_id']))

                            writer.delete_by_query(q)

                        # index from the previous last changeset + all new ones

                        indexed_total += self.index_changesets(writer,

                                                repo_name, repo, start_id)

                        writer_is_dirty = True

                log.debug('indexed %s changesets for repo %s',

                          indexed_total, repo_name

                )

            finally:

                if writer_is_dirty:

                    log.debug('>> COMMITING CHANGES TO CHANGESET INDEX<<')

                    writer.commit(merge=True)

                    log.debug('>>> FINISHED REBUILDING CHANGESET INDEX <<<')

                else:

                    log.debug('>> NOTHING TO COMMIT TO CHANGESET INDEX<<')

    def update_file_index(self):

                  'AND REPOS %s', INDEX_EXTENSIONS, ' and '.join(self.repo_paths))

        idx = open_dir(self.index_location, indexname=self.indexname)

        # The set of all paths in the index

        indexed_paths = set()

        # The set of all paths we need to re-index

        to_index = set()

        writer = idx.writer()

        writer_is_dirty = False

        try:

            with idx.reader() as reader:

                # Loop over the stored fields in the index

                for fields in reader.all_stored_fields():

                    indexed_path = fields['path']

                    indexed_repo_path = fields['repository']

                    indexed_paths.add(indexed_path)

                    if indexed_repo_path not in self.filtered_repo_update_paths:

                        continue

                    repo = self.repo_paths[indexed_repo_path]

# 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 logging

import os

import sys

log = logging.getLogger(__name__)

def current_locale_is_valid():

    """Verify that things work when Dulwich passes unicode paths to the file system layer.

    Note: UTF-8 is preferred, but for example ISO-8859-1 or mbcs should also

    work under the right circumstances."""

    try:

    except UnicodeEncodeError:

        log.error("Cannot encode Unicode paths to file system encoding %r", sys.getfilesystemencoding())

        for var in ['LC_ALL', 'LC_CTYPE', 'LANG']:

            if var in os.environ:

                val = os.environ[var]

                log.error("Note: Environment variable %s is %r - perhaps change it to some other value from 'locale -a', like 'C.UTF-8' or 'en_US.UTF-8'", var, val)

                break

        else:

            log.error("Note: No locale setting found in environment variables - perhaps set LC_CTYPE to some value from 'locale -a', like 'C.UTF-8' or 'en_US.UTF-8'")

        return False

    return True

def get_current_locale():

    """Return the current locale based on environment variables.

    There does not seem to be a good (and functional) way to get it via Python.

    """

    for var in ['LC_ALL', 'LC_CTYPE', 'LANG']:

        val = os.environ.get(var)

        if val:

            log.debug('Determined current locale via environment variable %s (%s)', var, val)

            return val

    return None

            return exc.HTTPMethodNotAllowed()

        if 'CONTENT_LENGTH' in environ:

            inputstream = FileWrapper(environ['wsgi.input'],

                                      req.content_length)

        else:

            inputstream = environ['wsgi.input']

        gitenv = dict(os.environ)

        # forget all configs

        gitenv['GIT_CONFIG_NOGLOBAL'] = '1'

        cmd = [_git_path, git_command[4:], '--stateless-rpc', self.content_path]

        log.debug('handling cmd %s', cmd)

        try:

            out = subprocessio.SubprocessIOChunker(

                cmd,

                inputstream=inputstream,

                env=gitenv,

                cwd=self.content_path,