"""workflow definition and history related entities

: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.decorators import cached, clear_cache

from logilab.common.deprecation import deprecated

from logilab.common.compat import any

from cubicweb.entities import AnyEntity, fetch_config

from cubicweb.interfaces import IWorkflowable

from cubicweb.common.mixins import MI_REL_TRIGGERS

class WorkflowException(Exception): pass

class Workflow(AnyEntity):

    __regid__ = 'Workflow'

    @property

    def initial(self):

        """return the initial state for this workflow"""

        return self.initial_state and self.initial_state[0] or None

    def is_default_workflow_of(self, etype):

        """return True if this workflow is the default workflow for the given

        entity type

        """

        return any(et for et in self.reverse_default_workflow

                   if et.name == etype)

    # XXX define parent() instead? what if workflow of multiple types?

    def after_deletion_path(self):

        """return (path, parameters) which should be used as redirect

        information when this entity is being deleted

        """

        if self.workflow_of:

            return self.workflow_of[0].rest_path(), {'vid': 'workflow'}

        return super(Workflow, self).after_deletion_path()

    def iter_workflows(self, _done=None):

        """return an iterator on actual workflows, eg this workflow and its

        subworkflows

        """

        # infinite loop safety belt

        if _done is None:

            _done = set()

        yield self

        _done.add(self.eid)

        for tr in self._cw.execute('Any T WHERE T is WorkflowTransition, '

                                   'T transition_of WF, WF eid %(wf)s',

                                   {'wf': self.eid}).entities():

            if tr.subwf.eid in _done:

                continue

            for subwf in tr.subwf.iter_workflows(_done):

                yield subwf

    # state / transitions accessors ############################################

    def state_by_name(self, statename):

        rset = self._cw.execute('Any S, SN WHERE S name SN, S name %(n)s, '

                                'S state_of WF, WF eid %(wf)s',

                                {'n': statename, 'wf': self.eid}, 'wf')

        if rset:

            return rset.get_entity(0, 0)

        return None

    def state_by_eid(self, eid):

        rset = self._cw.execute('Any S, SN WHERE S name SN, S eid %(s)s, '

                                'S state_of WF, WF eid %(wf)s',

                                {'s': eid, 'wf': self.eid}, ('wf', 's'))

        if rset:

            return rset.get_entity(0, 0)

        return None

    def transition_by_name(self, trname):

        rset = self._cw.execute('Any T, TN WHERE T name TN, T name %(n)s, '

                                'T transition_of WF, WF eid %(wf)s',

                                {'n': trname, 'wf': self.eid}, 'wf')

        if rset:

            return rset.get_entity(0, 0)

        return None

    def transition_by_eid(self, eid):

        rset = self._cw.execute('Any T, TN WHERE T name TN, T eid %(t)s, '

                                'T transition_of WF, WF eid %(wf)s',

                                {'t': eid, 'wf': self.eid}, ('wf', 't'))

        if rset:

            return rset.get_entity(0, 0)

        return None

    # wf construction methods ##################################################

    def add_state(self, name, initial=False, **kwargs):

        """add a state to this workflow"""

        state = self._cw.create_entity('State', name=unicode(name), **kwargs)

        self._cw.execute('SET S state_of WF WHERE S eid %(s)s, WF eid %(wf)s',

                         {'s': state.eid, 'wf': self.eid}, ('s', 'wf'))

        if initial:

            assert not self.initial, "Initial state already defined as %s" % self.initial

            self._cw.execute('SET WF initial_state S '

                             'WHERE S eid %(s)s, WF eid %(wf)s',

                             {'s': state.eid, 'wf': self.eid}, ('s', 'wf'))

        return state

    def _add_transition(self, trtype, name, fromstates,

                        requiredgroups=(), conditions=(), **kwargs):

        tr = self._cw.create_entity(trtype, name=unicode(name), **kwargs)

        self._cw.execute('SET T transition_of WF '

                         'WHERE T eid %(t)s, WF eid %(wf)s',

                         {'t': tr.eid, 'wf': self.eid}, ('t', 'wf'))

        assert fromstates, fromstates

        if not isinstance(fromstates, (tuple, list)):

            fromstates = (fromstates,)

        for state in fromstates:

            if hasattr(state, 'eid'):

                state = state.eid

            self._cw.execute('SET S allowed_transition T '

                             'WHERE S eid %(s)s, T eid %(t)s',

                             {'s': state, 't': tr.eid}, ('s', 't'))

        tr.set_transition_permissions(requiredgroups, conditions, reset=False)

        return tr

    def add_transition(self, name, fromstates, tostate=None,

                       requiredgroups=(), conditions=(), **kwargs):

        """add a transition to this workflow from some state(s) to another"""

        tr = self._add_transition('Transition', name, fromstates,

                                  requiredgroups, conditions, **kwargs)

        if tostate is not None:

            if hasattr(tostate, 'eid'):

                tostate = tostate.eid

            self._cw.execute('SET T destination_state S '

                             'WHERE S eid %(s)s, T eid %(t)s',

                             {'t': tr.eid, 's': tostate}, ('s', 't'))

        return tr

    def add_wftransition(self, name, subworkflow, fromstates, exitpoints=(),

                         requiredgroups=(), conditions=(), **kwargs):

        """add a workflow transition to this workflow"""

        tr = self._add_transition('WorkflowTransition', name, fromstates,

                                  requiredgroups, conditions, **kwargs)

        if hasattr(subworkflow, 'eid'):

            subworkflow = subworkflow.eid

        assert _cw.req.execute('SET T subworkflow WF WHERE WF eid %(wf)s,T eid %(t)s',

                               {'t': tr.eid, 'wf': subworkflow}, ('wf', 't'))

        for fromstate, tostate in exitpoints:

            tr.add_exit_point(fromstate, tostate)

        return tr

class BaseTransition(AnyEntity):

    """customized class for abstract transition

    provides a specific may_be_fired method to check if the relation may be

    fired by the logged user

    """

    __regid__ = 'BaseTransition'

    fetch_attrs, fetch_order = fetch_config(['name'])

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

        if self.__regid__ == 'BaseTransition':

            raise WorkflowException('should not be instantiated')

        super(BaseTransition, self).__init__(*args, **kwargs)

    @property

    def workflow(self):

        return self.transition_of[0]

    def has_input_state(self, state):

        if hasattr(state, 'eid'):

            state = state.eid

        return any(s for s in self.reverse_allowed_transition if s.eid == state)

    def may_be_fired(self, eid):

        """return true if the logged user may fire this transition

        `eid` is the eid of the object on which we may fire the transition

        """

        user = self._cw.user

        # check user is at least in one of the required groups if any

        groups = frozenset(g.name for g in self.require_group)

        if groups:

            matches = user.matching_groups(groups)

            if matches:

                return matches

            if 'owners' in groups and user.owns(eid):

                return True

        # check one of the rql expression conditions matches if any

        if self.condition:

            for rqlexpr in self.condition:

                if rqlexpr.check_expression(self._cw, eid):

                    return True

        if self.condition or groups:

            return False

        return True

    def after_deletion_path(self):

        """return (path, parameters) which should be used as redirect

        information when this entity is being deleted

        """

        if self.transition_of:

            return self.transition_of[0].rest_path(), {}

        return super(Transition, self).after_deletion_path()

    def set_transition_permissions(self, requiredgroups=(), conditions=(),

                                   reset=True):

        """set or add (if `reset` is False) groups and conditions for this

        transition

        """

        if reset:

            self._cw.execute('DELETE T require_group G WHERE T eid %(x)s',

                             {'x': self.eid}, 'x')

            self._cw.execute('DELETE T condition R WHERE T eid %(x)s',

                             {'x': self.eid}, 'x')

        for gname in requiredgroups:

            rset = self._cw.execute('SET T require_group G '

                                    'WHERE T eid %(x)s, G name %(gn)s',

                                    {'x': self.eid, 'gn': gname}, 'x')

            assert rset, '%s is not a known group' % gname

        if isinstance(conditions, basestring):

            conditions = (conditions,)

        for expr in conditions:

            if isinstance(expr, basestring):

                kwargs = {'expr': unicode(expr)}

            else:

                assert isinstance(expr, dict)

                kwargs = expr

            kwargs['x'] = self.eid

            kwargs.setdefault('mainvars', u'X')

            self._cw.execute('INSERT RQLExpression X: X exprtype "ERQLExpression", '

                             'X expression %(expr)s, T condition X '

                             'WHERE T eid %(x)s',

                             'T condition X WHERE T eid %(x)s', kwargs, 'x')

        # XXX clear caches?

class Transition(BaseTransition):

    """customized class for Transition entities"""

    __regid__ = 'Transition'

    def destination(self):

        return self.destination_state[0]

    def parent(self):

        return self.workflow

class WorkflowTransition(BaseTransition):

    """customized class for WorkflowTransition entities"""

    __regid__ = 'WorkflowTransition'

    @property

    def subwf(self):

        return self.subworkflow[0]

    def destination(self):

        return self.subwf.initial

    def add_exit_point(self, fromstate, tostate):

        if hasattr(fromstate, 'eid'):

            fromstate = fromstate.eid

        if tostate is None:

            self._cw.execute('INSERT SubWorkflowExitPoint X: T subworkflow_exit X, '

                             'X subworkflow_state FS WHERE T eid %(t)s, FS eid %(fs)s',

                             {'t': self.eid, 'fs': fromstate}, ('t', 'fs'))

        else:

            if hasattr(tostate, 'eid'):

                tostate = tostate.eid

            self._cw.execute('INSERT SubWorkflowExitPoint X: T subworkflow_exit X, '

                             'X subworkflow_state FS, X destination_state TS '

                             'WHERE T eid %(t)s, FS eid %(fs)s, TS eid %(ts)s',

                             {'t': self.eid, 'fs': fromstate, 'ts': tostate},

                             ('t', 'fs', 'ts'))

    def get_exit_point(self, entity, stateeid):

        """if state is an exit point, return its associated destination state"""

        if hasattr(stateeid, 'eid'):

            stateeid = stateeid.eid

        try:

            tostateeid = self.exit_points()[stateeid]

        except KeyError:

            return None

        if tostateeid is None:

            # go back to state from which we've entered the subworkflow

            return entity.subworkflow_input_trinfo().previous_state

        return self._cw.entity_from_eid(tostateeid)

    @cached

    def exit_points(self):

        result = {}

        for ep in self.subworkflow_exit:

            result[ep.subwf_state.eid] = ep.destination and ep.destination.eid

        return result

    def clear_all_caches(self):

        super(WorkflowableMixIn, self).clear_all_caches()

        clear_cache(self, 'exit_points')

class SubWorkflowExitPoint(AnyEntity):

    """customized class for SubWorkflowExitPoint entities"""

    __regid__ = 'SubWorkflowExitPoint'

    @property

    def subwf_state(self):

        return self.subworkflow_state[0]

    @property

    def destination(self):

        return self.destination_state and self.destination_state[0] or None

    def parent(self):

        return self.reverse_subworkflow_exit[0]

class State(AnyEntity):

    """customized class for State entities"""

    __regid__ = 'State'

    fetch_attrs, fetch_order = fetch_config(['name'])

    rest_attr = 'eid'

    @property

    def workflow(self):

        # take care, may be missing in multi-sources configuration

        return self.state_of and self.state_of[0]

    def parent(self):

        return self.workflow

class TrInfo(AnyEntity):

    """customized class for Transition information entities

    """

    __regid__ = 'TrInfo'

    fetch_attrs, fetch_order = fetch_config(['creation_date', 'comment'],

                                            pclass=None) # don't want modification_date

    @property

    def for_entity(self):

        return self.wf_info_for[0]

    @property

    def previous_state(self):

        return self.from_state[0]

    @property

    def new_state(self):

        return self.to_state[0]

    @property

    def transition(self):

        return self.by_transition and self.by_transition[0] or None

    def parent(self):

        return self.for_entity

class WorkflowableMixIn(object):

    """base mixin providing workflow helper methods for workflowable entities.

    This mixin will be automatically set on class supporting the 'in_state'

    relation (which implies supporting 'wf_info_for' as well)

    """

    __implements__ = (IWorkflowable,)

    @property

    def main_workflow(self):

        """return current workflow applied to this entity"""

        if self.custom_workflow:

            return self.custom_workflow[0]

        return self.cwetype_workflow()