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.

__module__ = 'fsl.utils.notifier'

__weakref__

list of weak references to the object (if defined)

class fsl.utils.notifier._Listener(name, callback, topic, runOnIdle)

Bases: object

This class is used internally by the Notifier class to store references to callback functions.

__init__(name, callback, topic, runOnIdle)

property callback

Returns the callback function, or None if it has been garbage-collected.

property expectsArguments

Returns True if the listener function needs to be passed arguments, False otherwise. Listener functions can be defined to accept either zero arguments, or a set of positional arguments - see Notifier.register() for details.

__str__()

Return str(self).

__repr__()

Return repr(self).

__dict__ = mappingproxy({'__module__': 'fsl.utils.notifier', '__doc__': 'This class is used internally by the :class:`.Notifier` class to\n    store references to callback functions.\n    ', '__init__': <function _Listener.__init__>, 'callback': <property object>, 'expectsArguments': <property object>, '__str__': <function _Listener.__str__>, '__repr__': <function _Listener.__repr__>, '__dict__': <attribute '__dict__' of '_Listener' objects>, '__weakref__': <attribute '__weakref__' of '_Listener' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.notifier'

__weakref__

list of weak references to the object (if defined)

class fsl.utils.notifier.Notifier(*args, **kwargs)

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.

static __new__(cls, *args, **kwargs)

Initialises a dictionary of listeners on a new Notifier instance.

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 either zero arguments, or three 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().

__getListeners(topic)

Called by notify(). Returns all listeners which should be notified for the specified topic.

__annotations__ = {}

__dict__ = mappingproxy({'__module__': 'fsl.utils.notifier', '__doc__': 'The ``Notifier`` class is a mixin which provides simple notification\n    capability. Listeners can be registered/deregistered to listen via the\n    :meth:`register` and :meth:`deregister` methods, and notified via the\n    :meth:`notify` method. Listeners can optionally listen on a specific\n    *topic*, or be notified for all topics.\n\n    .. note:: The ``Notifier`` class stores ``weakref`` references to\n              registered callback functions, using the\n              :class:`.WeakFunctionRef` class.\n    ', '__new__': <staticmethod(<function Notifier.__new__>)>, 'register': <function Notifier.register>, 'deregister': <function Notifier.deregister>, 'enable': <function Notifier.enable>, 'disable': <function Notifier.disable>, 'isEnabled': <function Notifier.isEnabled>, 'enableAll': <function Notifier.enableAll>, 'disableAll': <function Notifier.disableAll>, 'isAllEnabled': <function Notifier.isAllEnabled>, 'skipAll': <function Notifier.skipAll>, 'skip': <function Notifier.skip>, 'notify': <function Notifier.notify>, '_Notifier__getListeners': <function Notifier.__getListeners>, '__dict__': <attribute '__dict__' of 'Notifier' objects>, '__weakref__': <attribute '__weakref__' of 'Notifier' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.notifier'

__weakref__

list of weak references to the object (if defined)