TracDev/ContextRefactoring: trac_context.py

# -*- coding: utf-8 -*-
#
# Copyright (C) 2006-2007 Edgewall Software
# Copyright (C) 2006-2007 Alec Thomas <alec@swapoff.org>
# Copyright (C) 2007 Christian Boos <cboos@neuf.fr>
# All rights reserved.
#
# This software is licensed as described in the file COPYING, which
# you should have received as part of this distribution. The terms
# are also available at http://trac.edgewall.org/wiki/TracLicense.
#
# This software consists of voluntary contributions made by many
# individuals. For the exact contribution history, see the revision
# history and logs, available at http://trac.edgewall.org/log/.
#
# Author: Christian Boos <cboos@neuf.fr>
#         Alec Thomas <alec@swapoff.org>

from trac.core import *
from trac.util.compat import reversed
from trac.util.translation import _

# TODO: rename this file to trac/resource.py

class ResourceNotFound(TracError):
    """Thrown when a non-existent resource is requested"""


class IResourceManager(Interface):

    def get_resource_realms():
        """Generate realm strings identifying the realm of resources handled
        by this component."""

    def get_model(resource):
        """Return a data model object corresponding to the given `resource`.

        NOTE: this method could also be used to clarify the model.exists
              semantic, e.g.
               - when the resource.id is None, return a new model
               - when the resource.id is not None, either return the
                 corresponding model if it exists, None otherwise.
              (currently achieving the above requires catching exceptions,
              see #4130)
        """

    def get_resource_url(resource, href, **kwargs):
        """Return the URL for the requested resource."""

    def get_resource_description(resource, format=None):
        """Return a representation of the resource, according to the `format`.

        For example, the ticket with the ID 123 is represented like `'#123'`
        for the `'compact'` format, `'Ticket #123'` for the default `None`
        format.
        With the `'summary'`format, more details about the resource will be
        given, at the expense of a lookup to the resource's model.
        """

class Resource(object):
    """Resource identifier.

    This specifies as precisely as possible *which* resource in a Trac
    system is manipulated.

    A resource is identified by:
     - a `realm` (a string like `'wiki'` or `'ticket'`)
     - an `id`, which uniquely identifies a resource within its realm.
       If the `id` information is not set, then the resource identifier
       could be used to refer to the realm as a whole.
     - an optional `version` information.
       If `version` is `None`, this refers by convention to the latest
       version of the resource.
    (- a `project` identifier) 0.12 ?
    (- a `field` identifier) 0.12 ?

    This light-weight object can be used to access:
     - the more heavy-weight `model` object encapsulating the complete data
       and application logic associated to the "resource".
     - a light-weight descriptor that can be used to have different ways to
       describe the resource in a way specific to each resource realm
    
    """

    __slots__ = ('_perm', 'realm', 'id', 'version', '_model', 'parent',
                 '_manager')

    def __init__(self, perm, realm, id, version, model, parent):
        """Create a resource identifier."""
        self._perm = perm
        self.realm = realm
        self.id = id
        self.version = version
        self._model = model
        self.parent = parent
        self._manager = None

    def __repr__(self):
        path = []
        r = self
        while r:
            name = r.realm
            if r.id:
                name += ':' + unicode(r.id) # id can be numerical
            if r.version:
                name += '@' + unicode(r.version)
            path.append(name)
            r = r.parent
        return '<Resource %r>' % (', '.join(reversed(path)))

    def __eq__(self, other):
        return self.realm == other.realm and \
               self.id == other.id and \
               self.version == other.version and \
               self.parent == other.parent

    def __contains__(self, action):
        """Convenience method for doing a permission check on the resource.

        Thus the calls:
            'WIKI_VIEW' in perm(resource)
           or
            'WIKI_VIEW' in perm(realm, id, version)

        are working as expected.
        """
        return self.perm

    def __hash__(self):
        """Hash this resource descriptor, including its hierarchy."""
        path = []
        current = self
        while current:
            path.extend((self.realm, self.id, self.version))
            current = current.parent
        return hash(tuple(path))

    env = property(lambda self: self._perm.env)
    perm = property(lambda self: self._perm.copy(self))

    def _get_model(self):
        if not self._model:
            self._model = self.manager.get_model(self)
            if not self._model:
                raise ResourceNotFound(_("Can't retrieve model for %s:%s") %
                                       (self.realm, self.id))
        return self._model

    model = property(_get_model)

    def _get_manager(self):
        if not self._manager:
            self._manager = ResourceSystem(self.env) \
                            .get_resource_manager(self.realm)
            if not self._manager:
                raise TracError(_("Can't retrieve manager for %s:%s") %
                                (self.realm, self.id))
        return self._manager

    manager = property(_get_manager)

    def url(self, href, path=None, **kwargs):
        return self.manager.get_resource_url(self, href, path, **kwargs)

    name = property(
        lambda self: self.manager.get_resource_description(self))

    shortname = property(
        lambda self: self.manager.get_resource_description(self, 'compact'))
    summary = property(
        lambda self: self.manager.get_resource_description(self, 'summary'))

    # -- methods for retrieving other Resource identifiers

    def assert_copy(self, realm=False, id=False, version=False, model=None,
                    parent=None):
        """Create a new Resource using the current resource as a template.

        Optional keyword arguments can be given to override `realm`, `id`,
        `version` and set the `model`.
        If `realm` is changed, then the original `id` and `version` values
        will not be reused.
        If `id` is changed, then the original `version` value will not be
        reused.
        In any case, the `model` value will not reused.

        This method will raise a `PermissionError` exception if there's no
        read permission for the specified resource.
        """
        return self._perm.assert_resource(*self._copy(realm, id, version,
                                                      model, parent))

    def __call__(self, realm=False, id=False, version=False, model=None,
                 parent=None):
        """Create another resource using the current resource as a template.

        Unlike `copy()`, this will return `None` instead of a `Resource` object
        if there's no read permission for the specified resource.
        """
        return self._perm(*self._copy(realm, id, version, model, parent))

    def _copy(self, realm, id, version, model, parent):
        if realm is False:  # i.e. not set
            realm = self.realm
        if realm != self.realm:
            return (realm or '', id or None, version or None, model, parent)
        else:
            if id is False:
                id = self.id or None
            if version is False:
                version = id == self.id and self.version or None
            return (realm, id, version, model, parent)

    # -- methods for retrieving children Resource identifiers
    
    def assert_child(self, realm, id=False, version=False, model=None):
        """Retrieve a child resource for a secondary `realm`.

        Same as `copy()`, except that it sets the parent to `self`.
        """
        return self._perm.assert_resource(*self._copy(realm, id, version,
                                                      model, self))

    def child(self, realm, id=False, version=False, model=None):
        """Retrieve a child resource for a secondary `realm`.

        Same as `__call__`, except that it sets the parent to `self`.
        """
        return self._perm(*self._copy(realm, id, version, model, self))
    


