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

"""Base class for entity objects manipulated in clients"""

__docformat__ = "restructuredtext en"

from warnings import warn

from logilab.common import interface

from logilab.common.decorators import cached

from logilab.common.deprecation import deprecated

from logilab.mtconverter import TransformData, TransformError, xml_escape

from rql.utils import rqlvar_maker

from rql.stmts import Select

from rql.nodes import (Not, VariableRef, Constant, make_relation,

                       Relation as RqlRelation)

from cubicweb import Unauthorized, typed_eid, neg_role

from cubicweb.utils import support_args

from cubicweb.rset import ResultSet

from cubicweb.selectors import yes

from cubicweb.appobject import AppObject

from cubicweb.req import _check_cw_unsafe

from cubicweb.schema import RQLVocabularyConstraint, RQLConstraint

from cubicweb.rqlrewrite import RQLRewriter

from cubicweb.uilib import soup2xhtml

from cubicweb.mixins import MI_REL_TRIGGERS

from cubicweb.mttransforms import ENGINE

_marker = object()

def greater_card(rschema, subjtypes, objtypes, index):

    for subjtype in subjtypes:

        for objtype in objtypes:

            card = rschema.rdef(subjtype, objtype).cardinality[index]

            if card in '+*':

                return card

    return '1'

def can_use_rest_path(value):

    """return True if value can be used at the end of a Rest URL path"""

    if value is None:

        return False

    value = unicode(value)

    # the check for ?, /, & are to prevent problems when running

    # behind Apache mod_proxy

    if value == u'' or u'?' in value or u'/' in value or u'&' in value:

        return False

    return True

