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)

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)

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)

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

copy()

Clones this notifier (and its bound listeners).

deregister(event_type, callback, details_filter=None)

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)

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)

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)

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()

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)

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)

Register a callback to be called when event of a given type occurs.

Callback will be called with provided args and kwargs and when event type occurs (or on any event if event_type equals to ANY). It will also get additional keyword argument, details, that will hold event details provided to the notify() 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:

Listener

reset()

Forget all previously registered callbacks.

class notifier.RestrictedNotifier(watchable_events, allow_any=True, logger=None)

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.

can_be_registered(event_type)

Checks if the event can be registered/subscribed to.

Parameters:event_type – event that needs to be verified Returns:whether the event can be registered/subscribed to Return type:boolean

events_iter()

Returns iterator of events that can be registered/subscribed to.

NOTE(harlowja): does not include back the ANY event type as that meta-type is not a specific event but is a capture-all that does not imply the same meaning as specific event types.

class notifier.Listener(callback, args=None, kwargs=None, details_filter=None, weak=False)

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)

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)

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

Release Notes

• CHANGES

Indices and tables

• Index
• Module Index
• Search Page