"""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-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, filterwarnings

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, typed_eid)

# 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

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']

        eschema = cls_or_inst.e_schema

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

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

        returned

    """

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

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

        returned

    """

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

    """

    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

    """

    @lltrace

        for arg in self.expected:

            if not arg in kwargs:

                return 0

        return len(self.expected)

    """

        self.registry = registry

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

        try:

            return 1

        except NoSelectableObject:

            return 0