# copyright 2003-2012 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

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

#

# This file is part of CubicWeb.

#

# CubicWeb is free software: you can redistribute it and/or modify it under the

# terms of the GNU Lesser General Public License as published by the Free

# Software Foundation, either version 2.1 of the License, or (at your option)

# any later version.

#

# CubicWeb is distributed in the hope that it will be useful, but WITHOUT

# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more

# details.

#

# You should have received a copy of the GNU Lesser General Public License along

# with CubicWeb.  If not, see <http://www.gnu.org/licenses/>.

"""

The :mod:`cubicweb.web.facet` module contains a set of abstract classes to use

as bases to build your own facets

All facet classes inherits from the :class:`AbstractFacet` class, though you'll

usually find some more handy class that do what you want.

Let's see available classes.

Classes you'll want to use

--------------------------

.. autoclass:: cubicweb.web.facet.RelationFacet

.. autoclass:: cubicweb.web.facet.RelationAttributeFacet

.. autoclass:: cubicweb.web.facet.HasRelationFacet

.. autoclass:: cubicweb.web.facet.AttributeFacet

.. autoclass:: cubicweb.web.facet.RQLPathFacet

.. autoclass:: cubicweb.web.facet.RangeFacet

.. autoclass:: cubicweb.web.facet.DateRangeFacet

.. autoclass:: cubicweb.web.facet.BitFieldFacet

.. autoclass:: cubicweb.web.facet.AbstractRangeRQLPathFacet

.. autoclass:: cubicweb.web.facet.RangeRQLPathFacet

.. autoclass:: cubicweb.web.facet.DateRangeRQLPathFacet

Classes for facets implementor

------------------------------

Unless you didn't find the class that does the job you want above, you may want

to skip those classes...

.. autoclass:: cubicweb.web.facet.AbstractFacet

.. autoclass:: cubicweb.web.facet.VocabularyFacet

.. comment: XXX widgets

"""

__docformat__ = "restructuredtext en"

_ = unicode

from functools import reduce

from warnings import warn

from copy import deepcopy

from datetime import datetime, timedelta

from logilab.mtconverter import xml_escape

from logilab.common.graph import has_path

from logilab.common.decorators import cached, cachedproperty

from logilab.common.date import datetime2ticks, ustrftime, ticks2datetime

from logilab.common.compat import all

from logilab.common.deprecation import deprecated

from logilab.common.registry import yes

from rql import nodes, utils

from cubicweb import Unauthorized

from cubicweb.schema import display_name

from cubicweb.uilib import css_em_num_value, domid

from cubicweb.utils import make_uid

from cubicweb.predicates import match_context_prop, partial_relation_possible

from cubicweb.appobject import AppObject

from cubicweb.web import RequestError, htmlwidgets

def rtype_facet_title(facet):

    if facet.cw_rset:

        ptypes = facet.cw_rset.column_types(0)

        if len(ptypes) == 1:

            return display_name(facet._cw, facet.rtype, form=facet.role,

                                context=iter(ptypes).next())

    return display_name(facet._cw, facet.rtype, form=facet.role)

def get_facet(req, facetid, select, filtered_variable):

    return req.vreg['facets'].object_by_id(facetid, req, select=select,

                                           filtered_variable=filtered_variable)

@deprecated('[3.13] filter_hiddens moved to cubicweb.web.views.facets with '

            'slightly modified prototype')

def filter_hiddens(w, baserql, **kwargs):

    from cubicweb.web.views.facets import filter_hiddens

    return filter_hiddens(w, baserql, wdgs=kwargs.pop('facets'), **kwargs)

## rqlst manipulation functions used by facets ################################

def init_facets(rset, select, mainvar=None):

    """Alters in place the <select> for filtering and returns related data.

    Calls :func:`prepare_select` to prepare the syntaxtree for selection and

    :func:`get_filtered_variable` that selects the variable to be filtered and

    drops several parts of the select tree. See each function docstring for

    details.

    :param rset: ResultSet we init facet for.

    :type rset: :class:`~cubicweb.rset.ResultSet`

    :param select: Select statement to be *altered* to support filtering.

    :type select:   :class:`~rql.stmts.Select` from the ``rset`` parameters.

    :param mainvar: Name of the variable we want to filter with facets.

    :type mainvar:  string

    :rtype: (filtered_variable, baserql) tuple.

    :return filtered_variable:  A rql class:`~rql.node.VariableRef`

                                instance as returned by

                                :func:`get_filtered_variable`.

    :return baserql: A string containing the rql before

                     :func:`prepare_select` but after

                     :func:`get_filtered_variable`.

    """

    rset.req.vreg.rqlhelper.annotate(select)

    filtered_variable = get_filtered_variable(select, mainvar)

    baserql = select.as_string(kwargs=rset.args) # before call to prepare_select

    prepare_select(select, filtered_variable)

    return filtered_variable, baserql

