"""Base class for entity objects manipulated in clients

:organization: Logilab

:copyright: 2001-2009 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.

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

:license: GNU Lesser General Public License, v2.1 - http://www.gnu.org/licenses

"""

__docformat__ = "restructuredtext en"

from warnings import warn

from logilab.common import interface

from logilab.common.compat import all

from logilab.common.decorators import cached

from logilab.common.deprecation import deprecated

from logilab.mtconverter import TransformData, TransformError, xml_escape

from rql import parse

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.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, dict):

    """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':

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

            else:

                attr = 'reverse_%s' % rschema.type

                setattr(cls, attr, ObjectRelation(rschema))

        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)

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

                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

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

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

        dict.__init__(self)

        self._related_cache = {}

        if rset is not None:

            self.eid = rset[row][col]

        else:

            self.eid = None

        self._is_saved = True

    def __repr__(self):

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

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

    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 pre_add_hook(self):

        """hook called by the repository before doing anything to add the entity

        (before_add entity hooks have not been called yet). This give the

        occasion to do weird stuff such as autocast (File -> Image for instance).

        This method must return the actual entity to be added.

        """

        return self

    def set_eid(self, eid):

        self.eid = self['eid'] = eid

    def has_eid(self):

        """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 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._is_saved

    @cached

    def metainformation(self):

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

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

        return res

    def clear_local_perm_cache(self, action):

        for rqlexpr in self.e_schema.get_rqlexprs(action):

            self._cw.local_perm_cache.pop((rqlexpr.eid, (('x', self.eid),)), None)

    def check_perm(self, action):

        self.e_schema.check_perm(self._cw, action, eid=self.eid)

    def has_perm(self, action):

        return self.e_schema.has_perm(self._cw, action, eid=self.eid)

    def view(self, vid, __registry='views', **kwargs):

        """shortcut to apply a view on this entity"""

        view = self._cw.vreg[__registry].select(vid, self._cw, rset=self.cw_rset,

                                                row=self.cw_row, col=self.cw_col,

                                                **kwargs)

        return view.render(row=self.cw_row, col=self.cw_col, **kwargs)

    def absolute_url(self, *args, **kwargs):

        """return an absolute url to view this entity"""

        # use *args since we don't want first argument to be "anonymous" to

        # avoid potential clash with kwargs

        if args:

            assert len(args) == 1, 'only 0 or 1 non-named-argument expected'

            method = args[0]

        else:

            method = None

        # in linksearch mode, we don't want external urls else selecting

        # the object for use in the relation is tricky

        # XXX search_state is web specific

        if getattr(self._cw, 'search_state', ('normal',))[0] == 'normal':

            kwargs['base_url'] = self.metainformation()['source'].get('base-url')

        if method in (None, 'view'):

            try:

                kwargs['_restpath'] = self.rest_path(kwargs.get('base_url'))

            except TypeError:

                warn('[3.4] %s: rest_path() now take use_ext_eid argument, '

                     'please update' % self.__regid__, DeprecationWarning)

                kwargs['_restpath'] = self.rest_path()

        else:

            kwargs['rql'] = 'Any X WHERE X eid %s' % self.eid

        return self._cw.build_url(method, **kwargs)

    def rest_path(self, use_ext_eid=False):

        """returns a REST-like (relative) path for this entity"""

        mainattr, needcheck = self._rest_attr_info()

        etype = str(self.e_schema)

        path = etype.lower()

        if mainattr != 'eid':

            value = getattr(self, mainattr)

            if value is None or unicode(value) == u'':

                mainattr = 'eid'

                path += '/eid'

            elif needcheck:

                # make sure url is not ambiguous

                rql = 'Any COUNT(X) WHERE X is %s, X %s %%(value)s' % (

                    etype, mainattr)

                nbresults = self._cw.execute(rql, {'value' : value})[0][0]

                if nbresults != 1: # ambiguity?

                    mainattr = 'eid'

                    path += '/eid'

        if mainattr == 'eid':

            if use_ext_eid:

                value = self.metainformation()['extid']

            else:

                value = self.eid

        return '%s/%s' % (path, self._cw.url_quote(value))

    def attr_metadata(self, attr, metadata):

        """return a metadata for an attribute (None if unspecified)"""

        value = getattr(self, '%s_%s' % (attr, metadata), None)

        if value is None and metadata == 'encoding':

            value = self._cw.vreg.property_value('ui.encoding')

        return value

    def printable_value(self, attr, value=_marker, attrtype=None,

                        format='text/html', displaytime=True):

        """return a displayable value (i.e. unicode string) which may contains

        html tags

        """

        attr = str(attr)

        if value is _marker:

            value = getattr(self, attr)

        if isinstance(value, basestring):

            value = value.strip()

        if value is None or value == '': # don't use "not", 0 is an acceptable value

            return u''

        if attrtype is None:

            attrtype = self.e_schema.destination(attr)

        props = self.e_schema.rdef(attr)

        if attrtype == 'String':

            # internalinalized *and* formatted string such as schema

            # description...

            if props.internationalizable:

                value = self._cw._(value)

            attrformat = self.attr_metadata(attr, 'format')

            if attrformat:

                return self.mtc_transform(value, attrformat, format,

                                          self._cw.encoding)

        elif attrtype == 'Bytes':

            attrformat = self.attr_metadata(attr, 'format')

            if attrformat:

                encoding = self.attr_metadata(attr, 'encoding')

                return self.mtc_transform(value.getvalue(), attrformat, format,

                                          encoding)

            return u''

        value = printable_value(self._cw, attrtype, value, props,

                                displaytime=displaytime)

        if format == 'text/html':

            value = xml_escape(value)

        return value

    def mtc_transform(self, data, format, target_format, encoding,