nmevent 0.3.1

A simple C#-like implementation of the Observer design pattern.

nmevent v0.3.1 - C#-like implementation of the Observer pattern

This is a Python module :mod:`nmevent`, simple C#-like implementation of
the Observer pattern (http://en.wikipedia.org/wiki/Observer_pattern).
It's main purpose and goal is to allow developers to use events
with C#-like syntax in their Python classes.

=============
Usage example
=============

The most straightfoward way to use :mod:`nmevent` is this:

>>> import nmevent
>>> class ExampleClass(object):
... def __init__(self):
... self.event = nmevent.Event()
...
... def do_something(self):
... self.event(self)
...
>>> def handler(sender, **keywords):
... print "event occured"
...
>>> example = ExampleClass()
>>> example.event += handler
>>> example.do_something()
event occured

It should be noted, that event doesn't necessarily need to be an object
attribute. :class:`Event` instance is basically just a callable object that
works as a sort of "dispatch demultiplexer".

This usage, however, isn't very C#-like. In C#, events are declared in class
scope and that's why the :class:`Event` class also supports the descriptor
protocol (you can use the same way you use the built-in ``property`` object).

>>> from nmevent import Event
>>> class ExampleClass(object):
... event = Event()
...
... def _do_something(self):
... self.event()
...
>>> def handler(sender, **keywords):
... pass
...
>>> example = ExampleClass()
>>> example.event += handler

Perhaps this looks even more straightfoward than instantiating :class:`Event`
in object's constructor, but there's actually lot more going on under hood this
time.

Finally, there is the :class:`Property` descriptor and the associated
:func:`nmproperty` function decorator, which work very much like the built-in
``property`` object and decorator, except it can optionally call a callback
function if the property's value changes after calling the setter function. It
can work in tandem with the :func:`with_events` class decorator, which
decorates the class with property change events and connects them to the
instances of :class:`Property` class. It also creates events for the built-in
``property`` objects, but you have to raise the events yourself in the setter
function or elsewhere.

>>> @nmevent.with_events
... class ExampleClass(object):
... @nmevent.nmproperty
... def x(self):
... return self._x
...
... @x.setter
... def x(self, value):
... self._x = value
...
... @property
... def y(self):
... return self._y
...
... @y.setter
... def y(self, value):
... old_value, self._y = self._y, value
... self.y_changed(old_value = old_value)
...
... def __init__(self):
... self._x = None
... self._y = None
...
>>> def handler(sender, **keywords):
... print "x changed"
...
>>> example = ExampleClass()
>>> example.x_changed += handler
>>> example.x = 10 # handler gets called
x changed

=======
License
=======

Copyright (c) 2010, Jan Milík.

This program 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 3 of the License, or
(at your option) any later version.

This program is distributed in the hope the it will be useful,
but WITHOUT ANY WARRANTY; without event the implied warranty of
MERCHANTIBILITY 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 this program. If not, see <http://www.gnu.org/licenses/>.

=======
Changes
=======

v0.1
Initial release.

v0.1.1
No changes in source code. Improved documentation and unit tests.

v0.2
Rewritten most of the code. The :class:`Event` class now works as a
descriptor, which eliminated the need for a separate :class:`EventSlot`
class and simplified usage. Added :class:`CallbackStore` to abstract
the callback storage.

v0.2.1
Rewritten some unit tests and added new ones. Improved documentation
a little bit.

v0.3
Fixed a major bug, which caused an unbound event not to be actually
bound when called with an object instance as the first argument.

Added the :func:`with_properties` class decorator, which automatically
decorates a class with "private" attributes for each property and
automatic getters and setters where either one of them is missing.

v0.3.1
Added docstring tests and fixed all the docstrings so that they
would pass. As a result, another problem was found with the event
binding. That problem was fixed by adding the :meth:`InstanceEvent.bind`
method to be used mainly by the :class:`Property` class when raising
the "changed" events.