def get_filtered_variable(select, mainvar=None):

    """ Return the variable whose name is `mainvar`

    or the first variable selected in column 0

    """

    if mainvar is None:

        vref = select.selection[0].iget_nodes(nodes.VariableRef).next()

        return vref.variable

    return select.defined_vars[mainvar]

def prepare_select(select, filtered_variable):

    """prepare a syntax tree to generate facet filters

    * remove ORDERBY/GROUPBY clauses

    * cleanup selection (remove everything)

    * undefine unnecessary variables

    * set DISTINCT

    Notice unset of LIMIT/OFFSET us expected to be done by a previous call to

    :func:`get_filtered_variable`.

    """

    # cleanup sort terms / group by

    select.remove_sort_terms()

    select.remove_groups()

    # XXX remove aggregat from having

    # selection: only vocabulary entity

    for term in select.selection[:]:

        select.remove_selected(term)

    # remove unbound variables which only have some type restriction

    for dvar in list(select.defined_vars.itervalues()):

        if not (dvar is filtered_variable or dvar.stinfo['relations']):

            select.undefine_variable(dvar)

    # global tree config: DISTINCT, LIMIT, OFFSET

    select.set_distinct(True)

@deprecated('[3.13] use init_facets instead')

def prepare_facets_rqlst(rqlst, args=None):

    assert len(rqlst.children) == 1, 'FIXME: union not yet supported'

    select = rqlst.children[0]

    filtered_variable = get_filtered_variable(select)

    baserql = select.as_string(args)

    prepare_select(select, filtered_variable)

    return filtered_variable, baserql

def prepare_vocabulary_select(select, filtered_variable, rtype, role,

                              select_target_entity=True):

    """prepare a syntax tree to generate a filter vocabulary rql using the given

    relation:

    * create a variable to filter on this relation

    * add the relation

    * add the new variable to GROUPBY clause if necessary

    * add the new variable to the selection

    """

    newvar = _add_rtype_relation(select, filtered_variable, rtype, role)[0]

    if select_target_entity:

        # if select.groupby: XXX we remove groupby now

        #     select.add_group_var(newvar)

        select.add_selected(newvar)

    # add is restriction if necessary

    if filtered_variable.stinfo['typerel'] is None:

        etypes = frozenset(sol[filtered_variable.name] for sol in select.solutions)

        select.add_type_restriction(filtered_variable, etypes)

    return newvar

def insert_attr_select_relation(select, filtered_variable, rtype, role, attrname,

                                sortfuncname=None, sortasc=True,

                                select_target_entity=True):

    """modify a syntax tree to :

    * link a new variable to `filtered_variable` through `rtype` (where filtered_variable has `role`)

    * retrieve only the newly inserted variable and its `attrname`

    Sorting:

    * on `attrname` ascendant (`sortasc`=True) or descendant (`sortasc`=False)

    * on `sortfuncname`(`attrname`) if `sortfuncname` is specified

    * no sort if `sortasc` is None

    """

    cleanup_select(select, filtered_variable)

    var = prepare_vocabulary_select(select, filtered_variable, rtype, role,

                                   select_target_entity)

    attrvar = select.make_variable()

    select.add_relation(var, attrname, attrvar)

    # if query is grouped, we have to add the attribute variable

    #if select.groupby: XXX may not occur anymore

    #    if not attrvar in select.groupby:

    #        select.add_group_var(attrvar)

    if sortasc is not None:

        _set_orderby(select, attrvar, sortasc, sortfuncname)

    # add attribute variable to selection

    select.add_selected(attrvar)

    return var

def cleanup_select(select, filtered_variable):

    """cleanup tree from unnecessary restrictions:

    * attribute selection

    * optional relations linked to the main variable

    * mandatory relations linked to the main variable

    """

    if select.where is None:

        return

    schema = select.root.schema

    toremove = set()

    vargraph = deepcopy(select.vargraph) # graph representing links between variable

    for rel in select.where.get_nodes(nodes.Relation):

        ovar = _may_be_removed(rel, schema, filtered_variable)

        if ovar is not None:

            toremove.add(ovar)

    removed = set()

    while toremove:

        trvar = toremove.pop()

        trvarname = trvar.name

        # remove paths using this variable from the graph

        linkedvars = vargraph.pop(trvarname)

        for ovarname in linkedvars:

            vargraph[ovarname].remove(trvarname)

        # remove relation using this variable

        for rel in trvar.stinfo['relations']:

            if rel in removed:

                # already removed

                continue

            select.remove_node(rel)

            removed.add(rel)

        rel = trvar.stinfo['typerel']

        if rel is not None and not rel in removed:

            select.remove_node(rel)

            removed.add(rel)

        # cleanup groupby clause

        if select.groupby:

            for vref in select.groupby[:]:

                if vref.name == trvarname:

                    select.remove_group_var(vref)

        # we can also remove all variables which are linked to this variable

        # and have no path to the main variable

        for ovarname in linkedvars:

            if ovarname == filtered_variable.name:

                continue

            if not has_path(vargraph, ovarname, filtered_variable.name):

                toremove.add(select.defined_vars[ovarname])

