# copyright 2003-2010 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

# contact http://www.logilab.fr/ -- mailto:contact@logilab.fr

#

# This file is part of CubicWeb.

#

# CubicWeb is free software: you can redistribute it and/or modify it under the

# terms of the GNU Lesser General Public License as published by the Free

# Software Foundation, either version 2.1 of the License, or (at your option)

# any later version.

#

# CubicWeb 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 Lesser General Public License for more

# details.

#

# You should have received a copy of the GNU Lesser General Public License along

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

""".. VRegistry:

The `VRegistry`

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

The `VRegistry` can be seen as a two-level dictionary. It contains

all dynamically loaded objects (subclasses of :ref:`appobject`) to

build a |cubicweb| application. Basically:

* the first level key returns a *registry*. This key corresponds to the

  `__registry__` attribute of application object classes

* the second level key returns a list of application objects which

  share the same identifier. This key corresponds to the `__regid__`

  attribute of application object classes.

A *registry* holds a specific kind of application objects. There is

for instance a registry for entity classes, another for views, etc...

The `VRegistry` has two main responsibilities:

- being the access point to all registries

- handling the registration process at startup time, and during automatic

  reloading in debug mode.

.. _AppObjectRecording:

Details of the recording process

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

.. index::

   vregistry: registration_callback

On startup, |cubicweb| loads application objects defined in its library

and in cubes used by the instance. Application objects from the

library are loaded first, then those provided by cubes are loaded in

dependency order (e.g. if your cube depends on an other, objects from

the dependency will be loaded first). The layout of the modules or packages

in a cube  is explained in :ref:`cubelayout`.

For each module:

* by default all objects are registered automatically

* if some objects have to replace other objects, or have to be

  included only if some condition is met, you'll have to define a

  `registration_callback(vreg)` function in your module and explicitly

  register **all objects** in this module, using the api defined

  below.

.. Note::

    Once the function `registration_callback(vreg)` is implemented in a module,

    all the objects from this module have to be explicitly registered as it

    disables the automatic objects registration.

API for objects registration

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

Here are the registration methods that you can use in the `registration_callback`

to register your objects to the `VRegistry` instance given as argument (usually

named `vreg`):

.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_all

.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register_and_replace

.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.register

.. automethod:: cubicweb.cwvreg.CubicWebVRegistry.unregister

Examples:

.. sourcecode:: python

   # web/views/basecomponents.py

   def registration_callback(vreg):

      # register everything in the module except SeeAlsoComponent

      vreg.register_all(globals().values(), __name__, (SeeAlsoVComponent,))

      # conditionally register SeeAlsoVComponent

      if 'see_also' in vreg.schema:

          vreg.register(SeeAlsoVComponent)

In this example, we register all application object classes defined in the module

except `SeeAlsoVComponent`. This class is then registered only if the 'see_also'

relation type is defined in the instance'schema.

.. sourcecode:: python

   # goa/appobjects/sessions.py

   def registration_callback(vreg):

      vreg.register(SessionsCleaner)

      # replace AuthenticationManager by GAEAuthenticationManager

      vreg.register_and_replace(GAEAuthenticationManager, AuthenticationManager)

      # replace PersistentSessionManager by GAEPersistentSessionManager

      vreg.register_and_replace(GAEPersistentSessionManager, PersistentSessionManager)

In this example, we explicitly register classes one by one:

* the `SessionCleaner` class

* the `GAEAuthenticationManager` to replace the `AuthenticationManager`

* the `GAEPersistentSessionManager` to replace the `PersistentSessionManager`

If at some point we register a new appobject class in this module, it won't be

registered at all without modification to the `registration_callback`

implementation. The previous example will register it though, thanks to the call

to the `register_all` method.

.. _Selection:

Runtime objects selection

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

Now that we have all application objects loaded, the question is : when

I want some specific object, for instance the primary view for a given

entity, how do I get the proper object ? This is what we call the

**selection mechanism**.

As explained in the :ref:`Concepts` section:

* each application object has a **selector**, defined by its

  `__select__` class attribute

* this selector is responsible to return a **score** for a given context

  - 0 score means the object doesn't apply to this context

  - else, the higher the score, the better the object suits the context

* the object with the highest score is selected.

.. Note::

  When no single object has the highest score, an exception is raised in development

  mode to let you know that the engine was not able to identify the view to

  apply. This error is silenced in production mode and one of the objects with

  the highest score is picked.

  In such cases you would need to review your design and make sure

  your selectors or appobjects are properly defined. Such an error is

  typically caused by either forgetting to change the __regid__ in a

  derived class, or by having copy-pasted some code.

For instance, if you are selecting the primary (`__regid__ =

'primary'`) view (`__registry__ = 'views'`) for a result set

containing a `Card` entity, two objects will probably be selectable:

* the default primary view (`__select__ = is_instance('Any')`), meaning

  that the object is selectable for any kind of entity type

* the specific `Card` primary view (`__select__ = is_instance('Card')`,

  meaning that the object is selectable for Card entities

Other primary views specific to other entity types won't be selectable in this

case. Among selectable objects, the `is_instance('Card')` selector will return a higher

score since it's more specific, so the correct view will be selected as expected.

.. _SelectionAPI:

API for objects selections

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

Here is the selection API you'll get on every registry. Some of them, as the

'etypes' registry, containing entity classes, extend it. In those methods,

`*args, **kwargs` is what we call the **context**. Those arguments are given to

selectors that will inspect their content and return a score accordingly.

.. automethod:: cubicweb.vregistry.Registry.select

.. automethod:: cubicweb.vregistry.Registry.select_or_none

.. automethod:: cubicweb.vregistry.Registry.possible_objects

.. automethod:: cubicweb.vregistry.Registry.object_by_id

"""

