traits.traits_listener Module

Defines classes used to implement and manage various trait listener patterns.

traits.traits_listener.indent(text, first_line=True, n=1, width=4)

Indent lines of text.

Parameters

• text (str) – The text to indent.

• first_line (bool, optional) – If False, then the first line will not be indented (default: True).

• n (int, optional) – The level of indentation (default: 1).

• width (int, optional) – The number of spaces in each level of indentation (default: 4).

Returns

indented

Return type

str

traits.traits_listener.is_not_none(value)

traits.traits_listener.is_none(value)

traits.traits_listener.not_event(value)

class traits.traits_listener.ListenerBase

Bases: object

Abstract base class for both ListenerItem and ListenerGroup.

set_notify(notify)

Set notify state on this listener.

Parameters

notify (bool) – True if this listener should notify, else False.

set_next(next)

Set the child listener for this listener.

Parameters

next (ListenerBase) – The next level (if any) of ListenerBase object to be called when any of our listened to traits is changed:

register(new)

Registers new listeners.

unregister(old)

Unregisters any existing listeners.

handle(object, name, old, new)

Handles a trait change for a simple trait.

handle_list(object, name, old, new)

Handles a trait change for a list trait.

handle_list_items(object, name, old, new)

Handles a trait change for a list traits items.

handle_dict(object, name, old, new)

Handles a trait change for a dictionary trait.

handle_dict_items(object, name, old, new)

Handles a trait change for a dictionary traits items.

class traits.traits_listener.ListenerItem(*, name, metadata_name='', metadata_defined=True, handler=None, wrapped_handler_ref=None, dispatch, priority=False, next=None, type, notify=True, deferred=False, is_anytrait=False, is_list_handler=False)

Bases: traits.traits_listener.ListenerBase

Listener description for a single item.

Parameters

• name (str) – The name of the trait to listen to.

• metadata_name (str, optional) – The name of any metadata that must be present (or not present).

• metadata_defined (bool, optional) – True if the specified metadata needs to be defined; False if the specified metadata needs to be not defined.

• handler (ListenerHandler, optional) – Zero-argument callable that returns the actual handler when called (or Undefined if that handler is no longer available).

• wrapped_handler_ref (weakref.ref, optional) – Weak reference to a ListenerNotifyWrapper wrapping the actual handler.

• dispatch (str) – The dispatch mechanism to use when invoking the handler.

• priority (bool, optional) – True if the handler goes at the beginning of the notification handlers list, else False.

• next (ListenerBase or None, optional) – The next level (if any) of ListenerBase object to be called when any of this object’s listened-to traits is changed. The default is None.

• type (int) – The type of handler being used. One of ANY_LISTENER, SRC_LISTENER, DST_LISTENER.

• notify (bool, optional) – True if changes to this item should generate a notification to the handler; False otherwise. The default is True.

• deferred (bool, optional) – True if registering listeners for items reachable from this listener item should be deferred until the associated trait is first read or set.

• is_anytrait (bool, optional) – True if this is an “anytrait” change listener. False if it creates explicit listeners for each individual trait.

• is_list_handler (bool, optional) – True if the associated handler is a special list handler that handles both “foo” and “foo_items” events. False otherwise.

set_notify(notify)

Set notify state on this listener.

Parameters

notify (bool) – True if this listener should notify, else False.

set_next(next)

Set the child listener for this one.

Parameters

next (ListenerBase) – The next level (if any) of ListenerBase object to be called when any of our listened to traits is changed:

register(new)

Registers new listeners.

unregister(old)

Unregisters any existing listeners.

handle_simple(object, name, old, new)

Handles a trait change for an intermediate link trait.

handle_dst(object, name, old, new)

Handles a trait change for an intermediate link trait when the notification is for the final destination trait.

handle_list(object, name, old, new)

Handles a trait change for a list (or set) trait.

handle_list_items(object, name, old, new)