def _may_be_removed(rel, schema, variable):

    """if the given relation may be removed from the tree, return the variable

    on the other side of `variable`, else return None

    Conditions:

    * the relation is an attribute selection of the main variable

    * the relation is optional relation linked to the main variable

    * the relation is a mandatory relation linked to the main variable

      without any restriction on the other variable

    """

    lhs, rhs = rel.get_variable_parts()

    rschema = schema.rschema(rel.r_type)

    if lhs.variable is variable:

        try:

            ovar = rhs.variable

        except AttributeError:

            # constant restriction

            # XXX: X title LOWER(T) if it makes sense?

            return None

        if rschema.final:

            if len(ovar.stinfo['relations']) == 1 \

                   and not ovar.stinfo.get('having'):

                # attribute selection

                return ovar

            return None

        opt = 'right'

        cardidx = 0

    elif getattr(rhs, 'variable', None) is variable:

        ovar = lhs.variable

        opt = 'left'

        cardidx = 1

    else:

        # not directly linked to the main variable

        return None

    if rel.optional in (opt, 'both'):

        # optional relation

        return ovar

    if all(rdef.cardinality[cardidx] in '1+'

           for rdef in rschema.rdefs.itervalues()):

        # mandatory relation without any restriction on the other variable

        for orel in ovar.stinfo['relations']:

            if rel is orel:

                continue

            if _may_be_removed(orel, schema, ovar) is None:

                return None

        return ovar

    return None

def _make_relation(select, variable, rtype, role):

    newvar = select.make_variable()

    if role == 'object':

        rel = nodes.make_relation(newvar, rtype, (variable,), nodes.VariableRef)

    else:

        rel = nodes.make_relation(variable, rtype, (newvar,), nodes.VariableRef)

    return newvar, rel

def _add_rtype_relation(select, variable, rtype, role):

    """add a relation relying `variable` to entities linked by the `rtype`

    relation (where `variable` has `role`)

    return the inserted variable for linked entities.

    """

    newvar, newrel = _make_relation(select, variable, rtype, role)

    select.add_restriction(newrel)

    return newvar, newrel

def _remove_relation(select, rel, var):

    """remove a constraint relation from the syntax tree"""

    # remove the relation

    select.remove_node(rel)

    # remove relations where the filtered variable appears on the

    # lhs and rhs is a constant restriction

    extra = []

    for vrel in var.stinfo['relations']:

        if vrel is rel:

            continue

        if vrel.children[0].variable is var:

            if not vrel.children[1].get_nodes(nodes.Constant):

                extra.append(vrel)

            select.remove_node(vrel)

    return extra

def _set_orderby(select, newvar, sortasc, sortfuncname):

    if sortfuncname is None:

        select.add_sort_var(newvar, sortasc)

    else:

        vref = nodes.variable_ref(newvar)

        vref.register_reference()

        sortfunc = nodes.Function(sortfuncname)

        sortfunc.append(vref)

        term = nodes.SortTerm(sortfunc, sortasc)

        select.add_sort_term(term)

def _get_var(select, varname, varmap):

    try:

        return varmap[varname]

    except KeyError:

        varmap[varname] = var = select.make_variable()

        return var

_prepare_vocabulary_rqlst = deprecated('[3.13] renamed prepare_vocabulary_select')(

    prepare_vocabulary_select)

_cleanup_rqlst = deprecated('[3.13] renamed to cleanup_select')(cleanup_select)

## base facet classes ##########################################################

class AbstractFacet(AppObject):

    """Abstract base class for all facets. Facets are stored in their own

    'facets' registry. They are similar to contextual components since the use

    the following configurable properties:

    * `visible`, boolean flag telling if a facet should be displayed or not

    * `order`, integer to control facets display order

    * `context`, telling if a facet should be displayed in the table form filter

      (context = 'tablefilter') or in the facet box (context = 'facetbox') or in

      both (context = '')

    The following methods define the facet API:

    .. automethod:: cubicweb.web.facet.AbstractFacet.get_widget

    .. automethod:: cubicweb.web.facet.AbstractFacet.add_rql_restrictions

    Facets will have the following attributes set (beside the standard

    :class:`~cubicweb.appobject.AppObject` ones):