********
Eventize
********

.. image:: https://pypip.in/v/eventize/badge.png
        :target: https://pypi.python.org/pypi/eventize


Add events to object methods and attributes.

Events are triggered at 3 levels in order:
  * Descriptor Class: for all Attribute or Method types (from version 0.3)
  * Descriptor Instance: for all classes that have an Attribute or a Method
  * Object instance: for the given object attribute value or method


Methods support events "before" and "after"
Attributes support events: "on_get", "on_set", "on_del"

Events can be triggered conditionaly within arguments or user condition.

Since version 0.3, observers defined at Descriptor Instance level are preserved in descriptor container class children, providing inheritance. see example 4

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

**Table of Contents**


.. contents::
    :local:
    :depth: 1
    :backlinks: none


=============
Installation
=============

Install it from pypi::

  pip install eventize

or from sources::

  git clone git@github.com:apieum/eventize.git
  cd eventize
  python setup.py install

=====
Usage
=====

-----------------------------
Example 1 - observe a method:
-----------------------------
  As ObservedMethod class take a function as argument it can be used as a decorator.

.. code-block:: python


  from eventize import ObservedMethod
  from eventize.events import Expect

  class Observed(object):
    def __init__(self):
      self.valid = False
      self.logs=[]

    @ObservedMethod
    def is_valid(self, *args, **kwargs):
      return self.valid

    def not_valid(self, event):
      event.subject.valid = not event.subject.valid

  class Logger(list):
    def log_before(self, event):
      self.append(self.message('before', *event.args, is_valid=event.subject.valid))

    def log_after(self, event):
      self.append(self.message('after', *event.args, is_valid=event.subject.valid))

    def message(self, event_name, *args, **kwargs):
      return "%s called with args: '%s', current:'%s'" % (event_name, args, kwargs['is_valid'])



  my_object = Observed()
  my_logs = Logger()
  called_with_permute = Expect.arg('permute')

  my_object.is_valid.before += my_logs.log_before
  my_object.is_valid.before.when(called_with_permute).do(my_object.not_valid)
  my_object.is_valid.after += my_logs.log_after

  assert my_object.is_valid() is False
  assert my_object.is_valid('permute') is True

  assert my_logs == [
    my_logs.message('before', is_valid=False),
    my_logs.message('after', is_valid=False),
    my_logs.message('before', 'permute', is_valid=False),
    my_logs.message('after', 'permute', is_valid=True),
  ]


---------------------------------
Example 2 - observe an attribute:
---------------------------------

.. code-block:: python

  from eventize import ObservedAttribute
  class Validator(object):
    def __init__(self, is_valid=False):
      self.valid = is_valid

  class Observed(object):
    validator = ObservedAttribute(default=Validator(False))

  class Logger(list):
    def log_get(self, event):
      self.append(self.message('on_get', event.name, event.value.valid))
    def log_set(self, event):
      self.append(self.message('on_set', event.name, event.value.valid))
    def log_del(self, event):
      self.append(self.message('on_del', event.name, event.value.valid))

    def message(self, event_name, attr_name, value):
      return "'%s' called for attribute '%s', with value '%s'" % (event_name, attr_name, value)

  my_object = Observed()
  my_logs = Logger()
  # Note: order matter here !
  my_object.validator.on_del += my_logs.log_del
  my_object.validator.on_set += my_logs.log_set
  my_object.validator.on_get += my_logs.log_get

  Observed.validator.on_set += my_logs.log_set
  Observed.validator.on_del += my_logs.log_del
  Observed.validator.on_get += my_logs.log_get

  assert my_object.validator.valid == False, 'Default value was not set'
  setattr(my_object, 'validator', Validator(True))
  del my_object.validator

  assert my_logs == [
    my_logs.message('on_get', 'v