PyDispatcher

Warnings

• gotcha Receiver functions must accept `sender` as the first positional argument and `**kwargs` for any additional arguments. Failing to include `**kwargs` can cause runtime errors if the signal sender later provides arguments not explicitly defined in the receiver's signature.
  Fix: Always define receiver functions with the signature `def receiver_func(sender, **kwargs):` to ensure forward compatibility and prevent argument mismatch errors. Extract specific arguments from `kwargs` inside the function body.
• gotcha The `dispatcher.connect` method defaults to listening for signals from `dispatcher.Any` sender, while `dispatcher.send` defaults to sending signals with `dispatcher.Anonymous` sender. This difference can lead to signals not being received if not explicitly specified.
  Fix: Explicitly define the `sender` argument in both `dispatcher.connect` and `dispatcher.send` to match desired behavior. Use `dispatcher.Any` to listen for all senders, and specify a concrete sender object or `dispatcher.Anonymous` when sending.
• gotcha While `dispatcher.send` accepts positional arguments, it is generally recommended to use keyword arguments for all data passed with a signal. Positional arguments can lead to conflicts with receiver signatures if not carefully managed.
  Fix: Pass all data to `dispatcher.send` using keyword arguments (e.g., `signal=MY_SIGNAL, sender=self, data='value'`). This improves clarity and avoids potential mismatches with receiver function signatures.
• breaking Disconnecting a receiver within another receiver's execution flow might prevent subsequent receivers for the same signal from being called.
  Fix: Avoid disconnecting receivers dynamically within the signal processing chain. If necessary, defer disconnection until after all signal processing for the current event cycle has completed.
• gotcha There's an open issue where PyDispatcher's internal `robustApply` module may not fully support Python's keyword-only arguments, which could impact how signal arguments are processed if receivers rely heavily on them.
  Fix: Be mindful when using keyword-only arguments in receiver functions. Test thoroughly if your signal handlers depend on this feature. Where possible, define keyword arguments with defaults or handle them within `**kwargs`.

Install

• pip install pydispatcher Install PyDispatcher

Imports

• dispatcher

  from pydispatch import dispatcher

  The primary API is exposed through the `dispatcher` object, imported directly from the `pydispatch` package.

Quickstart

This example demonstrates how to define a signal, connect multiple receiver functions to it (including one that expects specific keyword arguments), and send the signal from a custom sender object. It also shows how to disconnect a receiver.

from pydispatch import dispatcher

# Define a signal name (can be any hashable object)
MY_SIGNAL = 'my_custom_event'

def my_receiver(sender, **kwargs):
    """A function to receive the signal."""
    print(f"Receiver got signal from {sender}: {kwargs}")

def another_receiver(sender, data, event_type, **kwargs):
    """Another receiver that expects specific keyword args."""
    print(f"Another receiver got signal from {sender}: data={data}, type={event_type}")

class MySender:
    def __init__(self, name):
        self.name = name

    def trigger_event(self):
        print(f"\n{self.name} is sending MY_SIGNAL...")
        # Send the signal, specifying the sender and any keyword arguments
        dispatcher.send(signal=MY_SIGNAL, sender=self, data='important data', event_type='click')

# Connect receivers to the signal
# Use dispatcher.Any to receive signals from any sender
dispatcher.connect(receiver=my_receiver, signal=MY_SIGNAL, sender=dispatcher.Any)
dispatcher.connect(receiver=another_receiver, signal=MY_SIGNAL, sender=MySender)

# Create a sender instance and trigger the event
sender_instance = MySender(name="ComponentA")
sender_instance.trigger_event()

# Disconnect a receiver (optional)
dispatcher.disconnect(receiver=my_receiver, signal=MY_SIGNAL, sender=dispatcher.Any)