Traits User Manual
Previous: 3.1.1 Example of a Dynamic Notification Handler Table of Contents Next: 3.1.3 Notification Handler Signatures
Traits User Manual
1 Introduction
1.1 What Are Traits?
1.2 Background
2 Defining Traits: Initialization and Validation
2.1 Predefined Traits
2.1.1 Predefined Traits for Simple Types
2.1.2 Other Predefined Traits
2.2 Trait Metadata
2.2.1 Internal Metadata Attributes
2.2.2 Recognized Metadata Attributes
2.2.3 Accessing Metadata Attributes
3 Trait Notification
3.1 Dynamic Notification
3.1.1 Example of a Dynamic Notification Handler
3.1.2 The name Parameter
3.1.3 Notification Handler Signatures
3.1.4 Dynamic Handler Special Cases
3.2 Static Notification
3.2.1 Handler Decorator
3.2.2 Specially-named Notification Handlers
3.2.3 Attribute-specific Handler Signatures
3.2.4 General Static Handler Signatures
3.3 Trait Events
3.4 Undefined Object
4 Deferring Trait Definitions
4.1 DelegatesTo
4.2 PrototypedFrom
4.3 Keyword Parameters
4.3.1 Prefix Keyword
4.3.2 Listenable Keyword
4.4 Notification with Deferring
5 Custom Traits
5.1 Trait Subclassing
5.1.1 Defining a Trait Type
5.1.2 Defining a Trait Property
5.1.3 Other TraitType Members
5.2 The Trait() Factory Function
5.2.1 Trait () Parameters
5.2.2 Mapped Traits
5.3 Trait Handlers
5.3.1 TraitPrefixList
5.3.2 TraitPrefixMap
5.4 Custom Trait Handlers
5.4.1 Example Custom Trait Handler
6 Advanced Topics
6.1 Initialization and Validation Revisited
6.1.1 Dynamic Initialization
6.1.2 Overriding Default Values in a Subclass
6.1.3 Reusing Trait Definitions
6.1.4 Trait Attribute Definition Strategies
6.1.5 Type-Checked Methods
6.2 Interfaces
6.2.1 Defining an Interface
6.2.2 Implementing an Interface
6.2.3 Using Interfaces
6.3 Adaptation
6.3.1 Defining Adapters
6.3.2 Using Adapters
6.3.3 Controlling Adaptation
6.4 Property Traits
6.4.1 Property Factory Function
6.4.2 Caching a Property Value
6.5 Persistence
6.5.1 Pickling HasTraits Objects
6.5.2 Predefined Transient Traits
6.5.3 Overriding __getstate__()
6.5.4 Unpickling HasTraits Objects
6.5.5 Overriding __setstate__()
6.6 Useful Methods on HasTraits
6.6.1 add_trait()
6.6.2 clone_traits()
6.6.3 set()
6.6.4 add_class_trait()
6.7 Performance Considerations of Traits

3.1.2        The name Parameter

The name parameter of on_trait_change() and on_trait_event() provides significant flexibility in specifying the name or names of one or more trait attributes that the handler applies to. It supports syntax for specifying names of trait attributes not just directly on the current object, but also on sub-objects referenced by the current object.

The name parameter can take any of the following values:

·    Omitted, None, or 'anytrait': The handler applies to any trait attribute on the object.

·    A name or list of names: The handler applies to each trait attribute on the object with the specified names.

·    An extended name or list of extended names: The handler applies to each trait attribute that matches the specified extended names.

3.1.2.1          Syntax

Extended names use the following syntax:

xname  ::= xname2['.'xname2]*

 

xname2 ::=

          ( xname3 | '['xname3[','xname3]*']' ) ['*']

 

xname3 ::= xname | ['+'|'-'][name] |

             name['?' | ('+'|'-')[name]]

A name is any valid Python attribute name.

3.1.2.2          Semantics

Table 4 Semantics of extended name notation

Pattern

Meaning

item1.item2

A trait named item1 contains an object (or objects, if item1 is a list or dictionary), with a trait named item2. Changes to either item1 or item2 cause a notification to be generated.

item1:item2

A trait named item1 contains an object (or objects, if item1 is a list or dictionary), with a trait named item2. Changes to item2 cause a notification, while changes to item1 do not (i.e., the ‘:’ indicates that changes to the link object should not be reported.

[item1, item2, …, itemN]

A list that matches any of the specified items. Note that at the topmost level, the surrounding square brackets are optional.

item[]

A trait named item is a list. Changes to item or to its members causes a notification.

name?

If the current object does not have an attribute called name, the reference can be ignored. If the ‘?’ character is omitted, the current object must have a trait called name; otherwise, an exception is raised.

prefix+

Matches any trait attribute on the object whose name begins with prefix.

+metadata_name

Matches any trait on the object that has a metadata attribute called metadata_name.

-metadata_name

Matches any trait on the current object that does not have a metadata attribute called metadata_name.

prefix+metadata_name

Matches any trait on the object whose name begins with prefix and that has a metadata attribute called metadata_name.

prefix-metadata_name

Matches any trait on the object whose name begins with prefix and that does not have a metadata attribute called metadata_name.

+

Matches all traits on the object.

pattern*

Matches object graphs where pattern occurs one or more times. This option is useful for setting up listeners on recursive data structures like trees or linked lists.

ExamplesTable 5 Examples of extended name notation

Example

Meaning

'foo, bar, baz'

Matches object.foo, object.bar, and object.baz.

['foo', 'bar', 'baz']

Equivalent to 'foo, bar, baz', but may be useful in cases where the individual items are computed.

'foo.bar.baz'

Matches object.foo.bar.baz

'foo.[bar,baz]'

Matches object.foo.bar and object.foo.baz

'foo[]'

Matches a list trait on object named foo.

'([left,right]).
name*'

Matches the name trait of each tree node object that is linked from the left or right traits of a parent node, starting with the current object as the root node. This pattern also matches the name trait of the current object, as the left and right modifiers are optional.

'+dirty'

Matches any trait on the current object that has a metadata attribute named dirty set.

'foo.+dirty'

Matches any trait on object.foo that has a metadata attribute named dirty set.

'foo.[bar,-dirty]'

Matches object.foo.bar or any trait on object.foo that does not have a metadata attribute named dirty set.

For a pattern that references multiple objects, any of the intermediate (non-final) links can traits of type Instance, List, or Dict. In the case of List or Dict traits, the subsequent portion of the pattern is applied to each item in the list or value in the dictionary. For example, if self.children is a list, a handler set for 'children.name' listens for changes to the name trait for each item in the self.children list.

The handler routine is also invoked when items are added or removed from a list or dictionary, because this is treated as an implied change to the item’s trait being monitored.

Previous: 3.1.1 Example of a Dynamic Notification Handler Table of Contents Next: 3.1.3 Notification Handler Signatures
Traits User Manual