Handles a trait change for items of a list (or set) trait.

handle_list_items_special(object, name, old, new)

Handles a trait change for items of a list (or set) trait with notification.

handle_dict(object, name, old, new)

Handles a trait change for a dictionary trait.

handle_dict_items(object, name, old, new)

Handles a trait change for items of a dictionary trait.

handle_error(obj, name, old, new)

Handles an invalid intermediate trait change to a handler that must be applied to the final destination object.trait.

class traits.traits_listener.ListenerGroup(*, items)

Bases: traits.traits_listener.ListenerBase

Listener description for a collection of items.

The ListenerParser produces a ListenerGroup rather than a ListenerItem when parsing strings like [abc,def].

Parameters

items (list) – List of ListenerItem objects representing the components of the group.

set_notify(notify)

Set notify state on this listener.

Parameters

notify (bool) – True if this listener should notify, else False.

set_next(next)

Set the child listener for this one.

Parameters

next (ListenerBase) – The next level (if any) of ListenerBase object to be called when any of our listened to traits is changed:

register(new)

Registers new listeners.

unregister(old)

Unregisters any existing listeners.

class traits.traits_listener.ListenerParser(text, *, handler=None, wrapped_handler_ref=None, dispatch='', priority=False, deferred=False, handler_type=0)

Bases: object

property next

The next character from the string being parsed.

property backspace

Backspaces to the last character processed.

property skip_ws

The next non-whitespace character.

property name

The next Python attribute name within the string.

text

The text being parsed.

len_text

The length of the string being parsed.

index

The current parse index within the string.

handler

The handler to be called when any listened-to trait is changed.

wrapped_handler_ref

A weakref ‘wrapped’ version of ‘handler’.

dispatch

The dispatch mechanism to use when invoking the handler.

priority

Does the handler go at the beginning (True) or end (False) of the notification handlers list?

listener

The parsed listener.

parse(deferred, handler_type)

Parses the text and returns the appropriate collection of

ListenerBase objects described by the text.

Parameters

• deferred (bool) – Should registering listeners for items reachable from this listener item be deferred until the associated trait is first read or set?

• handler_type (int) – The type of handler being used; one of {ANY_LISTENER, SRC_LISTENER, DST_LISTENER}.

parse_group(*, terminator, deferred, handler_type)

Parses the contents of a group.

Parameters

• terminator (str or EOS) – Character on which to halt parsing of this item.

• deferred (bool) – Should registering listeners for items reachable from this listener item be deferred until the associated trait is first read or set?

• handler_type (int) – The type of handler being used; one of {ANY_LISTENER, SRC_LISTENER, DST_LISTENER}.

parse_item(*, terminator, deferred, handler_type)

Parses a single, complete listener item or group string.

Parameters

• terminator (str or EOS) – Character on which to halt parsing of this item.

• deferred (bool) – Should registering listeners for items reachable from this listener item be deferred until the associated trait is first read or set?

• handler_type (int) – The type of handler being used; one of {ANY_LISTENER, SRC_LISTENER, DST_LISTENER}.

parse_metadata(item)

Parses the metadata portion of a listener item.

error(msg)

Raises a syntax error.

class traits.traits_listener.ListenerNotifyWrapper(handler, owner, id, listener, target=None)

Bases: traits.trait_notifiers.TraitChangeNotifyWrapper

listener_deleted(ref)

owner_deleted(ref)

class traits.traits_listener.ListenerHandler(handler)

Bases: object

Wrapper for trait change handlers that avoids strong references to methods.

For a bound method handler, this wrapper prevents us from holding a strong reference to the object bound to that bound method. For other callable handlers, we do keep a strong reference to the handler.

When called with no arguments, this object returns either the actual handler, or Undefined if the handler no longer exists because the object it was bound to has been garbage collected.

Parameters

handler (callable) – Object to be called when the relevant trait or traits change.