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 byNotifier.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 theregister()
andderegister()
methods, and notified via thenotify()
method. Listeners can optionally listen on a specific topic, or be notified for all topics.Note
The
Notifier
class storesweakref
references to registered callback functions, using theWeakFunctionRef
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:
topic – Optional topic on which to listen for notifications.
runOnIdle – If
True
, this listener will be called on the main thread, via theidle.idle()
function. Otherwise this function will be called directly by thenotify()
method. Defaults toFalse
.
- Raises
A
Registered
error if a listener with the givenname
is already registered on the giventopic
.
-
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 iftopic=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 viaidle.idle()
. Other listeners are called directly. Seeregister()
.
-