"""This file contains some basic selectors required by application objects.

A selector is responsible to score how well an object may be used with a

given context by returning a score.

In CubicWeb Usually the context consists for a request object, a result set

or None, a specific row/col in the result set, etc...

If you have trouble with selectors, especially if the objet (typically

a view or a component) you want to use is not selected and you want to

know which one(s) of its selectors fail (e.g. returns 0), you can use

`traced_selection` or even direclty `TRACED_OIDS`.

`TRACED_OIDS` is a tuple of traced object ids. The special value

'all' may be used to log selectors for all objects.

For instance, say that the following code yields a `NoSelectableObject`

exception::

    self.view('calendar', myrset)

You can log the selectors involved for *calendar* by replacing the line

above by::

    # in Python2.5

    from cubicweb.selectors import traced_selection

    with traced_selection():

        self.view('calendar', myrset)

    # in Python2.4

    from cubicweb import selectors

    selectors.TRACED_OIDS = ('calendar',)

    self.view('calendar', myrset)

    selectors.TRACED_OIDS = ()

:organization: Logilab

:copyright: 2001-2009 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

"""

__docformat__ = "restructuredtext en"

import logging

from warnings import warn

from logilab.common.compat import all

from logilab.common.deprecation import deprecated_function

from logilab.common.interface import implements as implements_iface

from yams import BASE_TYPES

from cubicweb import (Unauthorized, NoSelectableObject, NotAnEntity,

                      role, typed_eid)

from cubicweb.vregistry import (NoSelectableObject, Selector,

                                chainall, objectify_selector)

from cubicweb.cwconfig import CubicWebConfiguration

from cubicweb.schema import split_expression

# helpers for debugging selectors

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

TRACED_OIDS = ()

def lltrace(selector):

    # don't wrap selectors if not in development mode

    if CubicWebConfiguration.mode == 'installed':

        return selector

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

        # /!\ 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

        oid = vobj.id

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

        if TRACED_OIDS == 'all' or oid in TRACED_OIDS:

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

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

        return ret

    traced.__name__ = selector.__name__

    return traced

class traced_selection(object):

    """selector debugging helper.

    Typical usage is :

    >>> with traced_selection():

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

    ...     # for all objects

    or

    >>> with traced_selection( ('oid1', 'oid2') ):

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

    ...     # for objects with id 'oid1' and 'oid2'

    """

    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 = ()

        return traceback is None

def score_interface(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 = cls_or_inst.parent_classes()

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

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):

        super(ImplementsMixIn, self).__init__()

        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, cls_or_inst, cls):

        score = 0

        vreg, eschema = cls_or_inst.vreg, cls_or_inst.e_schema

        for iface in self.expected_ifaces:

            if isinstance(iface, basestring):

                # entity type

                try:

                    iface = vreg.etype_class(iface)

                except KeyError:

                    continue # entity type not in the schema

            score += score_interface(cls_or_inst, cls, iface)

        return score

class EClassSelector(Selector):

    """abstract class for selectors working on the entity classes of the result

    set. Its __call__ method has the following behaviour:

    * if row is specified, return the score returned by the score_class method

      called with the entity class found in the specified cell

    * else return the sum of score returned by the score_class method for each

      entity type found in the specified column, unless:

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

        returned

      - `once_is_enough` is False, in which case if score_class return 0, 0 is

        returned

    """

    def __init__(self, once_is_enough=False):

        self.once_is_enough = once_is_enough

    @lltrace

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

        if not rset:

            return 0

        score = 0

        if row is None:

            for etype in rset.column_types(col):

                if etype is None: # outer join

                    continue

                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(cls.vreg.etype_class(etype), req)

    def score_class(self, eclass, req):

        raise NotImplementedError()

class EntitySelector(EClassSelector):

    """abstract class for selectors working on the entity instances of the

    result set. Its __call__ method has the following behaviour:

    * if 'entity' find in kwargs, return the score returned by the score_entity

      method for this entity

    * if row is specified, return the score returned by the score_entity method

      called with the entity instance found in the specified cell

    * else return the sum of score returned by the score_entity method for each

      entity found in the specified column, unless:

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

        returned

      - `once_is_enough` is False, in which case if score_class return 0, 0 is

        returned

    note: None values (resulting from some outer join in the query) are not

          considered.

    """

    @lltrace

    def __call__(self, cls, req, rset=None, row=None, col=0, **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

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

                if rowvalue[col] is None: # outer join

                    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()

# very basic selectors ########################################################

class yes(Selector):

    """return arbitrary score

    default score of 0.5 so any other selector take precedence

    """

    def __init__(self, score=0.5):

        self.score = score

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

        return self.score

@objectify_selector

@lltrace

def none_rset(cls, req, rset=None, **kwargs):

    """accept no result set (e.g. given rset is None)"""

    if rset is None:

        return 1

    return 0

@objectify_selector

@lltrace

def any_rset(cls, req, rset=None, **kwargs):

    """accept result set, whatever the number of result it contains"""

    if rset is not None:

        return 1

    return 0

@objectify_selector

@lltrace

def nonempty_rset(cls, req, rset=None, **kwargs):

    """accept any non empty result set"""

    if rset is not None and rset.rowcount:

        return 1

    return 0

@objectify_selector

@lltrace

def empty_rset(cls, req, rset=None, **kwargs):

    """accept empty result set"""

    if rset is not None and rset.rowcount == 0:

        return 1

    return 0

@objectify_selector

@lltrace

def one_line_rset(cls, req, rset=None, row=None, **kwargs):

    """if row is specified, accept result set with a single line of result,

    else accepts anyway

    """

    if rset is not None and (row is not None or rset.rowcount == 1):

        return 1

    return 0

@objectify_selector

@lltrace

def two_lines_rset(cls, req, rset=None, **kwargs):

    """accept result set with *at least* two lines of result"""

    if rset is not None and rset.rowcount > 1:

        return 1

    return 0

@objectify_selector

@lltrace

def two_cols_rset(cls, req, rset=None, **kwargs):

    """accept result set with at least one line and two columns of result"""

    if rset is not None and rset.rowcount and len(rset.rows[0]) > 1:

        return 1

    return 0

@objectify_selector

@lltrace

def paginated_rset(cls, req, rset=None, **kwargs):

    """accept result set with more lines than the page size.

    Page size is searched in (respecting order):

    * a page_size argument

    * a page_size form parameters

    * the navigation.page-size property

    """

    page_size = kwargs.get('page_size')

    if page_size is None:

        page_size = req.form.get('page_size')

        if page_size is None:

            page_size = req.property_value('navigation.page-size')

        else:

            page_size = int(page_size)

    if rset is None or rset.rowcount <= page_size:

        return 0

    return 1

@objectify_selector

@lltrace

def sorted_rset(cls, req, rset=None, **kwargs):

    """accept sorted result set"""

    rqlst = rset.syntax_tree()

    if len(rqlst.children) > 1 or not rqlst.children[0].orderby:

        return 0

    return 2

@objectify_selector

@lltrace

def one_etype_rset(cls, req, rset=None, col=0, **kwargs):

    """accept result set where entities in the specified column (or 0) are all

    of the same type

    """

    if rset is None:

        return 0

    if len(rset.column_types(col)) != 1:

        return 0

    return 1

@objectify_selector

@lltrace

def two_etypes_rset(cls, req, rset=None, col=0, **kwargs):

    """accept result set where entities in the specified column (or 0) are not

    of the same type

    """

    if rset:

        etypes = rset.column_types(col)

        if len(etypes) > 1:

            return 1

    return 0

class non_final_entity(EClassSelector):

    """accept if entity type found in the result set is non final.