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

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'

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_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"""

        # XXX update api and implementation to AST manipulation (see unrelated rql)

        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

        # XXX not enough to be sure it'll be no conflicts

        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:

                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] += '?'

                targettypes = rschema.objects(eschema.type)

                # XXX user._cw.vreg iiiirk

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

                if len(targettypes) > 1:

                    # find fetch_attrs common to all destination types

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

                else:

                    fetchattrs = etypecls.fetch_attrs

                etypecls._fetch_restrictions(var, varmaker, fetchattrs,

                                             selection, orderby, restrictions,

                                             user, ordermethod, visited=visited)

            if ordermethod is not None:

                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(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

        for attr, value in kwargs.items():

            if attr.startswith('reverse_'):

                attr = attr[len('reverse_'):]

                role = 'object'

            else:

                role = 'subject'

            assert eschema.has_relation(attr, role), '%s %s not found on %s' % (attr, role, eschema)

            rschema = eschema.subjrels[attr] if role == 'subject' else eschema.objrels[attr]

            if not rschema.final and isinstance(value, (tuple, list, set, frozenset)):

                if len(value) == 1:

                    value = iter(value).next()

                else:

                    # prepare IN clause

                    del kwargs[attr]

                    pending_relations.append( (attr, value) )

                    continue

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

                rvar = attr.upper()

                if role == 'object':

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

                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 __cmp__(self, other):

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

    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 cw_adapt_to(self, interface):

        """return an adapter the entity to the given interface name.

        return None if it can not be adapted.

        """

        try:

            cache = self._cw_adapters_cache

        except AttributeError:

            self._cw_adapters_cache = cache = {}

        try:

            return cache[interface]

        except KeyError:

            adapter = self._cw.vreg['adapters'].select_or_none(

                interface, self._cw, entity=self)

            cache[interface] = adapter

            return adapter

    def has_eid(self): # XXX cw_has_eid

        """return True if the entity has an attributed eid (False

        meaning that the entity has to be created

        """

        try:

            typed_eid(self.eid)

            return True

        except (ValueError, TypeError):

            return False

    def cw_is_saved(self):

        """during entity creation, there is some time during which the entity

        has an eid attributed though it's not saved (eg during

        'before_add_entity' hooks). You can use this method to ensure the entity

        has an eid *and* is saved in its source.

        """

        return self.has_eid() and self._cw_is_saved

    @cached

    def cw_metainformation(self):

        res = dict(zip(('type', 'source', 'extid'), self._cw.describe(self.eid)))

        res['source'] = self._cw.source_defs()[res['source']]

        return res