In normal operation, Kallithea will keep caches up-to-date

    automatically. However, if repositories are externally modified, e.g. by

    a direct push via the filesystem rather than via a Kallithea URL,

    Kallithea is not aware of it. In this case, you should manually run this

    command to update the repository cache.

    If no repositories are specified, the caches of all repositories are

    updated.

    """

    if not repositories:

        repo_list = Repository.query().all()

    else:

        repo_names = [safe_unicode(n.strip()) for n in repositories]

        repo_list = list(Repository.query()

                        .filter(Repository.repo_name.in_(repo_names)))

    for repo in repo_list:

        # update latest revision metadata in database

        repo.update_changeset_cache()

        # invalidate in-memory VCS object cache... will be repopulated on

        # first access

        repo.set_invalidate()

    Session().commit()

    click.echo('Updated database with information about latest change in the following %s repositories:' % (len(repo_list)))

    click.echo('\n'.join(repo.repo_name for repo in repo_list))

@cli_base.register_command(config_file_initialize_app=True)

@click.option('--ask/--no-ask', default=True, help='Ask for confirmation or not. Default is --ask.')

@click.option('--older-than',

        help="""Only purge repositories that have been removed at least the given time ago.

        For example, '--older-than=30d' purges repositories deleted 30 days ago or longer.

        Possible suffixes: d (days), h (hours), m (minutes), s (seconds).""")

def repo_purge_deleted(ask, older_than):

    """Purge backups of deleted repositories.

    When a repository is deleted via the Kallithea web interface, the actual

    data is still present on the filesystem but set aside using a special name.

    This command allows to delete these files permanently.

    """

    def _parse_older_than(val):

        regex = re.compile(r'((?P<days>\d+?)d)?((?P<hours>\d+?)h)?((?P<minutes>\d+?)m)?((?P<seconds>\d+?)s)?')

        parts = regex.match(val)

        if not parts:

            return

        parts = parts.groupdict()

        time_params = {}

            if param:

                time_params[name] = int(param)

        return datetime.timedelta(**time_params)

    def _extract_date(name):

        """

        Extract the date part from rm__<date> pattern of removed repos,

        and convert it to datetime object

        :param name:

        """

        date_part = name[4:19]  # 4:19 since we don't parse milliseconds

        return datetime.datetime.strptime(date_part, '%Y%m%d_%H%M%S')

    repos_location = Ui.get_repos_location()

    to_remove = []

    for dn_, dirs, f in os.walk(safe_str(repos_location)):

        alldirs = list(dirs)

        del dirs[:]

        if ('.hg' in alldirs or

            '.git' in alldirs or

            '.svn' in alldirs or

            'objects' in alldirs and ('refs' in alldirs or 'packed-refs' in f)

        ):

            continue

        for loc in alldirs:

            if REMOVED_REPO_PAT.match(loc):

                to_remove.append([os.path.join(dn_, loc),

                                  _extract_date(loc)])

            else:

                dirs.append(loc)

        if dirs:

            click.echo('Scanning: %s' % dn_)

    if not to_remove:

        click.echo('There are no deleted repositories.')

        return

    # filter older than (if present)!

    if older_than:

        now = datetime.datetime.now()

        to_remove_filtered = []

        older_than_date = _parse_older_than(older_than)

        for name, date_ in to_remove:

            repo_age = now - date_

            if repo_age > older_than_date:

                to_remove_filtered.append([name, date_])

:author: marcink

:copyright: (c) 2013 RhodeCode GmbH, and others.

:license: GPLv3, see LICENSE.md for more details.

"""

import logging

import traceback

import formencode

from formencode import htmlfill

from tg import request

from tg.i18n import ugettext as _

from webob.exc import HTTPFound

from kallithea.config.routing import url

from kallithea.lib import helpers as h

from kallithea.lib.auth import HasPermissionAnyDecorator, LoginRequired

from kallithea.lib.base import BaseController, render

from kallithea.model.db import Setting

from kallithea.model.forms import DefaultsForm

from kallithea.model.meta import Session

log = logging.getLogger(__name__)

