Traits User Manual
Previous: 5.4 Custom Trait Handlers Table of Contents Next: 6 Advanced Topics
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

5.4.1        Example Custom Trait Handler

The following example defines the OddInt trait (also implemented as a trait type in Section 5.1.1) using a TraitHandler subclass.

# custom_traithandler.py --- Example of a custom TraitHandler

import types

from enthought.traits.api import TraitHandler

 

class TraitOddInteger(TraitHandler):

    def validate(self, object, name, value):

        if ((type(value) is types.IntType) and

            (value > 0) and ((value % 2) == 1)):

            return value

        self.error(object, name, value)

 

    def info(self):

        return 'a positive odd integer'

An application could use this new trait handler to define traits such as the following:

# use_custom_th.py --- Example of using a custom TraitHandler

from enthought.traits.api import HasTraits, Trait, TraitRange

from custom_traithandler import TraitOddInteger

 

class AnOddClass(HasTraits):

    oddball = Trait(1, TraitOddInteger())

    very_odd = Trait(-1, TraitOddInteger(),

                         TraitRange(-10, -1))

The following example demonstrates why the info() method returns a phrase rather than a complete sentence:

>>> from use_custom_th import AnOddClass

>>> odd_stuff = AnOddClass()

>>> odd_stuff.very_odd = 0

Traceback (most recent call last):

  File "test.py", line 25, in ?

    odd_stuff.very_odd = 0  

  File "C:\wrk\src\lib\enthought\traits\traits.py", line 1119, in validate

    raise TraitError, excp

traits.traits.TraitError: The 'very_odd' trait of a AnOddClass instance must be a positive odd integer or an integer in the range from -10 to -1, but a value of 0 was specified.

Note the emphasized result returned by the info() method, which is embedded in the exception generated by the invalid assignment.
Previous: 5.4 Custom Trait Handlers Table of Contents Next: 6 Advanced Topics
Traits User Manual