# :organization: Logilab

# :copyright: 2001-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

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

# :license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

""".. _Selectors:

Selectors

---------

Using and combining existant selectors

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

You can combine selectors using the `&`, `|` and `~` operators.

When two selectors are combined using the `&` operator, it means that

both should return a positive score. On success, the sum of scores is

returned.

When two selectors are combined using the `|` operator, it means that

one of them should return a positive score. On success, the first

positive score is returned.

You can also "negate" a selector by precedeing it by the `~` unary operator.

Of course you can use parenthesis to balance expressions.

Example

~~~~~~~

The goal: when on a blog, one wants the RSS link to refer to blog entries, not to

the blog entity itself.

To do that, one defines a method on entity classes that returns the

RSS stream url for a given entity. The default implementation on

:class:`~cubicweb.entities.AnyEntity` (the generic entity class used

as base for all others) and a specific implementation on `Blog` will

do what we want.

But when we have a result set containing several `Blog` entities (or

different entities), we don't know on which entity to call the

aforementioned method. In this case, we keep the generic behaviour.

Hence we have two cases here, one for a single-entity rsets, the other for

multi-entities rsets.

In web/views/boxes.py lies the RSSIconBox class. Look at its selector:

.. sourcecode:: python

  class RSSIconBox(ExtResourcesBoxTemplate):

    ''' just display the RSS icon on uniform result set '''

    __select__ = ExtResourcesBoxTemplate.__select__ & non_final_entity()

It takes into account:

* the inherited selection criteria (one has to look them up in the class

  hierarchy to know the details)

* :class:`~cubicweb.selectors.non_final_entity`, which filters on result sets

  containing non final entities (a 'final entity' being synonym for entity

  attributes type, eg `String`, `Int`, etc)

This matches our second case. Hence we have to provide a specific component for

the first case:

.. sourcecode:: python

  class EntityRSSIconBox(RSSIconBox):

    '''just display the RSS icon on uniform result set for a single entity'''

    __select__ = RSSIconBox.__select__ & one_line_rset()

Here, one adds the :class:`~cubicweb.selectors.one_line_rset` selector, which

filters result sets of size 1. Thus, on a result set containing multiple

entities, :class:`one_line_rset` makes the EntityRSSIconBox class non

selectable. However for a result set with one entity, the `EntityRSSIconBox`

class will have a higher score than `RSSIconBox`, which is what we wanted.

Of course, once this is done, you have to:

* fill in the call method of `EntityRSSIconBox`

* provide the default implementation of the method returning the RSS stream url

  on :class:`~cubicweb.entities.AnyEntity`

* redefine this method on `Blog`.

When to use selectors?

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

Selectors are to be used whenever arises the need of dispatching on the shape or

content of a result set or whatever else context (value in request form params,

authenticated user groups, etc...). That is, almost all the time.

Here is a quick example:

.. sourcecode:: python

    class UserLink(component.Component):

	'''if the user is the anonymous user, build a link to login else a link

	to the connected user object with a loggout link

	'''

	__regid__ = 'loggeduserlink'

	def call(self):

	    if self._cw.cnx.anonymous_connection:

		# display login link

		...

	    else:

		# display a link to the connected user object with a loggout link

		...

The proper way to implement this with |cubicweb| is two have two different

classes sharing the same identifier but with different selectors so you'll get

the correct one according to the context.

.. sourcecode:: python

    class UserLink(component.Component):

	'''display a link to the connected user object with a loggout link'''

	__regid__ = 'loggeduserlink'

	__select__ = component.Component.__select__ & authenticated_user()

	def call(self):

            # display useractions and siteactions

	    ...

    class AnonUserLink(component.Component):

	'''build a link to login'''

	__regid__ = 'loggeduserlink'

	__select__ = component.Component.__select__ & anonymous_user()

	def call(self):

	    # display login link

            ...

The big advantage, aside readability once you're familiar with the

system, is that your cube becomes much more easily customizable by

improving componentization.

.. _CustomSelectors:

Defining your own selectors

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

.. autodocstring:: cubicweb.appobject::objectify_selector

In other cases, you can take a look at the following abstract base classes:

.. autoclass:: cubicweb.selectors.ExpectedValueSelector

.. autoclass:: cubicweb.selectors.EClassSelector

.. autoclass:: cubicweb.selectors.EntitySelector

Also, think to use the :func:`lltrace` decorator on your selector class' :meth:`__call__` method

or below the :func:`objectify_selector` decorator of your selector function so it gets

traceable when :class:`traced_selection` is activated (see :ref:`DebuggingSelectors`).

.. autofunction:: cubicweb.selectors.lltrace

.. note::

  Selectors __call__ should *always* return a positive integer, and shall never

  return `None`.

.. _DebuggingSelectors:

Debugging selection

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

Once in a while, one needs to understand why a view (or any application object)

is, or is not selected appropriately. Looking at which selectors fired (or did

not) is the way. The :class:`cubicweb.selectors.traced_selection` context

manager to help with that, *if you're running your instance in debug mode*.

.. autoclass:: cubicweb.selectors.traced_selection

.. |cubicweb| replace:: *CubicWeb*

"""

