PyDispatcher provides the Python programmer
with a multiple-producer-multiple-consumer signal-registration and
routing infrastructure for use in multiple contexts. The
mechanism
of PyDispatcher started life as a highly rated recipe
in the Python
Cookbook. The project
aims
to include various enhancements to the recipe developed during use in
various applications. It is primarily maintained by Mike Fletcher. A derivative
of the project provides the Django web framework's "signal" system.
To be more concrete about what PyDispatcher does for you:
The dispatcher mechanism is particularly useful when constructing Model-View-Controller style applications where it is not desirable to have the Model objects aware of the event model.
PyDispatcher is available as a standard Python distutils
installation package from the Python Package Index (PyPI). To
install, run:
pip install PyDispatcher
PyDispatcher does not include any binary packages, so there should be no issues in installation. PyDispatcher is maintained on the LaunchPad project in bzr. To help develop, check out the project like so:
bzr branch lp:~mcfletch/pydispatcher/working
You can either send a pull request via LaunchPad or email a patch-set via:
bzr send --mail-to=mcfletch@vrplumber.com
PyDispatcher represents one of the more involved
usage patterns for Python weakref objects. We have discovered a few
problems in weakref operation of which users of the package should be
aware.
Python 2.2.2 (and
earlier) weak reference implementations have a subtle bug
in their weakref destructor code which can cause memory access errors
(aka segfaults) on program shutdown. If you are using Python 2.2,
it is strongly
recommended that you use Python 2.2.3 or
later
when using PyDispatcher. Note that this will not address the
following issue.
Python 2.3.2 (and earlier) has a different (even more subtle) bug in the weakref destructor code which, again, can cause segfaults. If you are using Python 2.3, it is strongly recommended that you use Python 2.3.3 or later when using PyDispatcher. This bug-fix will not be ported back to the Python 2.2.x branch, so if you are using Python 2.2.3 you may encounter this situation.
You can find usage samples in the examples directory of the
distribution. The dispatcher module's reference documentation is
currently the major source of information regarding usage.
PyDispatcher welcomes contributions, suggestions, and feedback from users in the pydispatcher-dev mailing list.
To set up a function to receive signals:
from pydispatch import dispatcher
SIGNAL = 'my-first-signal'
def handle_event( sender ):
"""Simple event handler"""
print 'Signal was sent by', sender
dispatcher.connect( handle_event, signal=SIGNAL, sender=dispatcher.Any )
The use of the Any object allows the handler to listen for messages from any Sender or to listen to Any message being sent. To send messages:
first_sender = object()
second_sender = {}
def main( ):
dispatcher.send( signal=SIGNAL, sender=first_sender )
dispatcher.send( signal=SIGNAL, sender=second_sender )
Which causes the following to be printed:
Signal was sent by <object object at 0x196a090>
Signal was sent by {}
Handler functions in PyDispatcher are relatively loose in their definition. A handler can simply declare the parameters it would like to receive and receive only those parameters when the signal is sent. The sender can include extra parameters for those handlers which require them without worrying about whether a more generic handler can accept them:
def handle_specific_event( sender, moo ):
"""Handle a simple event, requiring a "moo" parameter"""
print 'Specialized event for %(sender)s moo=%(moo)r'%locals()
dispatcher.connect( handle_specific_event, signal=SIGNAL2, sender=dispatcher.Any )
This connection requires that all senders of the particular signal send a "moo" parameter, but a handler that listens for all events and does not provide a "moo" parameter would silently ignore the sender having passed a "moo".
2 parameters are always available to handler functions if they would like to use them:
| Parameter |
Value |
|---|---|
| sender |
Object from/for which the event was sent, can be dispatcher.Anonymous for anonymous signals |
| signal |
Signal object used when sending |
Positional arguments and named arguments are passed through, but if positional arguments are used, they will fill in the parameters of the receiver in order and cause conflicts if named parameters are specified which match their names. Generally it is advisable to use named arguments when defining sending messages.
OpenGLContext uses PyDispatcher to provide a link between PyVRML97 (model level) and OpenGLContext (the controller and view levels). Changes to fields in the model send events, as do changes to object lists. A cache observes these changes and allows the view/model level to register dependencies on particular fields of particular nodes. The result is that rendering code can cache data extensively and have the caches consistently invalidated when their data-dependencies are changed.