__docformat__ = "restructuredtext en"

_ = unicode

from warnings import warn

from logilab.common.decorators import cached, clear_cache

from logilab.common.deprecation import  deprecated

from logilab.common.modutils import cleanup_sys_modules

from rql import RQLHelper

from cubicweb import (ETYPE_NAME_MAP, Binary, UnknownProperty, UnknownEid,

                      ObjectNotFound, NoSelectableObject, RegistryNotFound,

                      CW_EVENT_MANAGER)

from cubicweb.utils import dump_class

from cubicweb.vregistry import VRegistry, Registry, class_regid, classid

from cubicweb.rtags import RTAGS

def clear_rtag_objects():

    for rtag in RTAGS:

        rtag.clear()

def use_interfaces(obj):

    """return interfaces used by the given object by searching for implements

    selectors

    """

    from cubicweb.selectors import implements

    impl = obj.__select__.search_selector(implements)

    if impl:

        return sorted(impl.expected_ifaces)

    return ()

def require_appobject(obj):

    """return interfaces used by the given object by searching for implements

    selectors

    """

    from cubicweb.selectors import appobject_selectable

    impl = obj.__select__.search_selector(appobject_selectable)

    if impl:

        return (impl.registry, impl.regids)

    return None

class CWRegistry(Registry):

    def __init__(self, vreg):

        super(CWRegistry, self).__init__(vreg.config)

        self.vreg = vreg

    @property

    def schema(self):

        return self.vreg.schema

    @deprecated('[3.6] select object, then use obj.render()')

    def render(self, __oid, req, __fallback_oid=None, rset=None, initargs=None,

               **kwargs):

        """Select object with the given id (`__oid`) then render it.  If the

        object isn't selectable, try to select fallback object if

        `__fallback_oid` is specified.

        If specified `initargs` is expected to be a dictionnary containing

        arguments that should be given to selection (hence to object's __init__

        as well), but not to render(). Other arbitrary keyword arguments will be

        given to selection *and* to render(), and so should be handled by

        object's call or cell_call method..

        """

        if initargs is None:

            initargs = kwargs

        else:

            initargs.update(kwargs)

        try:

            obj = self.select(__oid, req, rset=rset, **initargs)

        except NoSelectableObject:

            if __fallback_oid is None:

                raise

            obj = self.select(__fallback_oid, req, rset=rset, **initargs)

        return obj.render(**kwargs)

    @deprecated('[3.6] use select_or_none and test for obj.cw_propval("visible")')

    def select_vobject(self, oid, *args, **kwargs):

        selected = self.select_or_none(oid, *args, **kwargs)

        if selected and selected.cw_propval('visible'):

            return selected

        return None

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

        """return an ordered list of possible app objects in a given registry,

        supposing they support the 'visible' and 'order' properties (as most

        visualizable objects)

        """

        return sorted([x for x in self.possible_objects(*args, **kwargs)

                       if x.cw_propval('visible')],

                      key=lambda x: x.cw_propval('order'))

    possible_vobjects = deprecated('[3.6] use poss_visible_objects()')(poss_visible_objects)