class ResourceSystem(Component):
    """Resource identification and description.

    This component makes the link between Resource identifiers and their
    corresponding manager component.

    It acts itself as a resource manager for resources in realms that are not
    explicitely managed.
    """

    implements = (IResourceManager,)

    resource_managers = ExtensionPoint(IResourceManager)

    def __init__(self):
        self._resource_managers_map = None

    # IResourceManager methods

    def get_resource_realms(self):
        yield ''

    def get_model(self, resource):
        return None

    def get_resource_url(self, resource, href, path=None, **kwargs):
        """Produce an URL to the `resource`, using the `href` as a base.
        
        In addition, a relative `path` can be given to refer to another
        resource within the same realm, and relative to the current resource.
        """
        if path and path[0] == '/': # absolute reference, start at project base
            return href(path.lstrip('/'), **kwargs)
        base = unicode(resource.id or '').split('/')
        for comp in (path or '').split('/'):
            if comp in ('.', ''):
                continue
            elif comp == '..':
                if base:
                    base.pop()
            else:
                base.append(comp)
        if path in (None, '', '.') and resource.version is not None \
               and 'version' not in kwargs:
            kwargs['version'] = resource.version
        return href(resource.realm, *base, **kwargs)

    def get_resource_description(self, resource, format=None, **kwargs):
        """Return a representation of the resource.

        Typical formats are: `None` (default), `'compact'` or `'summary'`.

        For example, the ticket with the ID 123 is represented like `'#123'`
        in compact mode, `'Ticket #123'` in default mode and adds much more
        ticket state information to this in summary mode.
        """
        name = '%s:%s' % (resource.realm, resource.id)
        if format == 'summary':
            name += ' at version %s' % resource.version
        return name

    # Public methods

    def get_resource_manager(self, realm):
        """Return the `ResourceManager` responsible for the given `realm`.

        If there's no corresponding realm, this will be the `ResourceSystem`
        itself.
        """
        # build a dict of realm keys to IResourceManager implementations
        if not self._resource_managers_map:
            map = {}
            for manager in self.resource_managers:
                for manager_realm in manager.get_resource_realms():
                    map[manager_realm] = manager
            self._resource_managers_map = map
        return self._resource_managers_map.get(realm, self)

    def get_known_realms(self):
        """Return a list of all the realm names of resource managers."""
        realms = []
        for manager in self.resource_managers:
            for realm in manager.get_resource_realms():
                realms.append(realm)
        return realms