GreenRocket 0.20

Green Rocket
============

Green Rocket is a simple and compact implementation of Observer
(or Publish/Subscribe) design pattern via signals.

Create specific signal using base one::

>>> from greenrocket import Signal
>>> class MySignal(Signal):
... pass
...

Subscribe handler::

>>> @MySignal.subscribe
... def handler(signal):
... print('handler: ' + repr(signal))
...

Fire signal::

>>> MySignal().fire()
handler: MySignal()

Note, that signal propagates over inheritance, i.e. all subscribers of base
signal will be called when child one is fired::

>>> @Signal.subscribe
... def base_hadler(signal):
... print('base_handler: ' + repr(signal))
...
>>> MySignal().fire()
handler: MySignal()
base_handler: MySignal()

Unsubscribe handler::

>>> MySignal.unsubscribe(handler)
>>> MySignal().fire()
base_handler: MySignal()

The handler is subscribed using weak reference. So if you create and subscribe
a handler in local scope (for example inside a generator), it will unsubscribed
automatically.

::

>>> def gen():
... @MySignal.subscribe
... def local_handler(signal):
... print('local_handler: ' + repr(signal))
... yield 1
...
>>> for value in gen():
... MySignal(value=value).fire()
...
local_handler: MySignal(value=1)
base_handler: MySignal(value=1)
>>> import gc # PyPy fails the following test without
>>> gc.collect() # an explicit call of garbage collector.
0
>>> MySignal(value=2).fire()
base_handler: MySignal(value=2)

As you can see above, signal constructor accepts keyword arguments. These
arguments are available as signal attributes::

>>> s = MySignal(a=1, b=2)
>>> s.a
1
>>> s.b
2

Signal suppresses any exception which is raised on handler call. It uses
logger named ``greenrocket`` from standard ``logging`` module to log errors and
debug information.


CHANGES
=======

0.20
----

* Changed handler subscription mechanism from subscription by reference to
subscription by weak reference

0.11
----

* Fixed logger loose on program termination

0.1
---

* Initial release