# copyright 2003-2011 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/>.

""".. _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(box.Box):

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

    __select__ = box.Box.__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 logout link

	'''

	__regid__ = 'loggeduserlink'

	def call(self):

	    if self._cw.session.anonymous_session:

		# 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.appobject.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.appobject.traced_selection` context

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

.. autoclass:: cubicweb.appobject.traced_selection

"""

__docformat__ = "restructuredtext en"

import logging

from warnings import warn

from operator import eq

from logilab.common.deprecation import class_renamed, deprecated

from logilab.common.compat import all, any

from logilab.common.interface import implements as implements_iface

from yams.schema import BASE_TYPES, role_name

from rql.nodes import Function

from cubicweb import (Unauthorized, NoSelectableObject, NotAnEntity,

                      CW_EVENT_MANAGER, role)

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

from cubicweb.uilib import eid_param

from cubicweb.appobject import Selector, objectify_selector, lltrace, yes

from cubicweb.schema import split_expression

from cubicweb.appobject import traced_selection # XXX for bw compat

def score_interface(etypesreg, eclass, 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, any = etypesreg.parent_classes(eclass.__regid__)

        if iface is eclass:

            return len(parents) + 4

        if iface is any: # Any

            return 1

        for index, basecls in enumerate(reversed(parents)):

            if iface is basecls:

                return index + 3

        return 0

    # XXX iface in implements deprecated in 3.9

    if implements_iface(eclass, iface):

        # implementing 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 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 `rset`, `select` and `filtered_variable` are specified, return score

      for the possible classes for variable in the given rql :class:`Select`

      node

    * elif `rset` and `row` are specified, return score for the class of the

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

    * elif `rset` is specified return score for each entity class found in the

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

      specified

    When there are several classes to be evaluated, return the sum of scores for

    each entity class unless:

      - `mode` == 'all' (the default) and some entity class is scored

        to 0, in which case 0 is returned

      - `mode` == 'any', 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=None, accept_none=True, mode='all'):

        if once_is_enough is not None:

            warn("[3.14] once_is_enough is deprecated, use mode='any'",

                 DeprecationWarning, stacklevel=2)

            if once_is_enough:

                mode = 'any'

        assert mode in ('any', 'all'), 'bad mode %s' % mode

        self.once_is_enough = mode == 'any'

        self.accept_none = accept_none

    @lltrace

    def __call__(self, cls, req, rset=None, row=None, col=0, entity=None,

                 select=None, filtered_variable=None,

                 accept_none=None,

                 **kwargs):

        if entity is not None:

            return self.score_class(entity.__class__, req)

        if not rset:

            return 0

        if select is not None and filtered_variable is not None:

            etypes = set(sol[filtered_variable.name] for sol in select.solutions)

        elif row is None:

            if accept_none is None:

                accept_none = self.accept_none

            if not accept_none and \

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

                return 0

            etypes = rset.column_types(col)

        else:

            etype = rset.description[row][col]

            # may have None in rset.description on outer join

            if etype is None or rset.rows[row][col] is None:

                return 0

            etypes = (etype,)

        score = 0

        for etype in etypes:

            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

        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:

      - `mode` == 'all' (the default) and some entity class is scored

        to 0, in which case 0 is returned

      - `mode` == 'any', 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.

    """

    @lltrace

    def __call__(self, cls, req, rset=None, row=None, col=0, accept_none=None,

                 **kwargs):

        if not rset and not kwargs.get('entity'):

            return 0

        score = 0

        if kwargs.get('entity'):

            score = self.score_entity(kwargs['entity'])

        elif row is None:

            col = col or 0

            if accept_none is None:

                accept_none = self.accept_none

            for row, rowvalue in enumerate(rset.rows):

                if rowvalue[col] is None: # outer join

                    if not accept_none:

                        return 0

                    continue

                escore = self.score(req, rset, row, col)

                if not escore and not self.once_is_enough:

                    return 0

                elif self.once_is_enough:

                    return escore

                score += escore

        else:

            col = col or 0

            etype = rset.description[row][col]

            if etype is not None: # outer join

                score = self.score(req, rset, row, col)

        return score

    def score(self, req, rset, row, col):

        try:

            return self.score_entity(rset.get_entity(row, col))

        except NotAnEntity:

            return 0

    def score_entity(self, entity):

        raise NotImplementedError()

class ExpectedValueSelector(Selector):

    """Take a list of expected values as initializer argument and store them

    into the :attr:`expected` set attribute. You may also give a set as single

    argument, which will then be referenced as set of expected values,

    allowing modifications to the given set to be considered.

    You should implement one of :meth:`_values_set(cls, req, **kwargs)` or

    :meth:`_get_value(cls, req, **kwargs)` method which should respectively

    return the set of values or the unique possible value for the given context.

    You may also specify a `mode` behaviour as argument, as explained below.

    Returned score is:

    - 0 if `mode` == 'all' (the default) and at least one expected

      values isn't found

    - 0 if `mode` == 'any' and no expected values isn't found at all

    - else the number of matching values