# 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 just before (or after) the

`precommit`, `postcommit` or `rollback` event. Hooks are being fired immediately

on data operations, and it is sometime necessary to delay the actual work down

to a time where all other hooks have run. 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.

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 :attr: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 check what attributes of the entity are modified in

    `entity.cw_edited` (by definition the database is not yet updated in a before

    event)

  - you are allowed to further modify the entity before database

    operations, using the dictionary notation on `cw_edited`. By doing

    this, you'll avoid the need for a whole new rql query processing,

    the only difference is that the underlying backend query (eg

    usually sql) will contains the additional data. For example:

    .. sourcecode:: python

       self.entity.set_attributes(age=42)

    will set the `age` attribute of the entity to 42. But to do so, it will

    generate a rql query that will have to be processed, then trigger some

    hooks, and so one (potentially leading to infinite hook loops or such

    awkward situations..) You can avoid this by doing the modification that way:

    .. sourcecode:: python

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

    Here the attribute will simply be edited in the same query that the

    one that triggered the hook.

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

    modification.

  - on `before_update_entity` event, you can access to old and new values in

    this hook, by using `entity.cw_edited.oldnewvalue(attr)`

* `after_add_entity`, `after_update_entity`

  - on those events, you can still check what attributes of the entity are

    modified in `entity.cw_edited` but you can't get anymore the old value, nor

    modify it.

* `before_delete_entity`, `after_delete_entity`

  - on those events, the entity has no `cw_edited` set.

Relation modification related events

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

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

attributes containing respectivly 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 original relation by issuing a rql query

* `after_add_relation`, `after_delete_relation`

This is an occasion to remind us that relations support the add / delete

operation, but no update.

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

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

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, kwargs):

    if not entities:

        yield kwargs

    else:

        for entity in entities:

            kwargs['entity'] = entity

            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'

                entities = kwargs.pop('entities')

            else:

                entities = []

            # by default, hooks are executed with security turned off

            with security_enabled(session, read=False):

                for _kwargs in _iter_kwargs(entities, kwargs):

                    hooks = sorted(self.possible_objects(session, **_kwargs),

                                   key=lambda x: x.order)

                    with security_enabled(session, write=False):

                        for hook in hooks:

                            #print hook.category, hook.__regid__

                            hook()

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

@objectify_selector

@lltrace

def enabled_category(cls, req, **kwargs):

    if req is None:

        return True # XXX how to deactivate server startup / shutdown event

    return req.is_hook_activated(cls)

@objectify_selector

@lltrace

def from_dbapi_query(cls, req, **kwargs):

    if req.running_dbapi_query:

        return 1

    return 0

class rechain(object):

    def __init__(self, *iterators):

        self.iterators = iterators

    def __iter__(self):

        return iter(chain(*self.iterators))

class match_rtype(ExpectedValueSelector):

    """accept if parameters specified as initializer arguments are specified

    in named arguments given to the selector

    :param *expected: parameters (eg `basestring`) which are expected to be

                      found in named arguments (kwargs)

    """

    def __init__(self, *expected, **more):

        self.expected = expected

        self.frometypes = more.pop('frometypes', None)

        self.toetypes = more.pop('toetypes', None)

        assert not more, "unexpected kwargs in match_rtype: %s" % more

    @lltrace

    def __call__(self, cls, req, *args, **kwargs):

        if kwargs.get('rtype') not in self.expected:

            return 0

        if self.frometypes is not None and \

               req.describe(kwargs['eidfrom'])[0] not in self.frometypes:

            return 0

        if self.toetypes is not None and \

               req.describe(kwargs['eidto'])[0] not in self.toetypes:

            return 0

        return 1

class match_rtype_sets(ExpectedValueSelector):

    """accept if the relation type is in one of the sets given as initializer

    argument. The goal of this selector is that it keeps reference to original sets,

    so modification to thoses sets are considered by the selector. For instance

    MYSET = set()

    class Hook1(Hook):

        __regid__ = 'hook1'

        __select__ = Hook.__select__ & match_rtype_sets(MYSET)

        ...

    class Hook2(Hook):

        __regid__ = 'hook2'

        __select__ = Hook.__select__ & match_rtype_sets(MYSET)

    Client code can now change `MYSET`, this will changes the selection criteria

    of :class:`Hook1` and :class:`Hook1`.

    """

    def __init__(self, *expected):

        self.expected = expected

    @lltrace

    def __call__(self, cls, req, *args, **kwargs):

        for rel_set in self.expected:

            if kwargs.get('rtype') in rel_set:

                return 1

        return 0

# base class for hook ##########################################################

class Hook(AppObject):

    """Base class for hook.

    Hooks being appobjects like views, they have a `__regid__` and a `__select__`

    class attribute. Like all appobjects, hooks have the `self._cw` attribute which

    represents the current session. In entity hooks, a `self.entity` attribute is

    also present.