class DefaultsController(BaseController):

    @LoginRequired()

    @HasPermissionAnyDecorator('hg.admin')

    def _before(self, *args, **kwargs):

        super(DefaultsController, self)._before(*args, **kwargs)

    def index(self, format='html'):

        defaults = Setting.get_default_repo_settings()

        return htmlfill.render(

            render('admin/defaults/defaults.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False

        )

    def update(self, id):

        _form = DefaultsForm()()

        try:

            form_result = _form.to_python(dict(request.POST))

                setting = Setting.create_or_update(k, v)

            Session().commit()

            h.flash(_('Default settings updated successfully'),

                    category='success')

        except formencode.Invalid as errors:

            defaults = errors.value

            return htmlfill.render(

                render('admin/defaults/defaults.html'),

                defaults=defaults,

                errors=errors.error_dict or {},

                prefix_error=False,

                encoding="UTF-8",

                force_defaults=False)

        except Exception:

            log.error(traceback.format_exc())

            h.flash(_('Error occurred during update of defaults'),

                    category='error')

        raise HTTPFound(location=url('defaults'))

                except Exception:

                    log.error(traceback.format_exc())

                    h.flash(_('Error occurred during hook creation'),

                            category='error')

                raise HTTPFound(location=url('admin_settings_hooks'))

        defaults = Setting.get_app_settings()

        defaults.update(self._get_hg_ui_settings())

        c.hooks = Ui.get_builtin_hooks()

        c.custom_hooks = Ui.get_custom_hooks()

        return htmlfill.render(

            render('admin/settings/settings.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False)

    @HasPermissionAnyDecorator('hg.admin')

    def settings_search(self):

        c.active = 'search'

        if request.POST:

            repo_location = self._get_hg_ui_settings()['paths_root_path']

            full_index = request.POST.get('full_index', False)

            tasks.whoosh_index(repo_location, full_index)

            h.flash(_('Whoosh reindex task scheduled'), category='success')

            raise HTTPFound(location=url('admin_settings_search'))

        defaults = Setting.get_app_settings()

        defaults.update(self._get_hg_ui_settings())

        return htmlfill.render(

            render('admin/settings/settings.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False)

    @HasPermissionAnyDecorator('hg.admin')

    def settings_system(self):

        c.active = 'system'

        defaults = Setting.get_app_settings()

        defaults.update(self._get_hg_ui_settings())

        import kallithea

        c.ini = kallithea.CONFIG

        server_info = Setting.get_server_info()

            setattr(c, key, val)

        return htmlfill.render(

            render('admin/settings/settings.html'),

            defaults=defaults,

            encoding="UTF-8",

            force_defaults=False)

            self._req_method = json_body['method']

            self._request_params = json_body['args']

            if not isinstance(self._request_params, dict):

                self._request_params = {}

            log.debug('method: %s, params: %s',

                      self._req_method, self._request_params)

        except KeyError as e:

            raise JSONRPCErrorResponse(retid=self._req_id,

                                       message='Incorrect JSON query missing %s' % e)

        # check if we can find this session using api_key

        try:

            u = User.get_by_api_key(self._req_api_key)

            auth_user = AuthUser.make(dbuser=u, ip_addr=ip_addr)

            if auth_user is None:

                raise JSONRPCErrorResponse(retid=self._req_id,

                                           message='Invalid API key')

        except Exception as e:

            raise JSONRPCErrorResponse(retid=self._req_id,

                                       message='Invalid API key')

        request.authuser = auth_user

        request.ip_addr = ip_addr

        self._error = None

        try:

            self._func = self._find_method()

        except AttributeError as e:

            raise JSONRPCErrorResponse(retid=self._req_id,

                                       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 = [type(arg) for arg in argspec[3] or []]

        default_empty = type(NotImplemented)

        # kw arguments required by this method

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

                                                  fillvalue=default_empty))

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

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

            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:

                raise JSONRPCErrorResponse(

                    retid=self._req_id,

                    message='Missing non optional `%s` arg in JSON DATA' % arg,

                )

        extra = set(self._request_params).difference(func_kwargs)

        if extra:

            raise JSONRPCErrorResponse(

                retid=self._req_id,

                message='Unknown %s arg in JSON DATA' %

                        ', '.join('`%s`' % arg for arg in extra),

            )

        self._rpc_args = {}

        self._rpc_args.update(self._request_params)

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

        self._rpc_args['environ'] = environ

        log.info('IP: %s Request to %s time: %.3fs' % (

            self._get_ip_addr(environ),

            get_path_info(environ), time.time() - start)

        )

        state.set_action(self._rpc_call, [])

        state.set_params(self._rpc_args)

        return state

    def _rpc_call(self, action, environ, **rpc_args):

        """

        Call the specified RPC Method

        """

        raw_response = ''

        try:

            raw_response = getattr(self, action)(**rpc_args)

            if isinstance(raw_response, HTTPError):

                self._error = str(raw_response)

        except JSONRPCError as e:

            self._error = unicode(e)

        except Exception as e:

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

        user = None

    if user is None or user.is_default_user:

        h.flash(_('Invalid reviewer "%s" specified') % user_id, category='error')

        raise HTTPBadRequest()

    return user

class PullrequestsController(BaseRepoController):

    def _get_repo_refs(self, repo, rev=None, branch=None, branch_rev=None):

        """return a structure with repo's interesting changesets, suitable for

        the selectors in pullrequest.html

        rev: a revision that must be in the list somehow and selected by default

        branch: a branch that must be in the list and selected by default - even if closed

        branch_rev: a revision of which peers should be preferred and available."""

        # list named branches that has been merged to this named branch - it should probably merge back

        peers = []

        if rev:

            rev = safe_str(rev)

        if branch:

            branch = safe_str(branch)

        if branch_rev:

            # a revset not restricting to merge() would be better

            # (especially because it would get the branch point)

            # ... but is currently too expensive

            # including branches of children could be nice too

            peerbranches = set()

            for i in repo._repo.revs(

                b"sort(parents(branch(id(%s)) and merge()) - branch(id(%s)), -rev)",

                ascii_bytes(branch_rev), ascii_bytes(branch_rev),

            ):

                for abranch in repo.get_changeset(i).branches:

                    if abranch not in peerbranches:

                        n = 'branch:%s:%s' % (abranch, repo.get_changeset(abranch).raw_id)

                        peers.append((n, abranch))

                        peerbranches.add(abranch)

        selected = None

        tiprev = repo.tags.get('tip')

        tipbranch = None

        branches = []

            n = 'branch:%s:%s' % (abranch, branchrev)

            desc = abranch

            if branchrev == tiprev:

                tipbranch = abranch

                desc = '%s (current tip)' % desc

            branches.append((n, desc))

            if rev == branchrev:

                selected = n

            if branch == abranch:

                if not rev:

                    selected = n

                branch = None

        if branch:  # branch not in list - it is probably closed

            branchrev = repo.closed_branches.get(branch)

            if branchrev:

                n = 'branch:%s:%s' % (branch, branchrev)

                branches.append((n, _('%s (closed)') % branch))

                selected = n

                branch = None

            if branch:

                log.debug('branch %r not found in %s', branch, repo)

        bookmarks = []

            n = 'book:%s:%s' % (bookmark, bookmarkrev)

            bookmarks.append((n, bookmark))

            if rev == bookmarkrev:

                selected = n

        tags = []

            if tag == 'tip':

                continue

            n = 'tag:%s:%s' % (tag, tagrev)

            tags.append((n, tag))

            # note: even if rev == tagrev, don't select the static tag - it must be chosen explicitly

        # prio 1: rev was selected as existing entry above

        # prio 2: create special entry for rev; rev _must_ be used

        specials = []

        if rev and selected is None:

            selected = 'rev:%s:%s' % (rev, rev)

            specials = [(selected, '%s: %s' % (_("Changeset"), rev[:12]))]

        # prio 3: most recent peer branch

        if peers and not selected:

            selected = peers[0][0]

        # prio 4: tip revision

        if not selected:

            if h.is_hg(repo):

                if tipbranch:

                    selected = 'branch:%s:%s' % (tipbranch, tiprev)

                else:

                    selected = 'tag:null:' + repo.EMPTY_CHANGESET

                    tags.append((selected, 'null'))

            else:

                if 'master' in repo.branches:

                    selected = 'branch:master:%s' % repo.branches['master']

                else:

                    k, v = list(repo.branches.items())[0]

                    selected = 'branch:%s:%s' % (k, v)

        groups = [(specials, _("Special")),

                  (peers, _("Peer branches")),

                  (bookmarks, _("Bookmarks")),

                  (branches, _("Branches")),

                  (tags, _("Tags")),

                  ]

        return [g for g in groups if g[0]], selected

    def _is_allowed_to_change_status(self, pull_request):

        if pull_request.is_closed():

            return False

        owner = request.authuser.user_id == pull_request.owner_id

        reviewer = PullRequestReviewer.query() \

            .filter(PullRequestReviewer.pull_request == pull_request) \

    def make(cls, dbuser=None, is_external_auth=False, ip_addr=None):

        """Create an AuthUser to be authenticated ... or return None if user for some reason can't be authenticated.

        Checks that a non-None dbuser is provided, is active, and that the IP address is ok.

        """

        assert ip_addr is not None

        if dbuser is None:

            log.info('No db user for authentication')

            return None

        if not dbuser.active:

            log.info('Db user %s not active', dbuser.username)

            return None

        allowed_ips = AuthUser.get_allowed_ips(dbuser.user_id, cache=True)

        if not check_ip_access(source_ip=ip_addr, allowed_ips=allowed_ips):

            log.info('Access for %s from %s forbidden - not in %s', dbuser.username, ip_addr, allowed_ips)

            return None

        return cls(dbuser=dbuser, is_external_auth=is_external_auth)

    def __init__(self, user_id=None, dbuser=None, is_external_auth=False):

        self.is_external_auth = is_external_auth # container auth - don't show logout option

        # These attributes will be overridden by fill_data, below, unless the

        # requested user cannot be found and the default anonymous user is

        # not enabled.

        self.user_id = None

        self.username = None

        self.api_key = None

        self.name = ''

        self.lastname = ''

        self.email = ''

        self.admin = False

        # Look up database user, if necessary.

        if user_id is not None:

            assert dbuser is None

            log.debug('Auth User lookup by USER ID %s', user_id)

            dbuser = UserModel().get(user_id)

            assert dbuser is not None

        else:

            assert dbuser is not None

            log.debug('Auth User lookup by database user %s', dbuser)

        log.debug('filling %s data', dbuser)

        self.is_anonymous = dbuser.is_default_user

        if dbuser.is_default_user and not dbuser.active:

            self.username = 'None'

            self.is_default_user = False

        else:

            # copy non-confidential database fields from a `db.User` to this `AuthUser`.

                assert k not in ['api_keys', 'permissions']

                setattr(self, k, v)

            self.is_default_user = dbuser.is_default_user

        log.debug('Auth User is now %s', self)

    @LazyProperty

    def permissions(self):

        return self.__get_perms(user=self, cache=False)

    def has_repository_permission_level(self, repo_name, level, purpose=None):

        required_perms = {

            'read': ['repository.read', 'repository.write', 'repository.admin'],

            'write': ['repository.write', 'repository.admin'],

            'admin': ['repository.admin'],

        }[level]

        actual_perm = self.permissions['repositories'].get(repo_name)

        ok = actual_perm in required_perms

        log.debug('Checking if user %r can %r repo %r (%s): %s (has %r)',

            self.username, level, repo_name, purpose, ok, actual_perm)

        return ok

    def has_repository_group_permission_level(self, repo_group_name, level, purpose=None):

        required_perms = {

            'read': ['group.read', 'group.write', 'group.admin'],

            'write': ['group.write', 'group.admin'],

            'admin': ['group.admin'],

        }[level]

        actual_perm = self.permissions['repositories_groups'].get(repo_group_name)

        ok = actual_perm in required_perms

        log.debug('Checking if user %r can %r repo group %r (%s): %s (has %r)',

            self.username, level, repo_group_name, purpose, ok, actual_perm)

        return ok

    def has_user_group_permission_level(self, user_group_name, level, purpose=None):

        required_perms = {

            'read': ['usergroup.read', 'usergroup.write', 'usergroup.admin'],

            'write': ['usergroup.write', 'usergroup.admin'],

            'admin': ['usergroup.admin'],

        }[level]

        actual_perm = self.permissions['user_groups'].get(user_group_name)

        ok = actual_perm in required_perms

        log.debug('Checking if user %r can %r user group %r (%s): %s (has %r)',

            self.username, level, user_group_name, purpose, ok, actual_perm)

        return ok

    @property

    def api_keys(self):

        return self._get_api_keys()

    def __get_perms(self, user, cache=False):

        """

        Fills user permission attribute with permissions taken from database

        works for permissions given for repositories, and for permissions that

        are granted to groups

        :param user: `AuthUser` instance

        """

        user_id = user.user_id

        user_is_admin = user.is_admin

        log.debug('Getting PERMISSION tree')

        compute = conditional_cache('short_term', 'cache_desc',

                                    condition=cache, func=_cached_perms_data)

        return compute(user_id, user_is_admin)

    def _get_api_keys(self):

        api_keys = [self.api_key]

        for api_key in UserApiKeys.query() \

                .filter_by(user_id=self.user_id, is_expired=False):

            api_keys.append(api_key.api_key)

        return api_keys

    @property

    def is_admin(self):

        return self.admin

    @property

    def repositories_admin(self):

        """

        Returns list of repositories you're an admin of

        """

                if x[1] == 'repository.admin']

    @property

    def repository_groups_admin(self):

        """

        Returns list of repository groups you're an admin of

        """

                if x[1] == 'group.admin']

    @property

    def user_groups_admin(self):

        """

        Returns list of user groups you're an admin of

        """

                if x[1] == 'usergroup.admin']

    def __repr__(self):

        return "<%s %s: %r>" % (self.__class__.__name__, self.user_id, self.username)

    def to_cookie(self):

        """ Serializes this login session to a cookie `dict`. """

        return {

            'user_id': self.user_id,

            'is_external_auth': self.is_external_auth,

        }

    @staticmethod

    def from_cookie(cookie, ip_addr):

        """

        Deserializes an `AuthUser` from a cookie `dict` ... or return None.

        """

        return AuthUser.make(

            dbuser=UserModel().get(cookie.get('user_id')),

            is_external_auth=cookie.get('is_external_auth', False),

            ip_addr=ip_addr,

        )

    @classmethod

    def get_allowed_ips(cls, user_id, cache=False):

        _set = set()

        default_ips = UserIpMap.query().filter(UserIpMap.user_id ==

                                        User.get_default_user(cache=True).user_id)

        if cache:

            default_ips = default_ips.options(FromCache("sql_cache_short",

                                              "get_user_ips_default"))

        for ip in default_ips:

            try:

                _set.add(ip.ip_addr)

            except ObjectDeletedError:

                # since we use heavy caching sometimes it happens that we get

                # deleted objects here, we just skip them

                pass

        user_ips = UserIpMap.query().filter(UserIpMap.user_id == user_id)

        if cache:

            user_ips = user_ips.options(FromCache("sql_cache_short",

                                                  "get_user_ips_%s" % user_id))

        for ip in user_ips:

            try:

                _set.add(ip.ip_addr)

            except ObjectDeletedError:

                if head.get('copy_from') and head.get('copy_to'):

                    op = 'modified'

                    stats['binary'] = True

                    stats['ops'][COPIED_FILENODE] = ('file copied from %s to %s'

                                        % (head['copy_from'], head['copy_to']))

                # FALL BACK: detect missed old style add or remove

                if op is None:

                    if not head['a_file'] and head['b_file']:

                        op = 'added'

                        stats['binary'] = True

                        stats['ops'][NEW_FILENODE] = 'new file'

                    elif head['a_file'] and not head['b_file']:

                        op = 'removed'

                        stats['binary'] = True

                        stats['ops'][DEL_FILENODE] = 'deleted file'

                # it's not ADD not DELETE

                if op is None:

                    op = 'modified'

                    stats['binary'] = True

                    stats['ops'][MOD_FILENODE] = 'modified file'

            # a real non-binary diff

            if head['a_file'] or head['b_file']:

                chunks, added, deleted = _parse_lines(diff_lines)

                stats['binary'] = False

                stats['added'] = added

                stats['deleted'] = deleted

                # explicit mark that it's a modified file

                if op == 'modified':

                    stats['ops'][MOD_FILENODE] = 'modified file'

            else:  # Git binary patch (or empty diff)

                # Git binary patch

                if head['bin_patch']:

                    stats['ops'][BIN_FILENODE] = 'binary diff not shown'

                chunks = []

            if op == 'removed' and chunks:

                # a way of seeing deleted content could perhaps be nice - but

                # not with the current UI

                chunks = []

            chunks.insert(0, [{

                'old_lineno': '',

                'new_lineno': '',

                'action':     'context',

                'line':       msg,

                  if _op not in [MOD_FILENODE]])

            _files.append({

                'old_filename':     head['a_path'],

                'filename':         head['b_path'],

                'old_revision':     head['a_blob_id'],

                'new_revision':     head['b_blob_id'],

                'chunks':           chunks,

                'operation':        op,

                'stats':            stats,

            })

        if not inline_diff:

            return _files

        # highlight inline changes when one del is followed by one add

        for diff_data in _files:

            for chunk in diff_data['chunks']:

                lineiter = iter(chunk)

                try:

                    peekline = next(lineiter)

                    while True:

                        # find a first del line

                        while peekline['action'] != 'del':

                            peekline = next(lineiter)

                        delline = peekline

                        peekline = next(lineiter)

                        # if not followed by add, eat all following del lines

                        if peekline['action'] != 'add':

                            while peekline['action'] == 'del':

                                peekline = next(lineiter)

                            continue

                        # found an add - make sure it is the only one

                        addline = peekline

                        try:

                            peekline = next(lineiter)

                        except StopIteration:

                            # add was last line - ok

                            _highlight_inline_diff(delline, addline)

                            raise

                        if peekline['action'] != 'add':

                            # there was only one add line - ok

                            _highlight_inline_diff(delline, addline)

                except StopIteration:

                    pass

        return _files

        >>> MarkupRenderer.markdown('''<a href="foo">foo</a>''')

        u'<p><a href="foo">foo</a></p>'

        >>> MarkupRenderer.markdown('''<script>alert(1)</script>''')

        u'<script>alert(1)</script>'

        >>> MarkupRenderer.markdown('''<div onclick="alert(2)">yo</div>''')

        u'<div onclick="alert(2)">yo</div>'

        >>> MarkupRenderer.markdown('''<a href="javascript:alert(3)">yo</a>''')

        u'<p><a href="javascript:alert(3)">yo</a></p>'

        >>> MarkupRenderer.markdown('''## Foo''')

        u'<h2>Foo</h2>'

        >>> print MarkupRenderer.markdown('''

        ...     #!/bin/bash

        ...     echo "hello"

        ... ''')

        <table class="code-highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre>1

        2</pre></div></td><td class="code"><div class="code-highlight"><pre><span></span><span class="ch">#!/bin/bash</span>

        <span class="nb">echo</span> <span class="s2">&quot;hello&quot;</span>

        </pre></div>

        </td></tr></table>

        """

        source = safe_unicode(source)

        try:

            if flavored:

                source = cls._flavored_markdown(source)

            return markdown_mod.markdown(

                source,

                extensions=['markdown.extensions.codehilite', 'markdown.extensions.extra'],

                extension_configs={'markdown.extensions.codehilite': {'css_class': 'code-highlight'}})

        except Exception:

            log.error(traceback.format_exc())

            if safe:

                log.debug('Falling back to render in plain mode')

                return cls.plain(source)

            else:

                raise

    @classmethod

    def rst(cls, source, safe=True):

        source = safe_unicode(source)

        try:

            from docutils.core import publish_parts

            from docutils.parsers.rst import directives

            docutils_settings = dict([(alias, None) for alias in

                                cls.RESTRUCTUREDTEXT_DISALLOWED_DIRECTIVES])

            docutils_settings.update({'input_encoding': 'unicode',

                                      'report_level': 4})

                directives.register_directive(k, v)

            parts = publish_parts(source=source,

                                  writer_name="html4css1",

                                  settings_overrides=docutils_settings)

            return parts['html_title'] + parts["fragment"]

        except ImportError:

            log.warning('Install docutils to use this function')

            return cls.plain(source)

        except Exception:

            log.error(traceback.format_exc())

            if safe:

                log.debug('Falling back to render in plain mode')

                return cls.plain(source)

            else:

                raise

    @classmethod

    def rst_with_mentions(cls, source):

        def wrapp(match_obj):

            uname = match_obj.groups()[0]

            return r'\ **@%(uname)s**\ ' % {'uname': uname}

        mention_hl = MENTIONS_REGEX.sub(wrapp, source).strip()

        return cls.rst(mention_hl)