class Entity(AppObject):

    """an entity instance has e_schema automagically set on

    the class and instances has access to their issuing cursor.

    A property is set for each attribute and relation on each entity's type

    class. Becare that among attributes, 'eid' is *NEITHER* stored in the

    dict containment (which acts as a cache for other attributes dynamically

    fetched)

    :type e_schema: `cubicweb.schema.EntitySchema`

    :ivar e_schema: the entity's schema

    :type rest_attr: str

    :cvar rest_attr: indicates which attribute should be used to build REST urls

       If `None` is specified (the default), the first unique attribute will

       be used ('eid' if none found)

    :type cw_skip_copy_for: list

    :cvar cw_skip_copy_for: a list of couples (rtype, role) for each relation

       that should be skipped when copying this kind of entity. Note that some

       relations such as composite relations or relations that have '?1' as

       object cardinality are always skipped.

    """

    __registry__ = 'etypes'

    __select__ = yes()

    # class attributes that must be set in class definition

    rest_attr = None

    fetch_attrs = None

    skip_copy_for = () # bw compat (< 3.14), use cw_skip_copy_for instead

    cw_skip_copy_for = [('in_state', 'subject')]

    # class attributes set automatically at registration time

    e_schema = None

    @classmethod

    def __initialize__(cls, schema):

        """initialize a specific entity class by adding descriptors to access

        entity type's attributes and relations

        """

        etype = cls.__regid__

        assert etype != 'Any', etype

        cls.e_schema = eschema = schema.eschema(etype)

        for rschema, _ in eschema.attribute_definitions():

            if rschema.type == 'eid':

                continue

            setattr(cls, rschema.type, Attribute(rschema.type))

        mixins = []

        for rschema, _, role in eschema.relation_definitions():

            if (rschema, role) in MI_REL_TRIGGERS:

                mixin = MI_REL_TRIGGERS[(rschema, role)]

                if not (issubclass(cls, mixin) or mixin in mixins): # already mixed ?

                    mixins.append(mixin)

                for iface in getattr(mixin, '__implements__', ()):

                    if not interface.implements(cls, iface):

                        interface.extend(cls, iface)

            if role == 'subject':

                attr = rschema.type

            else:

                attr = 'reverse_%s' % rschema.type

            setattr(cls, attr, Relation(rschema, role))

        if mixins:

            # see etype class instantation in cwvreg.ETypeRegistry.etype_class method:

            # due to class dumping, cls is the generated top level class with actual

            # user class as (only) parent. Since we want to be able to override mixins

            # method from this user class, we have to take care to insert mixins after that

            # class

            #

            # note that we don't plug mixins as user class parent since it causes pb

            # with some cases of entity classes inheritance.

            mixins.insert(0, cls.__bases__[0])

            mixins += cls.__bases__[1:]

            cls.__bases__ = tuple(mixins)

            cls.info('plugged %s mixins on %s', mixins, cls)

    fetch_attrs = ('modification_date',)

    @classmethod

    def cw_fetch_order(cls, select, attr, var):

        """This class method may be used to control sort order when multiple

        entities of this type are fetched through ORM methods. Its arguments

        are:

        * `select`, the RQL syntax tree

        * `attr`, the attribute being watched

        * `var`, the variable through which this attribute's value may be

          accessed in the query

        When you want to do some sorting on the given attribute, you should

        modify the syntax tree accordingly. For instance:

        .. sourcecode:: python

          from rql import nodes

          class Version(AnyEntity):

              __regid__ = 'Version'

              fetch_attrs = ('num', 'description', 'in_state')

              @classmethod

              def cw_fetch_order(cls, select, attr, var):

                  if attr == 'num':

                      func = nodes.Function('version_sort_value')

                      func.append(nodes.variable_ref(var))

                      sterm = nodes.SortTerm(func, asc=False)

                      select.add_sort_term(sterm)

        The default implementation call

        :meth:`~cubicweb.entity.Entity.cw_fetch_unrelated_order`

        """

        cls.cw_fetch_unrelated_order(select, attr, var)

    @classmethod

    def cw_fetch_unrelated_order(cls, select, attr, var):

        """This class method may be used to control sort order when multiple entities of

        this type are fetched to use in edition (e.g. propose them to create a

        new relation on an edited entity).

        See :meth:`~cubicweb.entity.Entity.cw_fetch_unrelated_order` for a

        description of its arguments and usage.

        By default entities will be listed on their modification date descending,

        i.e. you'll get entities recently modified first.

        """

        if attr == 'modification_date':

            select.add_sort_var(var, asc=False)

    @classmethod

    def fetch_rql(cls, user, restriction=None, fetchattrs=None, mainvar='X',

                  settype=True, ordermethod='fetch_order'):

        st = cls.fetch_rqlst(user, mainvar=mainvar, fetchattrs=fetchattrs,

                             settype=settype, ordermethod=ordermethod)

        rql = st.as_string()

        if restriction:

            # cannot use RQLRewriter API to insert 'X rtype %(x)s' restriction

            warn('[3.14] fetch_rql: use of `restriction` parameter is '

                 'deprecated, please use fetch_rqlst and supply a syntax'

                 'tree with your restriction instead', DeprecationWarning)

            insert = ' WHERE ' + ','.join(restriction)

            if ' WHERE ' in rql:

                select, where = rql.split(' WHERE ', 1)

                rql = select + insert + ',' + where

            else:

                rql += insert

        return rql

    @classmethod

    def fetch_rqlst(cls, user, select=None, mainvar='X', fetchattrs=None,

                    settype=True, ordermethod='fetch_order'):

        if select is None:

            select = Select()

            mainvar = select.get_variable(mainvar)

            select.add_selected(mainvar)

        elif isinstance(mainvar, basestring):

            assert mainvar in select.defined_vars

            mainvar = select.get_variable(mainvar)

        # eases string -> syntax tree test transition: please remove once stable

        select._varmaker = rqlvar_maker(defined=select.defined_vars,

                                        aliases=select.aliases, index=26)

        if settype:

            select.add_type_restriction(mainvar, cls.__regid__)

        if fetchattrs is None:

            fetchattrs = cls.fetch_attrs

        cls._fetch_restrictions(mainvar, select, fetchattrs, user, ordermethod)

        return select

    @classmethod

    def _fetch_ambiguous_rtypes(cls, select, var, fetchattrs, subjtypes, schema):

        """find rtypes in `fetchattrs` that relate different subject etypes

        taken from (`subjtypes`) to different target etypes; these so called

        "ambiguous" relations, are added directly to the `select` syntax tree

        selection but removed from `fetchattrs` to avoid the fetch recursion

        because we have to choose only one targettype for the recursion and

        adding its own fetch attrs to the selection -when we recurse- would

        filter out the other possible target types from the result set

        """

        for attr in fetchattrs.copy():

            rschema = schema.rschema(attr)

            if rschema.final:

                continue

            ttypes = None

            for subjtype in subjtypes:

                cur_ttypes = set(rschema.objects(subjtype))

                if ttypes is None:

                    ttypes = cur_ttypes

                elif cur_ttypes != ttypes:

                    # we found an ambiguous relation: remove it from fetchattrs

                    fetchattrs.remove(attr)

                    # ... and add it to the selection

                    targetvar = select.make_variable()

                    select.add_selected(targetvar)

                    rel = make_relation(var, attr, (targetvar,), VariableRef)

                    select.add_restriction(rel)

                    break

    @classmethod

    def _fetch_restrictions(cls, mainvar, select, fetchattrs,

                            user, ordermethod='fetch_order', visited=None):

        eschema = cls.e_schema

        if visited is None:

            visited = set((eschema.type,))

        elif eschema.type in visited:

            # avoid infinite recursion

            return

        else:

            visited.add(eschema.type)

        _fetchattrs = []

        for attr in fetchattrs:

            try:

                rschema = eschema.subjrels[attr]

            except KeyError:

                cls.warning('skipping fetch_attr %s defined in %s (not found in schema)',

                            attr, cls.__regid__)

                continue

            rdef = eschema.rdef(attr)

            if not user.matching_groups(rdef.get_groups('read')):

                continue

            if rschema.final or rdef.cardinality[0] in '?1':

                var = select.make_variable()

                select.add_selected(var)

                rel = make_relation(mainvar, attr, (var,), VariableRef)

                select.add_restriction(rel)

            else:

                cls.warning('bad relation %s specified in fetch attrs for %s',

                            attr, cls)

                continue

            if not rschema.final:

                # XXX we need outer join in case the relation is not mandatory

                # (card == '?')  *or if the entity is being added*, since in

                # that case the relation may still be missing. As we miss this

                # later information here, systematically add it.

                rel.change_optional('right')

                targettypes = rschema.objects(eschema.type)

                vreg = user._cw.vreg # XXX user._cw.vreg iiiirk

                etypecls = vreg['etypes'].etype_class(targettypes[0])

                if len(targettypes) > 1:

                    # find fetch_attrs common to all destination types

                    fetchattrs = vreg['etypes'].fetch_attrs(targettypes)

                    # ... and handle ambiguous relations

                    cls._fetch_ambiguous_rtypes(select, var, fetchattrs,

                                                targettypes, vreg.schema)

                else:

                    fetchattrs = etypecls.fetch_attrs

                etypecls._fetch_restrictions(var, select, fetchattrs,

                                             user, ordermethod, visited=visited)

            if ordermethod is not None:

                try:

                    cmeth = getattr(cls, ordermethod)

                    warn('[3.14] %s %s class method should be renamed to cw_%s'

                         % (cls.__regid__, ordermethod, ordermethod),

                         DeprecationWarning)

                except AttributeError:

                    cmeth = getattr(cls, 'cw_' + ordermethod)

                if support_args(cmeth, 'select'):

                    cmeth(select, attr, var)

                else:

                    warn('[3.14] %s should now take (select, attr, var) and '

                         'modify the syntax tree when desired instead of '

                         'returning something' % cmeth, DeprecationWarning)

                    orderterm = cmeth(attr, var.name)

                    if orderterm is not None:

                        try:

                            var, order = orderterm.split()

                        except ValueError:

                            if '(' in orderterm:

                                self.error('ignore %s until %s is upgraded',

                                           orderterm, cmeth)

                                orderterm = None

                            elif not ' ' in orderterm.strip():

                                var = orderterm

                                order = 'ASC'

                        if orderterm is not None:

                            select.add_sort_var(select.get_variable(var),

                                                order=='ASC')

    @classmethod

    @cached

    def cw_rest_attr_info(cls):

        """this class method return an attribute name to be used in URL for

        entities of this type and a boolean flag telling if its value should be

        checked for uniqness.

        The attribute returned is, in order of priority:

        * class's `rest_attr` class attribute

        * an attribute defined as unique in the class'schema

        * 'eid'

        """

        mainattr, needcheck = 'eid', True

        if cls.rest_attr:

            mainattr = cls.rest_attr

            needcheck = not cls.e_schema.has_unique_values(mainattr)

        else:

            for rschema in cls.e_schema.subject_relations():

                if rschema.final and rschema != 'eid' \

                        and cls.e_schema.has_unique_values(rschema):

                    mainattr = str(rschema)

                    needcheck = False

                    break

        if mainattr == 'eid':

            needcheck = False

        return mainattr, needcheck

    @classmethod

    def cw_instantiate(cls, execute, **kwargs):

        """add a new entity of this given type

        Example (in a shell session):

        >>> companycls = vreg['etypes'].etype_class(('Company')

        >>> personcls = vreg['etypes'].etype_class(('Person')

        >>> c = companycls.cw_instantiate(session.execute, name=u'Logilab')

        >>> p = personcls.cw_instantiate(session.execute, firstname=u'John', lastname=u'Doe',

        ...                              works_for=c)

        You can also set relation where the entity has 'object' role by

        prefixing the relation by 'reverse_'.

        """

        rql = 'INSERT %s X' % cls.__regid__

        relations = []

        restrictions = set()

        pending_relations = []

        eschema = cls.e_schema

        qargs = {}

        for attr, value in kwargs.items():