PyDispatcher

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 SourceForge project aims to include various enhancements to the recipe developed during use in various applications.

To be more concrete about what PyDispatcher does for you:

provides a centralized service for delivering messages to registered objects (in the local process). It allows you to register any number of functions (callable objects) which can receive signals from senders.

registration can be for all senders, particular sending objects, or "anonymous" messages (messages where the sender is None)
registration can be for any signal, or particular signals
a single signal will be delivered to all appropriate registered receivers, so that multiple registrations do not interfere with each other

there is no requirement for the sender or receiver to be dispatcher-aware. Any Python object save the None object can act as a sender, and any callable object can act as a receiver. There is no need to inherit from a particular class or provide a particular interface on the object.
the system uses weak references to receivers wherever possible

object lifetimes are not affected by PyDispatcher registrations (that is, when your object goes away, the registrations related to the object also go away).
references to common transient objects (in particular instance methods) are stored as compound weak references.
weak references can be disabled on a registration-by-registration basis

allows rich signal types, signals are simply hashable objects used to store and retrieve sub-tables, they are otherwise opaque to the dispatcher mechanism
allows sending more information when sending than any particular receiver can handle, dispatcher automatically culls those arguments which are not appropriate for the particular receiver. This allows registering very simple functions dealing with general messages, while still allowing natural passing of arguments to higher level functions.

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.

Acquisition and Installation

PyDispatcher is available as a standard Python distutils installation package from the SourceForge project file repository. To install, unzip the source archive into a temporary directory and run:

python setup.py install

PyDispatcher does not include any binary packages, so there should be no issues in installation. To use the CVS version of PyDispatcher (useful for developers of PyDispatcher), simply check out the module to a directory on your PythonPath.

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.

Documentation

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.

Release Notes

Version 1.0.2

Fixes another memory leak, again wrt the back-reference table

Version 1.0.1

Fixes 2 memory leaks, one regarding the back-reference table for receivers, the other being a failure to register all receivers beyond the first for deletion

Version 1.0.0

Initial SourceForge release with restructured codebase