4.6. py4j.signals — Py4J Signals API

The py4j.signals module contains classes that enables the creation of signals, i.e., events that can be sent to “receivers”. A receiver must connect to a signal beforehand and can optionally specify from which sender it should receive signals.

Here is a full usage example:

# Declare a signal
server_connection_stopped = Signal()
"""Signal sent when a Python (Callback) Server connection is stopped.

Will supply the ``connection`` argument, an instance of CallbackConnection.

The sender is the CallbackServer instance.
"""

server = ...
connection = ...

# Create a receiver
def on_connection_stopped(sender, **kwargs):
    connection = kwargs["connection"]
    # ...

# Connect the receiver to the signal. Only signals sent from
# server will be sent to on_connection_stopped.
server_connection_stopped.connect(on_connection_stopped, sender=server)

# Send a signal to the receivers. If one receiver raises an error,
# the error is propagated back and other receivers won't receive the
# signal.
server_connection_stopped.send(sender=server, connection=connection)

4.6.1. Signal

class py4j.signals.Signal

Basic signal class that can register receivers (listeners) and dispatch events to these receivers.

As opposed to many signals libraries, receivers are not stored as weak references, so it is us to the client application to unregister them.

Greatly inspired from Django Signals: https://github.com/django/django/blob/master/django/dispatch/dispatcher.py

connect(receiver, sender=None, unique_id=None)

Registers a receiver for this signal.

The receiver must be a callable (e.g., function or instance method) that accepts named arguments (i.e., **kwargs).

In case that the connect method might be called multiple time, it is best to provide the receiver with a unique id to make sure that the receiver is not registered more than once.

Parameters:

• receiver – The callable that will receive the signal.

• sender – The sender to which the receiver will respond to. If None, signals from any sender are sent to this receiver

• unique_id – The unique id of the callable to make sure it is not registered more than once. Optional.

disconnect(receiver, sender=None, unique_id=None)

Unregisters a receiver for this signal.

Parameters:

• receiver – The callable that was registered to receive the signal.

• unique_id – The unique id of the callable if it was provided. Optional.

Returns:

True if the receiver was found and disconnected. False otherwise.

Return type:

bool

send(sender, **params)

Sends the signal to all connected receivers.

If a receiver raises an error, the error is propagated back and interrupts the sending processing. It is thus possible that not all receivers will receive the signal.

Param:

named parameters to send to the receivers.

Param:

the sender of the signal. Optional.

Returns:

List of (receiver, response) from receivers.

Return type:

list