Metadata-Version: 1.1
Name: nmevent
Version: 0.3.2
Summary: A simple C#-like implementation of the Observer design pattern.
Home-page: http://pypi.python.org/pypi/nmevent
Author: Jan Milík
Author-email: milikjan@fit.cvut.cz
License: Lesser General Public License v3
Description: nmevent v0.3.2 - 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.3.2
          Added fairly useful functionality to the :func:`adapt` function: it
          can now connect to "nested events". See the functions's documentation
          for more information. It can also disconnect the handlers as well.
        
        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.
        
        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.2.1
          Rewritten some unit tests and added new ones. Improved documentation
          a little bit.
        
        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.1.1
          No changes in source code. Improved documentation and unit tests.
        
        v0.1
          Initial release.
        
Keywords: library event observer pattern
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.6
Provides: nmevent
