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

    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)

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

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

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

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

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

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

        if initial:

            assert not self.initial

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

                         '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

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

                       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 hasattr(tostate, 'eid'):

            tostate = tostate.eid

                         '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

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

        """

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

                    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:

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

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

        for gname in requiredgroups:

                                    '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, str):

                expr = unicode(expr)

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

                             'WHERE T eid %(x)s',

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

        # XXX clear caches?

class Transition(BaseTransition):

    """customized class for Transition entities"""

    __regid__ = 'Transition'

    def destination(self):

        return self.destination_state[0]

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 hasattr(tostate, 'eid'):

            tostate = tostate.eid

                         '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, state):

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

        if hasattr(state, 'eid'):

            state = state.eid

        stateeid = self.exit_points().get(state)

        if stateeid is not None:

        return None

    @cached

    def exit_points(self):

        result = {}

        for ep in self.subworkflow_exit:

            result[ep.subwf_state.eid] = 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[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 after_deletion_path(self):

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

        information when this entity is being deleted

        """

        if self.state_of:

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

        return super(State, self).after_deletion_path()

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

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

        information when this entity is being deleted

        """

        if self.for_entity:

            return self.for_entity.rest_path(), {}

        return 'view', {}

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

    @property

    def current_workflow(self):

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

        return self.current_state and self.current_state.workflow or self.main_workflow

    @property

    def current_state(self):

        """return current state entity"""

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

    @property

    def state(self):

        """return current state name"""

        try:

            return self.in_state[0].name

        except IndexError: