# copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved.

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

#

# This file is part of CubicWeb.

#

# CubicWeb is free software: you can redistribute it and/or modify it under the

# terms of the GNU Lesser General Public License as published by the Free

# Software Foundation, either version 2.1 of the License, or (at your option)

# any later version.

#

# CubicWeb is distributed in the hope that it will be useful, but WITHOUT

# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS

# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more

# details.

#

# You should have received a copy of the GNU Lesser General Public License along

# with CubicWeb.  If not, see <http://www.gnu.org/licenses/>.

"""

Generalities

------------

Paraphrasing the `emacs`_ documentation, let us say that hooks are an important

mechanism for customizing an application. A hook is basically a list of

functions to be called on some well-defined occasion (this is called `running

the hook`).

.. _`emacs`: http://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html

Hooks

~~~~~

In |cubicweb|, hooks are subclasses of the :class:`~cubicweb.server.hook.Hook`

class. They are selected over a set of pre-defined `events` (and possibly more

conditions, hooks being selectable appobjects like views and components).  They

should implement a :meth:`~cubicweb.server.hook.Hook.__call__` method that will

be called when the hook is triggered.

There are two families of events: data events (before / after any individual

update of an entity / or a relation in the repository) and server events (such

as server startup or shutdown).  In a typical application, most of the hooks are

defined over data events.

Also, some :class:`~cubicweb.server.hook.Operation` may be registered by hooks,

which will be fired when the transaction is commited or rollbacked.

The purpose of data event hooks is usually to complement the data model as

defined in the schema, which is static by nature and only provide a restricted

builtin set of dynamic constraints, with dynamic or value driven behaviours.

For instance they can serve the following purposes:

* enforcing constraints that the static schema cannot express (spanning several

  entities/relations, exotic value ranges and cardinalities, etc.)

* implement computed attributes

It is functionally equivalent to a `database trigger`_, except that database

triggers definition languages are not standardized, hence not portable (for

instance, PL/SQL works with Oracle and PostgreSQL but not SqlServer nor Sqlite).

.. _`database trigger`: http://en.wikipedia.org/wiki/Database_trigger

.. hint::

   It is a good practice to write unit tests for each hook. See an example in

   :ref:`hook_test`

Operations

~~~~~~~~~~

Operations are subclasses of the :class:`~cubicweb.server.hook.Operation` class

that may be created by hooks and scheduled to happen on `precommit`,

`postcommit` or `rollback` event (i.e. respectivly before/after a commit or

before a rollback of a transaction).

Hooks are being fired immediately on data operations, and it is sometime

necessary to delay the actual work down to a time where we can expect all

information to be there, or when all other hooks have run (though take case

since operations may themselves trigger hooks). Also while the order of

execution of hooks is data dependant (and thus hard to predict), it is possible

to force an order on operations.

So, for such case where you may miss some information that may be set later in

the transaction, you should instantiate an operation in the hook.

Operations may be used to:

* implements a validation check which needs that all relations be already set on

  an entity

* process various side effects associated with a transaction such as filesystem

  udpates, mail notifications, etc.

Events

------

Hooks are mostly defined and used to handle `dataflow`_ operations. It

means as data gets in (entities added, updated, relations set or

unset), specific events are issued and the Hooks matching these events

are called.

You can get the event that triggered a hook by accessing its `event`

attribute.

.. _`dataflow`: http://en.wikipedia.org/wiki/Dataflow

Entity modification related events

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When called for one of these events, hook will have an `entity` attribute

containing the entity instance.

- `before_add_entity`, `before_update_entity`:

  On those events, you can access the modified attributes of the entity using

  the `entity.cw_edited` dictionnary. The values can be modified and the old

  values can be retrieved.

  If you modify the `entity.cw_edited` dictionnary in the hook, that is before

  the database operations take place, you will avoid the need to process a whole

  new rql query and the underlying backend query (eg usually sql) will contain

  the modified data. For example:

  .. sourcecode:: python

     self.entity.cw_edited['age'] = 42

  will modify the age before it is written to the backend storage.

  Similarly, removing an attribute from `cw_edited` will cancel its

  modification:

  .. sourcecode:: python

     del self.entity.cw_edited['age']

  On a `before_update_entity` event, you can access the old and new values:

  .. sourcecode:: python

     old, new = entity.cw_edited.oldnewvalue('age')

- `after_add_entity`, `after_update_entity`

  On those events, you can get the list of attributes that were modified using

  the `entity.cw_edited` dictionnary, but you can not modify it or get the old

  value of an attribute.

- `before_delete_entity`, `after_delete_entity`

  On those events, the entity has no `cw_edited` dictionnary.

.. note:: `self.entity.set_attributes(age=42)` will set the `age` attribute to

  42. But to do so, it will generate a rql query that will have to be processed,

  hence may trigger some hooks, etc. This could lead to infinitely looping hooks.

Relation modification related events

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When called for one of these events, hook will have `eidfrom`, `rtype`, `eidto`

attributes containing respectively the eid of the subject entity, the relation

type and the eid of the object entity.

* `before_add_relation`, `before_delete_relation`

  On those events, you can still get the original relation by issuing a rql query.

* `after_add_relation`, `after_delete_relation`

Take note that relations can be added or deleted, but not updated.

Non data events

~~~~~~~~~~~~~~~

Hooks called on server start/maintenance/stop event (eg `server_startup`,

`server_maintenance`, `server_shutdown`) have a `repo` attribute, but *their

`_cw` attribute is None*.  The `server_startup` is called on regular startup,

while `server_maintenance` is called on cubicweb-ctl upgrade or shell

commands. `server_shutdown` is called anyway.

Hooks called on backup/restore event (eg 'server_backup', 'server_restore') have

a `repo` and a `timestamp` attributes, but *their `_cw` attribute is None*.

Hooks called on session event (eg `session_open`, `session_close`) have no

special attribute.

API

---

Hooks control

~~~~~~~~~~~~~

It is sometimes convenient to explicitly enable or disable some hooks. For

instance if you want to disable some integrity checking hook.  This can be

controlled more finely through the `category` class attribute, which is a string

giving a category name.  One can then uses the

:class:`~cubicweb.server.session.hooks_control` context manager to explicitly

enable or disable some categories.

.. autoclass:: cubicweb.server.session.hooks_control

The existing categories are:

* ``security``, security checking hooks

* ``worfklow``, workflow handling hooks

* ``metadata``, hooks setting meta-data on newly created entities

* ``notification``, email notification hooks

* ``integrity``, data integrity checking hooks

* ``activeintegrity``, data integrity consistency hooks, that you should **never**

  want to disable

* ``syncsession``, hooks synchronizing existing sessions

* ``syncschema``, hooks synchronizing instance schema (including the physical database)

* ``email``, email address handling hooks

* ``bookmark``, bookmark entities handling hooks

Nothing precludes one to invent new categories and use the

:class:`~cubicweb.server.session.hooks_control` context manager to

filter them in or out. Note that ending the transaction with commit()

or rollback() will restore the hooks.

Hooks specific selector

~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: cubicweb.server.hook.match_rtype

.. autoclass:: cubicweb.server.hook.match_rtype_sets

Hooks and operations classes

~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: cubicweb.server.hook.Hook

.. autoclass:: cubicweb.server.hook.Operation

.. autoclass:: cubicweb.server.hook.LateOperation

.. autoclass:: cubicweb.server.hook.DataOperationMixIn

"""

from __future__ import with_statement

__docformat__ = "restructuredtext en"

from warnings import warn

from logging import getLogger

from itertools import chain

from logilab.common.decorators import classproperty, cached

from logilab.common.deprecation import deprecated, class_renamed

from logilab.common.logging_ext import set_log_methods

from cubicweb import RegistryNotFound

from cubicweb.vregistry import classid

from cubicweb.cwvreg import CWRegistry, VRegistry

from cubicweb.selectors import (objectify_selector, lltrace, ExpectedValueSelector,

                                is_instance)

from cubicweb.appobject import AppObject, NotSelector, OrSelector

from cubicweb.server.session import security_enabled

ENTITIES_HOOKS = set(('before_add_entity',    'after_add_entity',

                      'before_update_entity', 'after_update_entity',

                      'before_delete_entity', 'after_delete_entity'))

RELATIONS_HOOKS = set(('before_add_relation',   'after_add_relation' ,

                       'before_delete_relation','after_delete_relation'))

SYSTEM_HOOKS = set(('server_backup', 'server_restore',

                    'server_startup', 'server_maintenance', 'server_shutdown',

                    'session_open', 'session_close'))

ALL_HOOKS = ENTITIES_HOOKS | RELATIONS_HOOKS | SYSTEM_HOOKS

def _iter_kwargs(entities, eids_from_to, kwargs):

    if not entities and not eids_from_to:

        yield kwargs

    elif entities:

        for entity in entities:

            kwargs['entity'] = entity

            yield kwargs

    else:

        for subject, object in eids_from_to:

            kwargs.update({'eidfrom': subject, 'eidto': object})

            yield kwargs

class HooksRegistry(CWRegistry):

    def initialization_completed(self):

        for appobjects in self.values():

            for cls in appobjects:

                if not cls.enabled:

                    warn('[3.6] %s: enabled is deprecated' % classid(cls))

                    self.unregister(cls)

    def register(self, obj, **kwargs):

        obj.check_events()

        super(HooksRegistry, self).register(obj, **kwargs)

    def call_hooks(self, event, session=None, **kwargs):

        """call `event` hooks for an entity or a list of entities (passed

        respectively as the `entity` or ``entities`` keyword argument).

        """

        kwargs['event'] = event

        if session is None: # True for events such as server_start

            for hook in sorted(self.possible_objects(session, **kwargs),

                               key=lambda x: x.order):

                hook()

        else:

            if 'entities' in kwargs:

                assert 'entity' not in kwargs, \

                       'can\'t pass "entities" and "entity" arguments simultaneously'

                assert 'eids_from_to' not in kwargs, \

                       'can\'t pass "entities" and "eids_from_to" arguments simultaneously'

                entities = kwargs.pop('entities')

                eids_from_to = []

            elif 'eids_from_to' in kwargs:

                entities = []

                eids_from_to = kwargs.pop('eids_from_to')

            else:

                entities = []

                eids_from_to = []

            pruned = self.get_pruned_hooks(session, event,

                                           entities, eids_from_to, kwargs)

            # by default, hooks are executed with security turned off

            with security_enabled(session, read=False):

                for _kwargs in _iter_kwargs(entities, eids_from_to, kwargs):

                    hooks = sorted(self.filtered_possible_objects(pruned, session, **_kwargs),

                                   key=lambda x: x.order)

                    with security_enabled(session, write=False):

                        for hook in hooks:

                           hook()

    def get_pruned_hooks(self, session, event, entities, eids_from_to, kwargs):

        """return a set of hooks that should not be considered by filtered_possible objects

        the idea is to make a first pass over all the hooks in the

        registry and to mark put some of them in a pruned list. The

        pruned hooks are the one which:

        * are disabled at the session level

        * have a match_rtype or an is_instance selector which does not

          match the rtype / etype of the relations / entities for

          which we are calling the hooks. This works because the

          repository calls the hooks grouped by rtype or by etype when

          using the entities or eids_to_from keyword arguments

        Only hooks with a simple selector or an AndSelector of simple

        selectors are considered for disabling.

        """

        if 'entity' in kwargs:

            entities = [kwargs['entity']]

        if len(entities):

            look_for_selector = is_instance

            etype = entities[0].__regid__

        elif 'rtype' in kwargs:

            look_for_selector = match_rtype

            etype = None

        else: # nothing to prune, how did we get there ???

            return set()

        cache_key = (event, kwargs.get('rtype'), etype)

        pruned = session.pruned_hooks_cache.get(cache_key)

        if pruned is not None:

            return pruned

        pruned = set()

        session.pruned_hooks_cache[cache_key] = pruned

        if look_for_selector is not None:

            for id, hooks in self.iteritems():

                for hook in hooks:

                    enabled_cat, main_filter = hook.filterable_selectors()

                    if enabled_cat is not None:

                        if not enabled_cat(hook, session):

                            pruned.add(hook)

                            continue

                    if main_filter is not None:

                        if isinstance(main_filter, match_rtype) and \

                           (main_filter.frometypes is not None  or \

                            main_filter.toetypes is not None):

                            continue

                        first_kwargs = _iter_kwargs(entities, eids_from_to, kwargs).next()

                        if not main_filter(hook, session, **first_kwargs):

                            pruned.add(hook)

        return pruned

    def filtered_possible_objects(self, pruned, *args, **kwargs):

        for appobjects in self.itervalues():

            if pruned:

                filtered_objects = [obj for obj in appobjects if obj not in pruned]

                if not filtered_objects:

                    continue

            else:

                filtered_objects = appobjects

            obj = self._select_best(filtered_objects,

                                    *args, **kwargs)

            if obj is None:

                continue

            yield obj

class HooksManager(object):

    def __init__(self, vreg):

        self.vreg = vreg

    def call_hooks(self, event, session=None, **kwargs):

        try:

            registry = self.vreg['%s_hooks' % event]

        except RegistryNotFound:

            return # no hooks for this event

        registry.call_hooks(event, session, **kwargs)

for event in ALL_HOOKS:

    VRegistry.REGISTRY_FACTORY['%s_hooks' % event] = HooksRegistry

@deprecated('[3.10] use entity.cw_edited.oldnewvalue(attr)')

def entity_oldnewvalue(entity, attr):

    return entity.cw_edited.oldnewvalue(attr)

# some hook specific selectors #################################################