__docformat__ = "restructuredtext en"

import logging

from warnings import warn

from logilab.common.deprecation import class_renamed

from logilab.common.compat import all, any

from logilab.common.interface import implements as implements_iface

from yams import BASE_TYPES

from cubicweb import Unauthorized, NoSelectableObject, NotAnEntity, role

# even if not used, let yes here so it's importable through this module

from cubicweb.appobject import Selector, objectify_selector, yes

from cubicweb.vregistry import class_regid

from cubicweb.cwconfig import CubicWebConfiguration

from cubicweb.schema import split_expression

# helpers for debugging selectors

SELECTOR_LOGGER = logging.getLogger('cubicweb.selectors')

TRACED_OIDS = None

def _trace_selector(cls, selector, args, ret):

    # /!\ lltrace decorates pure function or __call__ method, this

    #     means argument order may be different

    if isinstance(cls, Selector):

        selname = str(cls)

        vobj = args[0]

    else:

        selname = selector.__name__

        vobj = cls

    if TRACED_OIDS == 'all' or class_regid(vobj) in TRACED_OIDS:

        #SELECTOR_LOGGER.warning('selector %s returned %s for %s', selname, ret, cls)

        print '%s -> %s for %s(%s)' % (selname, ret, vobj, vobj.__regid__)

def lltrace(selector):

    """use this decorator on your selectors so the becomes traceable with

    :class:`traced_selection`

    """

    # don't wrap selectors if not in development mode

    if CubicWebConfiguration.mode == 'system': # XXX config.debug

        return selector

    def traced(cls, *args, **kwargs):

        ret = selector(cls, *args, **kwargs)

        if TRACED_OIDS is not None:

            _trace_selector(cls, selector, args, ret)

        return ret

    traced.__name__ = selector.__name__

    traced.__doc__ = selector.__doc__

    return traced

class traced_selection(object):

    """

    Typical usage is :

    .. sourcecode:: python

        >>> from cubicweb.selectors import traced_selection

        >>> with traced_selection():

        ...     # some code in which you want to debug selectors

        ...     # for all objects

    Don't forget the 'from __future__ import with_statement' at the module top-level

    if you're using python prior to 2.6.

    This will yield lines like this in the logs::

        selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>

    You can also give to :class:`traced_selection` the identifiers of objects on

    which you want to debug selection ('oid1' and 'oid2' in the example above).

    .. sourcecode:: python

        >>> with traced_selection( ('regid1', 'regid2') ):

        ...     # some code in which you want to debug selectors

        ...     # for objects with __regid__ 'regid1' and 'regid2'

    A potentially usefull point to set up such a tracing function is

    the `cubicweb.vregistry.Registry.select` method body.

    """

    def __init__(self, traced='all'):

        self.traced = traced

    def __enter__(self):

        global TRACED_OIDS

        TRACED_OIDS = self.traced

    def __exit__(self, exctype, exc, traceback):

        global TRACED_OIDS

        TRACED_OIDS = None

        return traceback is None

def score_interface(etypesreg, cls_or_inst, cls, iface):

    """Return XXX if the give object (maybe an instance or class) implements

    the interface.

    """

    if getattr(iface, '__registry__', None) == 'etypes':

        # adjust score if the interface is an entity class

        parents = etypesreg.parent_classes(cls_or_inst.__regid__)

        if iface is cls:

            return len(parents) + 4

        if iface is parents[-1]: # Any

            return 1

        for index, basecls in enumerate(reversed(parents[:-1])):

            if iface is basecls:

                return index + 3

        return 0

    if implements_iface(cls_or_inst, iface):

        # implenting an interface takes precedence other special Any interface

        return 2

    return 0

# abstract selectors / mixin helpers ###########################################

class PartialSelectorMixIn(object):

    """convenience mix-in for selectors that will look into the containing

    class to find missing information.

    cf. `cubicweb.web.action.LinkToEntityAction` for instance

    """

    def __call__(self, cls, *args, **kwargs):

        self.complete(cls)

        return super(PartialSelectorMixIn, self).__call__(cls, *args, **kwargs)

class ImplementsMixIn(object):

    """mix-in class for selectors checking implemented interfaces of something

    """

    def __init__(self, *expected_ifaces, **kwargs):

        super(ImplementsMixIn, self).__init__(**kwargs)

        self.expected_ifaces = expected_ifaces

    def __str__(self):

        return '%s(%s)' % (self.__class__.__name__,

                           ','.join(str(s) for s in self.expected_ifaces))

    def score_interfaces(self, req, cls_or_inst, cls):

        score = 0

        etypesreg = req.vreg['etypes']

        for iface in self.expected_ifaces:

            if isinstance(iface, basestring):

                # entity type

                try:

                    iface = etypesreg.etype_class(iface)

                except KeyError:

                    continue # entity type not in the schema

            score += score_interface(etypesreg, cls_or_inst, cls, iface)

        return score

class EClassSelector(Selector):

    """abstract class for selectors working on *entity class(es)* specified

    explicitly or found of the result set.

    Here are entity lookup / scoring rules:

    * if `entity` is specified, return score for this entity's class

    * elif `row` is specified, return score for the class of the entity

      found in the specified cell, using column specified by `col` or 0

    * else return the sum of scores for each entity class found in the column

      specified specified by the `col` argument or in column 0 if not specified,

      unless:

      - `once_is_enough` is False (the default) and some entity class is scored

        to 0, in which case 0 is returned

      - `once_is_enough` is True, in which case the first non-zero score is

        returned

      - `accept_none` is False and some cell in the column has a None value

        (this may occurs with outer join)

    """

    def __init__(self, once_is_enough=False, accept_none=True):

        self.once_is_enough = once_is_enough

        self.accept_none = accept_none

    @lltrace

    def __call__(self, cls, req, rset=None, row=None, col=0, **kwargs):

        if kwargs.get('entity'):

            return self.score_class(kwargs['entity'].__class__, req)

        if not rset:

            return 0

        score = 0

        if row is None:

            if not self.accept_none:

                if any(rset[i][col] is None for i in xrange(len(rset))):

                    return 0

            for etype in rset.column_types(col):

                if etype is None: # outer join

                    return 0

                escore = self.score(cls, req, etype)

                if not escore and not self.once_is_enough:

                    return 0

                elif self.once_is_enough:

                    return escore

                score += escore

        else:

            etype = rset.description[row][col]

            if etype is not None:

                score = self.score(cls, req, etype)

        return score

    def score(self, cls, req, etype):

        if etype in BASE_TYPES:

            return 0

        return self.score_class(req.vreg['etypes'].etype_class(etype), req)

    def score_class(self, eclass, req):

        raise NotImplementedError()

class EntitySelector(EClassSelector):

    """abstract class for selectors working on *entity instance(s)* specified

    explicitly or found of the result set.

    Here are entity lookup / scoring rules:

    * if `entity` is specified, return score for this entity

    * elif `row` is specified, return score for the entity found in the

      specified cell, using column specified by `col` or 0

    * else return the sum of scores for each entity found in the column

      specified specified by the `col` argument or in column 0 if not specified,

      unless:

      - `once_is_enough` is False (the default) and some entity is scored

        to 0, in which case 0 is returned

      - `once_is_enough` is True, in which case the first non-zero score is

        returned

      - `accept_none` is False and some cell in the column has a None value

        (this may occurs with outer join)

    .. Note::

       using :class:`EntitySelector` or :class:`EClassSelector` as base selector

       class impacts performance, since when no entity or row is specified the

       later works on every different *entity class* found in the result set,

       while the former works on each *entity* (eg each row of the result set),

       which may be much more costly.

    """