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

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.common.uilib import printable_value, soup2xhtml

from cubicweb.common.mixins import MI_REL_TRIGGERS

from cubicweb.common.mttransforms import ENGINE

_marker = object()

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

    for subjtype in subjtypes:

        for objtype in objtypes:

            card = rschema.rproperty(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

    """

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

            cls.__bases__ = tuple(mixins + [p for p in cls.__bases__ if not p is object])

            cls.debug('plugged %s mixins on %s', mixins, etype)

    @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.subject_relation(attr)

            except KeyError:

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

                            attr, cls.__regid__)

                continue

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

                continue

            var = varmaker.next()

            selection.append(var)

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

            restrictions.append(restriction)

            if not rschema.is_final():

                # XXX this does not handle several destination types

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

                card = rschema.rproperty(eschema, desttype, '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.req.vreg iiiirk

                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.is_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:

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

        return res

    def clear_local_perm_cache(self, action):

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

    def check_perm(self, action):

    def has_perm(self, action):

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

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

    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

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

    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)

                if nbresults != 1: # ambiguity?

                    mainattr = 'eid'

                    path += '/eid'

        if mainattr == 'eid':

            if use_ext_eid:

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

            else:

                value = self.eid

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

        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.rproperties(attr)

        if attrtype == 'String':

            # internalinalized *and* formatted string such as schema

            # description...

            if props.get('internationalizable'):

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

            if attrformat:

                return self.mtc_transform(value, attrformat, format,

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

                                displaytime=displaytime)

        if format == 'text/html':

            value = xml_escape(value)

        return value

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

                      _engine=ENGINE):

        trdata = TransformData(data, format, encoding, appobject=self)

        data = _engine.convert(trdata, target_format).decode()

        if format == 'text/html':

        return data

    # entity cloning ##########################################################

    def copy_relations(self, ceid):

        """copy relations of the object with the given eid on this object

        By default meta and composite relations are skipped.

        Overrides this if you want another behaviour