Welcome to Notifier’s documentation!¶
Notifier¶
In memory pub/sub [1]
- Free software: Apache license
[1] | See: publish–subscribe pattern |
API¶
Classes¶
-
class
notifier.
Notifier
(logger=None)[source]¶ A notification (pub/sub like) helper class.
It is intended to be used to subscribe to notifications of events occurring as well as allow a entity to post said notifications to any associated subscribers without having either entity care about how this notification occurs.
-
ANY
= '*'¶ Kleene star constant that is used to recieve all notifications
-
DISALLOWED_NOTIFICATION_EVENTS
= frozenset(['*'])¶ Events which can not be used to trigger notifications
-
RESERVED_KEYS
= ('details',)¶ Keys that can not be used in callbacks arguments
-
can_be_registered
(event_type)[source]¶ Checks if the event can be registered/subscribed to.
Returns: whether the event_type can be registered/subscribed to. Return type: boolean
-
can_trigger_notification
(event_type)[source]¶ Checks if the event can trigger a notification.
Parameters: event_type – event that needs to be verified Returns: whether the event can trigger a notification Return type: boolean
-
deregister
(event_type, callback, details_filter=None)[source]¶ Remove a single listener bound to event
event_type
.Parameters: - event_type – deregister listener bound to event_type
- callback – callback that was used during registration
- details_filter – details filter that was used during registration
Returns: if a listener was deregistered
Return type: boolean
-
deregister_by_uuid
(event_type, uuid)[source]¶ Remove a single listener bound to event
event_type
.Parameters: - event_type – deregister listener bound to event_type
- uuid – uuid of listener to remove
Returns: if the listener was deregistered
Return type: boolean
-
deregister_event
(event_type)[source]¶ Remove a group of listeners bound to event
event_type
.Parameters: event_type – deregister listeners bound to event_type Returns: how many callbacks were deregistered Return type: int
-
is_registered
(event_type, callback, details_filter=None)[source]¶ Check if a callback is registered.
Parameters: - event_type – event type callback was registered to
- callback – callback that was used during registration
- details_filter – details filter that was used during registration
Returns: if the callback is registered
Return type: boolean
-
listeners_iter
()[source]¶ Return an iterator over the mapping of event => listeners bound.
The listener list(s) returned should not be mutated.
NOTE(harlowja): Each listener in the yielded (event, listeners) tuple is an instance of the
Listener
type, which itself wraps a provided callback (and its details filter callback, if any).
-
notify
(event_type, details)[source]¶ Notify about an event occurrence.
All callbacks registered to receive notifications about given event type will be called. If the provided event type can not be used to emit notifications (this is checked via the
can_be_registered()
method) then a value error will be raised.Parameters: - event_type – event type that occurred
- details (dictionary) – additional event details dictionary passed to callback keyword argument with the same name
Returns: a future object that will have a result named tuple with contents being (total listeners called, how many listeners were successfully called, how many listeners were not successfully called); do note that the result may be delayed depending on internal executor used.
-
register
(event_type, callback, args=None, kwargs=None, details_filter=None, weak=False)[source]¶ Register a callback to be called when event of a given type occurs.
Callback will be called with provided
args
andkwargs
and when event type occurs (or on any event ifevent_type
equals toANY
). It will also get additional keyword argument,details
, that will hold event details provided to thenotify()
method (if a details filter callback is provided then the target callback will only be triggered if the details filter callback returns a truthy value).Parameters: - event_type – event type to get triggered on
- callback – function callback to be registered.
- args (list) – non-keyworded arguments
- kwargs (dictionary) – key-value pair arguments
- weak (bool) – if the callback retained should be referenced via a weak reference or a strong reference (defaults to holding a strong reference)
Returns: the listener that was registered
Return type:
-
-
class
notifier.
RestrictedNotifier
(watchable_events, allow_any=True, logger=None)[source]¶ A notification class that restricts events registered/triggered.
NOTE(harlowja): This class unlike
Notifier
restricts and disallows registering callbacks for event types that are not declared when constructing the notifier.
-
class
notifier.
Listener
(callback, args=None, kwargs=None, details_filter=None, weak=False)[source]¶ Immutable helper that represents a notification listener/target.
-
args
¶ Tuple of positional arguments to use in future calls.
-
callback
¶ Callback (may be none) to call with event + details.
If the callback is maintained via a weak reference, and that weak reference has been collected, this will be none instead of an actual callback.
-
dead
¶ Whether the callback no longer exists.
If the callback is maintained via a weak reference, and that weak reference has been collected, this will be true instead of false.
-
details_filter
¶ Callback (may be none) to call to discard events + details.
-
is_equivalent
(callback, details_filter=None)[source]¶ Check if the callback provided is the same as the internal one.
Parameters: - callback – callback used for comparison
- details_filter – callback used for comparison
Returns: false if not the same callback, otherwise true
Return type: boolean
-
kwargs
¶ Frozen dictionary of keyword arguments to use in future calls.
-
uuid
¶ Unique identifier that uniquely identifies this listener.
-
Functions¶
-
notifier.
register_deregister
(*args, **kwds)[source]¶ Context manager that registers a callback, then deregisters on exit.
- NOTE(harlowja): if the callback is none, then this registers nothing, which
- is different from the behavior of the
register
method which will not accept none as it is not callable...
Constants¶
-
Notifier.
ANY
= '*' Kleene star constant that is used to recieve all notifications