VRegistry.REGISTRY_FACTORY[None] = CWRegistry

class ETypeRegistry(CWRegistry):

    def initialization_completed(self):

        """on registration completed, clear etype_class internal cache

        """

        super(ETypeRegistry, self).initialization_completed()

        # clear etype cache if you don't want to run into deep weirdness

        clear_cache(self, 'etype_class')

        clear_cache(self, 'parent_classes')

    def register(self, obj, **kwargs):

        oid = kwargs.get('oid') or class_regid(obj)

        if oid != 'Any' and not oid in self.schema:

            self.error('don\'t register %s, %s type not defined in the '

                       'schema', obj, oid)

            return

        kwargs['clear'] = True

        super(ETypeRegistry, self).register(obj, **kwargs)

    @cached

    def parent_classes(self, etype):

        if etype == 'Any':

            return (), self.etype_class('Any')

        parents = tuple(self.etype_class(e.type)

                        for e in self.schema.eschema(etype).ancestors())

        return parents, self.etype_class('Any')

    @cached

    def etype_class(self, etype):

        """return an entity class for the given entity type.

        Try to find out a specific class for this kind of entity or default to a

        dump of the nearest parent class (in yams inheritance) registered.

        Fall back to 'Any' if not yams parent class found.

        """

        etype = str(etype)

        if etype == 'Any':

            objects = self['Any']

            assert len(objects) == 1, objects

            return objects[0]

        eschema = self.schema.eschema(etype)

        baseschemas = [eschema] + eschema.ancestors()

        # browse ancestors from most specific to most generic and try to find an

        # associated custom entity class

        for baseschema in baseschemas:

            try:

                btype = ETYPE_NAME_MAP[baseschema]

            except KeyError:

                btype = str(baseschema)

            try:

                objects = self[btype]

                assert len(objects) == 1, objects

                if btype == etype:

                    cls = objects[0]

                else:

                    # recurse to ensure issubclass(etype_class('Child'),

                    #                              etype_class('Parent'))

                    cls = self.etype_class(btype)

                break

            except ObjectNotFound:

                pass

        else:

            # no entity class for any of the ancestors, fallback to the default

            # one

            objects = self['Any']

            assert len(objects) == 1, objects

            cls = objects[0]

        # make a copy event if cls.__regid__ == etype, else we may have pb for

        # client application using multiple connections to different

        # repositories (eg shingouz)

        cls = dump_class(cls, etype)

        cls.__regid__ = etype

        cls.__initialize__(self.schema)

        return cls

VRegistry.REGISTRY_FACTORY['etypes'] = ETypeRegistry

class ViewsRegistry(CWRegistry):

    def main_template(self, req, oid='main-template', rset=None, **kwargs):

        """display query by calling the given template (default to main),

        and returning the output as a string instead of requiring the [w]rite

        method as argument

        """

        obj = self.select(oid, req, rset=rset, **kwargs)

        res = obj.render(**kwargs)

        if isinstance(res, unicode):

            return res.encode(req.encoding)

        assert isinstance(res, str)

        return res

    def possible_views(self, req, rset=None, **kwargs):

        """return an iterator on possible views for this result set

        views returned are classes, not instances

        """

        for vid, views in self.items():

            if vid[0] == '_':

                continue

            try:

                view = self._select_best(views, req, rset=rset, **kwargs)

                if view.linkable():

                    yield view

            except NoSelectableObject:

                continue

            except Exception:

                self.exception('error while trying to select %s view for %s',

                               vid, rset)

VRegistry.REGISTRY_FACTORY['views'] = ViewsRegistry

class ActionsRegistry(CWRegistry):

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

        """return an ordered list of possible actions"""

        return sorted(self.possible_objects(*args, **kwargs),

                      key=lambda x: x.order)

    def possible_actions(self, req, rset=None, **kwargs):

        if rset is None:

            actions = self.poss_visible_objects(req, rset=rset, **kwargs)

        else:

            actions = rset.possible_actions(**kwargs) # cached implementation