nmevent 0.3

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

nmevent v0.3 - 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)
...
>>> example = ExampleClass()
>>> example.event += handler

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.

>>> import nmevent
>>> @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)
...
>>> example = ExampleClass()
>>> example.x_changed += handler
>>> example.x = 10 # handler gets called

=======
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.