"""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 result set (publishing time selection)

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.common.selectors import traced_selection

    with traced_selection():

        self.view('calendar', myrset)

    # in Python2.4

    from cubicweb.common 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 logilab.common.compat import all

from logilab.common.deprecation import deprecated_function

from cubicweb import Unauthorized, NoSelectableObject, role

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

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

        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

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

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

    """accept everything"""

    return 1

yes_selector = deprecated_function(yes)

@lltrace

def none_rset(cls, req, rset, *args, **kwargs):

    """accept no result set"""

    if rset is None:

        return 1

    return 0

norset_selector = deprecated_function(none_rset)

@lltrace

def any_rset(cls, req, rset, *args, **kwargs):

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

    if rset is not None:

        return 1

    return 0

rset_selector = deprecated_function(any_rset)

@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

anyrset_selector = deprecated_function(nonempty_rset)

@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

emptyrset_selector = deprecated_function(empty_rset)

@lltrace

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

    """accept result set with a single line of result"""

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

        return 1

    return 0

onelinerset_selector = deprecated_function(one_line_rset)

@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

twolinerset_selector = deprecated_function(two_lines_rset)

@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 > 0 and len(rset.rows[0]) > 1:

        return 1

    return 0

twocolrset_selector = deprecated_function(two_cols_rset)

@lltrace

def paginated_rset(cls, req, rset, *args, **kwargs):

    """accept result sets with more rows than the page size

    """

    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 len(rset) <= page_size:

        return 0

    return 1

largerset_selector = deprecated_function(paginated_rset)

@lltrace

    """accept sorted result set"""

    rqlst = rset.syntax_tree()

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

        return 0

    return 2

sortedrset_selector = deprecated_function(sorted_rset)

@lltrace

def one_etype_rset(cls, req, rset, *args, **kwargs):

    """accept result set where entities in the first columns are all of the

    same type

    """

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

        return 0

    return 1

oneetyperset_selector = deprecated_function(one_etype_rset)

@lltrace

def two_etypes_rset(cls, req, rset, **kwargs):

    """accepts resultsets containing several entity types"""

    if rset:

        etypes = rset.column_types(0)

        if len(etypes) > 1:

            return 1

    return 0

multitype_selector = deprecated_function(two_etypes_rset)

@lltrace

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

    """accept if user is anonymous"""

    if req.cnx.anonymous_connection:

        return 1

    return 0

anonymous_selector = deprecated_function(anonymous_user)

@lltrace

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

    """accept if user is authenticated"""

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

not_anonymous_selector = deprecated_function(authenticated_user)

@lltrace

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

    """check if parameters specified by the form_params attribute on

    the wrapped class are specified in request form parameters

    """

    score = 0

    for param in cls.form_params:

        val = req.form.get(param)

        if not val:

            return 0

        score += 1

    return score + 1

req_form_params_selector = deprecated_function(match_form_params)

@lltrace

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

    """check if arguments specified by the expected_kwargs attribute on

    the wrapped class are specified in given named parameters

    """

    values = []

    for arg in cls.expected_kwargs:

        if not arg in kwargs:

            return 0

    return 1

kwargs_selector = deprecated_function(match_kwargs)

# not so basic selectors ######################################################