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

    from cubicweb.selectors import traced_selection

    with traced_selection():

        self.view('calendar', myrset)

With python 2.5, think to add:

    from __future__ import with_statement

at the top of your module.

: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

"""

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

def lltrace(selector):

    # don't wrap selectors if not in development mode

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

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

        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(%s)' % (selname, ret, vobj, vobj.__regid__)

        return ret

    traced.__name__ = selector.__name__

    traced.__doc__ = selector.__doc__

    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(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 EntitySelector or 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, **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

                    if not self.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, check

    _get_value method return one of these expected values.

    """

    def __init__(self, *expected):

        assert expected, self

        self.expected = frozenset(expected)

    def __str__(self):

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

                           ','.join(sorted(str(s) for s in self.expected)))

    @lltrace

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

        if self._get_value(cls, req, **kwargs) in self.expected:

            return 1

        return 0

    def _get_value(self, cls, req, **kwargs):

        raise NotImplementedError()

# bare selectors ##############################################################

class match_kwargs(ExpectedValueSelector):

    """Return non-zero score if parameter names specified as initializer

    arguments are specified in the input context. When multiple parameters are

    specified, all of them should be specified in the input context. Return a

    score corresponding to the number of expected parameters.

    """

    @lltrace

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

        for arg in self.expected:

            if not arg in kwargs:

                return 0

        return len(self.expected)

class appobject_selectable(Selector):

    """return 1 if another appobject is selectable using the same input context.

    Initializer arguments:

    * `registry`, a registry name

    * `regid`, an object identifier in this registry

    """

    def __init__(self, registry, regid):

        self.registry = registry

        self.regid = regid

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

        try:

            req.vreg[self.registry].select(self.regid, req, **kwargs)

            return 1

        except NoSelectableObject:

            return 0

# rset selectors ##############################################################

@objectify_selector

@lltrace

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

    """Return 1 if the result set is None (eg usually not specified)."""

    if rset is None:

        return 1

    return 0

# XXX == ~ none_rset

@objectify_selector

@lltrace

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

    """Return 1 for any result set, whatever the number of rows in it, even 0."""

    if rset is not None:

        return 1

    return 0

@objectify_selector

@lltrace

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

    """Return 1 for result set containing one ore more rows."""

    if rset is not None and rset.rowcount:

        return 1

    return 0

# XXX == ~ nonempty_rset

@objectify_selector

@lltrace

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

    """Return 1 for result set which doesn't contain any row."""

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

        return 1

    return 0

# XXX == multi_lines_rset(1)