# copyright 2003-2011 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

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 warnings import warn

from copy import deepcopy

from datetime import date, datetime, timedelta

from logilab.mtconverter import xml_escape

from logilab.common.graph import has_path

from logilab.common.decorators import cached

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

from logilab.common.compat import all

from logilab.common.deprecation import deprecated

from rql import parse, nodes, utils

from cubicweb import Unauthorized, typed_eid

from cubicweb.schema import display_name

from cubicweb.utils import make_uid

from cubicweb.selectors import match_context_prop, partial_relation_possible, yes

from cubicweb.appobject import AppObject

from cubicweb.web import RequestError, htmlwidgets

def rtype_facet_title(facet):

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

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

    """drop any limit/offset from select (in-place modification) and return the

    variable whose name is `mainvar` or the first variable selected in column 0

    """

    select.set_limit(None)

    select.set_offset(None)

    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 select.defined_vars.values():

        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.values()):

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

    * `select`, the :class:`rql.stmts.Select` node of the rql syntax tree being

      filtered

    * `filtered_variable`, the variable node in this rql syntax tree that we're

      interested in filtering

    Facets implementors may also be interested in the following properties /