"""Base class for entity objects manipulated in clients

:organization: Logilab

:copyright: 2001-2009 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

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

"""

__docformat__ = "restructuredtext en"

from logilab.common import interface

from logilab.common.compat import all

from logilab.common.decorators import cached

from logilab.common.deprecation import obsolete

from logilab.mtconverter import TransformData, TransformError, html_escape

from rql.utils import rqlvar_maker

from cubicweb import Unauthorized

from cubicweb.rset import ResultSet

from cubicweb.selectors import yes

from cubicweb.appobject import AppRsetObject

from cubicweb.schema import RQLVocabularyConstraint, RQLConstraint, bw_normalize_etype

try:

    from cubicweb.common.uilib import printable_value, soup2xhtml

    from cubicweb.common.mixins import MI_REL_TRIGGERS

    from cubicweb.common.mttransforms import ENGINE

except ImportError:

    # missing -common

    MI_REL_TRIGGERS = {}

_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 RelationTags(object):

    MODE_TAGS = frozenset(('link', 'create'))

    CATEGORY_TAGS = frozenset(('primary', 'secondary', 'generic', 'generated',

                               'inlineview'))

    def __init__(self, eclass, tagdefs):

        # XXX if a rtag is redefined in a subclass,

        # the rtag of the base class overwrite the rtag of the subclass

        self.eclass = eclass

        self._tagdefs = {}

        for relation, tags in tagdefs.iteritems():

            # tags must become a set

            if isinstance(tags, basestring):

                tags = set((tags,))

            elif not isinstance(tags, set):

                tags = set(tags)

            # relation must become a 3-uple (rtype, targettype, role)

            if isinstance(relation, basestring):

                self._tagdefs[(relation, '*', 'subject')] = tags

                self._tagdefs[(relation, '*', 'object')] = tags

            elif len(relation) == 1: # useful ?

                self._tagdefs[(relation[0], '*', 'subject')] = tags

                self._tagdefs[(relation[0], '*', 'object')] = tags

            elif len(relation) == 2:

                rtype, ttype = relation

                ttype = bw_normalize_etype(ttype) # XXX bw compat

                self._tagdefs[rtype, ttype, 'subject'] = tags

                self._tagdefs[rtype, ttype, 'object'] = tags

            elif len(relation) == 3:

                relation = list(relation)  # XXX bw compat

                relation[1] = bw_normalize_etype(relation[1])

                self._tagdefs[tuple(relation)] = tags

            else:

                raise ValueError('bad rtag definition (%r)' % (relation,))

    def __initialize__(self):

        # eclass.[*]schema are only set when registering

        self.schema = self.eclass.schema

        eschema = self.eschema = self.eclass.e_schema

        rtags = self._tagdefs

        # expand wildcards in rtags and add automatic tags

        for rschema, tschemas, role in sorted(eschema.relation_definitions(True)):

            rtype = rschema.type

            star_tags = rtags.pop((rtype, '*', role), set())

            for tschema in tschemas:

                tags = rtags.setdefault((rtype, tschema.type, role), set(star_tags))

                if role == 'subject':

                    X, Y = eschema, tschema

                    card = rschema.rproperty(X, Y, 'cardinality')[0]

                    composed = rschema.rproperty(X, Y, 'composite') == 'object'

                else:

                    X, Y = tschema, eschema

                    card = rschema.rproperty(X, Y, 'cardinality')[1]

                    composed = rschema.rproperty(X, Y, 'composite') == 'subject'

                # set default category tags if needed

                if not tags & self.CATEGORY_TAGS:

                    if card in '1+':

                        if not rschema.is_final() and composed:

                            category = 'generated'

                        elif rschema.is_final() and (

                            rschema.type.endswith('_format')

                            or rschema.type.endswith('_encoding')):

                            category = 'generated'

                        else:

                            category = 'primary'

                    elif rschema.is_final():

                        if (rschema.type.endswith('_format')

                            or rschema.type.endswith('_encoding')):

                            category = 'generated'

                        else:

                            category = 'secondary'

                    else: 

                        category = 'generic'

                    tags.add(category)

                if not tags & self.MODE_TAGS:

                    if card in '?1':

                        # by default, suppose link mode if cardinality doesn't allow

                        # more than one relation

                        mode = 'link'

                    elif rschema.rproperty(X, Y, 'composite') == role:

                        # if self is composed of the target type, create mode

                        mode = 'create'

                    else:

                        # link mode by default

                        mode = 'link'

                    tags.add(mode)

    def _default_target(self, rschema, role='subject'):

        eschema = self.eschema

        if role == 'subject':

            return eschema.subject_relation(rschema).objects(eschema)[0]

        else:

            return eschema.object_relation(rschema).subjects(eschema)[0]

    # dict compat

    def __getitem__(self, key):

        if isinstance(key, basestring):

            key = (key,)

        return self.get_tags(*key)

    __contains__ = __getitem__

    def get_tags(self, rtype, targettype=None, role='subject'):

        rschema = self.schema.rschema(rtype)

        if targettype is None:

            tschema = self._default_target(rschema, role)

        else:

            tschema = self.schema.eschema(targettype)

        return self._tagdefs[(rtype, tschema.type, role)]

    __call__ = get_tags

    def get_mode(self, rtype, targettype=None, role='subject'):

        # XXX: should we make an assertion on rtype not being final ?

        # assert not rschema.is_final()

        tags = self.get_tags(rtype, targettype, role)

        # do not change the intersection order !

        modes = tags & self.MODE_TAGS

        assert len(modes) == 1

        return modes.pop()

    def get_category(self, rtype, targettype=None, role='subject'):

        tags = self.get_tags(rtype, targettype, role)

        categories = tags & self.CATEGORY_TAGS

        assert len(categories) == 1

        return categories.pop()

    def is_inlined(self, rtype, targettype=None, role='subject'):

        # return set(('primary', 'secondary')) & self.get_tags(rtype, targettype)

        return 'inlineview' in self.get_tags(rtype, targettype, role)

