"""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), all rights reserved.

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

"""

__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, role

from cubicweb.vregistry import (NoSelectableObject, Selector,

                                chainall, chainfirst, objectify_selector)

from cubicweb.cwvreg import DummyCursorError

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 = cls.__class__.__name__

            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 'selector %s returned %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

# abstract selectors ##########################################################

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, 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 and (score + 1)

    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 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, row=None, col=0, **kwargs):

        if not rset:

            return 0

        score = 0

        if row is None:

            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:

            etype = rset.description[row][col]

            if etype is not None: # outer join

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

        return score and (score + 1)

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

@objectify_selector

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

    """accept everything"""

    return 1

@objectify_selector

@lltrace

def none_rset(cls, req, rset, *args, **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, *args, **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, *args, **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, *args, **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, row=None, *args, **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, *args, **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, *args, **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, *args, **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, row=None, col=0, **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, row=None, col=0, *args, **kwargs):

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

    of the same type

    """

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

        return 0

    return 1

@objectify_selector

@lltrace

def two_etypes_rset(cls, req, rset, row=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.

    See `EClassSelector` documentation for behaviour when row is not specified.

    """

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

        if etype in BASE_TYPES:

            return 0

        return 1

@objectify_selector

@lltrace

def anonymous_user(cls, req, *args, **kwargs):

    """accept if user is anonymous"""

    if req.cnx.anonymous_connection:

        return 1

    return 0

@objectify_selector

@lltrace

def authenticated_user(cls, req, *args, **kwargs):

    """accept if user is authenticated"""

    return not anonymous_user()(cls, req, *args, **kwargs)

@objectify_selector

@lltrace

def primary_view(cls, req, rset, row=None, col=0, view=None, **kwargs):

    """accept if view given as named argument is a primary view, or if no view

    is given

    """

    if view is not None and not view.is_primary():

        return 0

    return 1

@objectify_selector

@lltrace

def match_context_prop(cls, req, rset, row=None, col=0, context=None,

                       **kwargs):

    """accept if:

    * no context given

    * context (`basestring`) is matching the context property value for the

      given cls

    """

    propval = req.property_value('%s.%s.context' % (cls.__registry__, cls.id))

    if not propval:

        propval = cls.context

    if context is not None and propval and context != propval:

        return 0

    return 1

class match_search_state(Selector):

    """accept if the current request search state is in one of the expected

    states given to the initializer

    :param expected: either 'normal' or 'linksearch' (eg searching for an

                     object to create a relation with another)

    """

    def __init__(self, *expected):

        self.expected = frozenset(expected)

    @lltrace

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

        try:

            if not req.search_state[0] in self.expected:

                return 0

        except AttributeError:

            return 1 # class doesn't care about search state, accept it

        return 1

class match_form_params(match_search_state):

    """accept if parameters specified as initializer arguments are specified

    in request's form parameters

    :param *expected: parameters (eg `basestring`) which are expected to be

                      found in request's form parameters

    """