# copyright 2003-2010 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 copy import copy

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 cubicweb import Unauthorized, typed_eid

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 printable_value, 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'

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_var: str

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

                    If None is specified, the first non-meta attribute will

                    be used

    :type skip_copy_for: list

    :cvar skip_copy_for: a list of relations 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 = ('in_state',)

    # 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 fetch_order(cls, attr, var):

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

        this type are fetched

        """

        return cls.fetch_unrelated_order(attr, var)

    @classmethod

    def fetch_unrelated_order(cls, attr, var):

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

        this type are fetched to use in edition (eg propose them to create a

        new relation on an edited entity).

        """

        if attr == 'modification_date':

            return '%s DESC' % var

        return None

    @classmethod

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

                  settype=True, ordermethod='fetch_order'):

        """return a rql to fetch all entities of the class type"""

        restrictions = restriction or []

        if settype:

            restrictions.append('%s is %s' % (mainvar, cls.__regid__))

        if fetchattrs is None:

            fetchattrs = cls.fetch_attrs

        selection = [mainvar]

        orderby = []

        # start from 26 to avoid possible conflicts with X

        varmaker = rqlvar_maker(index=26)

        cls._fetch_restrictions(mainvar, varmaker, fetchattrs, selection,

                                orderby, restrictions, user, ordermethod)

        rql = 'Any %s' % ','.join(selection)

        if orderby:

            rql +=  ' ORDERBY %s' % ','.join(orderby)

        rql += ' WHERE %s' % ', '.join(restrictions)

        return rql

    @classmethod

    def _fetch_restrictions(cls, mainvar, varmaker, fetchattrs,

                            selection, orderby, restrictions, 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

            var = varmaker.next()

            selection.append(var)

            restriction = '%s %s %s' % (mainvar, attr, var)

            restrictions.append(restriction)

            if not rschema.final:

                # XXX this does not handle several destination types

                desttype = rschema.objects(eschema.type)[0]

                card = rdef.cardinality[0]

                if card not in '?1':

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

                                 attr, cls)

                    selection.pop()

                    restrictions.pop()

                    continue

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

                restrictions[-1] += '?'

                # XXX user._cw.vreg iiiirk

                destcls = user._cw.vreg['etypes'].etype_class(desttype)

                destcls._fetch_restrictions(var, varmaker, destcls.fetch_attrs,

                                            selection, orderby, restrictions,

                                            user, ordermethod, visited=visited)

            orderterm = getattr(cls, ordermethod)(attr, var)

            if orderterm:

                orderby.append(orderterm)

        return selection, orderby, restrictions

    @classmethod

    @cached

    def _rest_attr_info(cls):

        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(req.execute, name=u'Logilab')

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

        ...                          works_for=c)

        """

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

        relations = []

        restrictions = set()

        pending_relations = []

        for attr, value in kwargs.items():

            if isinstance(value, (tuple, list, set, frozenset)):

                if len(value) == 1:

                    value = iter(value).next()

                else:

                    del kwargs[attr]

                    pending_relations.append( (attr, value) )

                    continue

            if hasattr(value, 'eid'): # non final relation

                rvar = attr.upper()

                # XXX safer detection of object relation

                if attr.startswith('reverse_'):

                    relations.append('%s %s X' % (rvar, attr[len('reverse_'):]))

                else:

                    relations.append('X %s %s' % (attr, rvar))

                restriction = '%s eid %%(%s)s' % (rvar, attr)

                if not restriction in restrictions:

                    restrictions.add(restriction)

                kwargs[attr] = value.eid

            else: # attribute

                relations.append('X %s %%(%s)s' % (attr, attr))

        if relations:

            rql = '%s: %s' % (rql, ', '.join(relations))

        if restrictions:

            rql = '%s WHERE %s' % (rql, ', '.join(restrictions))

        created = execute(rql, kwargs).get_entity(0, 0)

        for attr, values in pending_relations:

            if attr.startswith('reverse_'):

                restr = 'Y %s X' % attr[len('reverse_'):]

            else:

                restr = 'X %s Y' % attr

            execute('SET %s WHERE X eid %%(x)s, Y eid IN (%s)' % (

                restr, ','.join(str(r.eid) for r in values)),

                    {'x': created.eid}, build_descr=False)

        return created

    def __init__(self, req, rset=None, row=None, col=0):

        AppObject.__init__(self, req, rset=rset, row=row, col=col)

        self._cw_related_cache = {}

        if rset is not None:

            self.eid = rset[row][col]

        else:

            self.eid = None

        self._cw_is_saved = True

        self.cw_attr_cache = {}

    def __repr__(self):

        return '<Entity %s %s %s at %s>' % (

            self.e_schema, self.eid, self.cw_attr_cache.keys(), id(self))

    def __json_encode__(self):

        """custom json dumps hook to dump the entity's eid

        which is not part of dict structure itself

        """

        dumpable = dict(self)

        dumpable['eid'] = self.eid

        return dumpable

    def __nonzero__(self):

        return True

    def __hash__(self):

        return id(self)

    def __cmp__(self, other):

        raise NotImplementedError('comparison not implemented for %s' % self.__class__)

    def __contains__(self, key):

        return key in self.cw_attr_cache

    def __iter__(self):

        return iter(self.cw_attr_cache)

    def __getitem__(self, key):

        if key == 'eid':

            warn('[3.7] entity["eid"] is deprecated, use entity.eid instead',

                 DeprecationWarning, stacklevel=2)

            return self.eid

        return self.cw_attr_cache[key]

    def __setitem__(self, attr, value):

        """override __setitem__ to update self.edited_attributes.

        Typically, a before_[update|add]_hook could do::

            entity['generated_attr'] = generated_value

        and this way, edited_attributes will be updated accordingly. Also, add

        the attribute to skip_security since we don't want to check security

        for such attributes set by hooks.

        """

        if attr == 'eid':

            warn('[3.7] entity["eid"] = value is deprecated, use entity.eid = value instead',

                 DeprecationWarning, stacklevel=2)

            self.eid = value

        else:

            self.cw_attr_cache[attr] = value

            # don't add attribute into skip_security if already in edited

            # attributes, else we may accidentaly skip a desired security check

            if hasattr(self, 'edited_attributes') and \

                   attr not in self.edited_attributes:

                self.edited_attributes.add(attr)

                self._cw_skip_security_attributes.add(attr)

    def __delitem__(self, attr):

        """override __delitem__ to update self.edited_attributes on cleanup of

        undesired changes introduced in the entity's dict. For example, see the

        code snippet below from the `forge` cube:

        .. sourcecode:: python

            edited = self.entity.edited_attributes

            has_load_left = 'load_left' in edited

            if 'load' in edited and self.entity.load_left is None:

                self.entity.load_left = self.entity['load']

            elif not has_load_left and edited:

                # cleanup, this may cause undesired changes

                del self.entity['load_left']

        """

        del self.cw_attr_cache[attr]

        if hasattr(self, 'edited_attributes'):

            self.edited_attributes.remove(attr)

    def clear(self):

        self.cw_attr_cache.clear()

    def get(self, key, default=None):

        return self.cw_attr_cache.get(key, default)

    def setdefault(self, attr, default):

        """override setdefault to update self.edited_attributes"""

        self.cw_attr_cache.setdefault(attr, default)

        # don't add attribute into skip_security if already in edited