class metaentity(type):

    """this metaclass sets the relation tags on the entity class

    and deals with the `widgets` attribute

    """

    def __new__(mcs, name, bases, classdict):

        # collect baseclass' rtags

        tagdefs = {}

        widgets = {}

        for base in bases:

            tagdefs.update(getattr(base, '__rtags__', {}))

            widgets.update(getattr(base, 'widgets', {}))

        # update with the class' own rtgas

        tagdefs.update(classdict.get('__rtags__', {}))

        widgets.update(classdict.get('widgets', {}))

        # XXX decide whether or not it's a good idea to replace __rtags__

        #     good point: transparent support for inheritance levels >= 2

        #     bad point: we loose the information of which tags are specific

        #                to this entity class

        classdict['__rtags__'] = tagdefs

        classdict['widgets'] = widgets

        eclass = super(metaentity, mcs).__new__(mcs, name, bases, classdict)

        # adds the "rtags" attribute

        eclass.rtags = RelationTags(eclass, tagdefs)

        return eclass

class Entity(AppRsetObject, 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

    """

    __metaclass__ = metaentity

    __registry__ = 'etypes'

    __select__ = yes()

    widgets = {}

    id = None

    e_schema = None

    eid = None

    rest_attr = None

    skip_copy_for = ()

    @classmethod

    def registered(cls, registry):

        """build class using descriptor at registration time"""

        assert cls.id is not None

        super(Entity, cls).registered(registry)

        if cls.id != 'Any':

            cls.__initialize__()

        return cls

    MODE_TAGS = set(('link', 'create'))

    CATEGORY_TAGS = set(('primary', 'secondary', 'generic', 'generated')) # , 'metadata'))

    @classmethod

    def __initialize__(cls):

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

        entity type's attributes and relations

        """

        etype = cls.id

        assert etype != 'Any', etype

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

        for rschema, _ in eschema.attribute_definitions():

            if rschema.type == 'eid':

                continue

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

        mixins = []

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

            if (rschema, x) in MI_REL_TRIGGERS:

                mixin = MI_REL_TRIGGERS[(rschema, x)]

                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 x == '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)

        cls.rtags.__initialize__()

    @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.id))

        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.id)

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

                    selection.pop()

                    restrictions.pop()

                    continue

                if card == '?':

                    restrictions[-1] += '?' # left outer join if not mandatory

                destcls = cls.vreg.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

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

        AppRsetObject.__init__(self, req, rset)

        dict.__init__(self)

        self.row, self.col = row, col

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