fsl.utils.notifier

This module provides the Notifier class, intended to be used as a mixin for providing a simple notification API.

fsl.utils.notifier.DEFAULT_TOPIC = 'default'

Topic used when the caller does not specify one when registering, deregistering, or notifying listeners.

exception fsl.utils.notifier.Registered

Bases: Exception

Exception raised by Notifier.register() when an attempt is made to register a listener with a name that is already registered.

class fsl.utils.notifier.Notifier

Bases: object

The Notifier class is a mixin which provides simple notification capability. Listeners can be registered/deregistered to listen via the register() and deregister() methods, and notified via the notify() method. Listeners can optionally listen on a specific topic, or be notified for all topics.

Note

The Notifier class stores weakref references to registered callback functions, using the WeakFunctionRef class.

register(name, callback, topic=None, runOnIdle=False)

Register a listener with this Notifier.

Parameters:

• name – A unique name for the listener.
• callback –

  The function to call - must accept two positional arguments:

  • this Notifier instance.
  • The topic, which may be None - see notify().
  • A value, which may be None - see notify().

• topic – Optional topic on which to listen for notifications.
• runOnIdle – If True, this listener will be called on the main thread, via the idle.idle() function. Otherwise this function will be called directly by the notify() method. Defaults to False.

Raises:

A Registered error if a listener with the given name is already registered on the given topic.

deregister(name, topic=None)

De-register a listener that has been previously registered with this Notifier.

Parameters:

• name – Name of the listener to de-register.
• topic – Topic on which the listener was registered.

enable(name, topic=None, enable=True)

Enables the specified listener.

disable(name, topic=None)

Disables the specified listener.

isEnabled(name, topic=None)

Returns True if the specified listener is enabled, False otherwise.

enableAll(topic=None, state=True)

Enable/disable all listeners for the specified topic.

Parameters:

• topic – Topic to enable/disable listeners on. If None, all listeners are enabled/disabled.
• state – State to set listeners to.

disableAll(topic=None)

Disable all listeners for the specified topic (or None to disable all listeners).

isAllEnabled(topic=None)

Returns True if all listeners for the specified topic (or all listeners if topic=None) are enabled, False otherwise.

skipAll(topic=None)

Context manager which disables all listeners for the specified topic, and restores their state before returning.

Parameters:topic – Topic to skip listeners on. If None, notification is disabled for all topics.

skip(name, topic=None)

Context manager which disables the speciifed listener, and restores its state before returning.

You can use this method if you have some code which triggers a notification, but you do not your own listener to be notified. For example:

def __myListener(*a):
    pass

notifier.register('myListener', __myListener)

with notifier.skip('myListener'):
    # if a notification is triggered
    # by the code here, the __myListener
    # function will not be called.

Parameters:

• name – Name of the listener to skip
• topic – Topic or topics that the listener is registered on.

notify(*args, **kwargs)

Notify all registered listeners of this Notifier.

The documented arguments must be passed as keyword arguments.

Parameters:

• topic – The topic on which to notify. Default listeners are always notified, regardless of the specified topic.
• value – A value passed through to the registered listener functions. If not provided, listeners will be passed a value of None.

All other arguments passed to this method are ignored.

Note

Listeners registered with runOnIdle=True are called via idle.idle(). Other listeners are called directly. See register().