The Traits package for the Python language allows Python programmers to use a special kind of type definition called a trait. This document introduces the concepts behind, and usage of, the Traits package.
For more information on the Traits package, refer to the Traits web page. This page contains links to downloadable packages, the source code repository, and the Traits development website. Additional documentation for the Traits package is available from the Traits web page, including:
A trait is a type definition that can be used for normal Python object attributes, giving the attributes some additional characteristics:
A class can freely mix trait-based attributes with normal Python attributes, or can opt to allow the use of only a fixed or open set of trait attributes within the class. Trait attributes defined by a class are automatically inherited by any subclass derived from the class.
The following example  illustrates each of the features of the Traits package. These features are elaborated in the rest of this guide.
# all_traits_features.py --- Shows primary features of the Traits # package from enthought.traits.api import Delegate, HasTraits, Instance,\ Int, Str import enthought.traits.ui class Parent ( HasTraits ): # INITIALIZATION: last_name' is initialized to '': last_name = Str( '' ) class Child ( HasTraits ): age = Int # VALIDATION: 'father' must be a Parent instance: father = Instance( Parent ) # DELEGATION: 'last_name' is delegated to father's 'last_name': last_name = Delegate( 'father' ) # NOTIFICATION: This method is called when 'age' changes: def _age_changed ( self, old, new ): print 'Age changed from %s to %s ' % ( old, new ) # Set up the example: joe = Parent() joe.last_name = 'Johnson' moe = Child() moe.father = joe # DELEGATION in action: print "Moe's last name is %s " % moe.last_name # Result: # Moe's last name is Johnson # NOTIFICATION in action moe.age = 10 # Result: # Age changed from 0 to 10 # VISUALIZATION: Displays a UI for editing moe's attributes # (if a supported GUI toolkit is installed) moe.configure_traits()
In addition, traits can be used to define type-checked method signatures. The Traits package can ensure that the arguments and return value of a method invocation match the traits defined for the parameters and return value in the method signature. This feature is described in Type-Checked Methods.
Python does not require the data type of variables to be declared. As any experienced Python programmer knows, this flexibility has both good and bad points. The Traits package was developed to address some of the problems caused by not having declared variable types, in those cases where problems might arise. In particular, the motivation for Traits came as a direct result of work done on Chaco, an open source scientific plotting package.
Chaco provides a set of high-level plotting objects, each of which has a number of user-settable attributes, such as line color, text font, relative location, and so on. To make the objects easy for scientists and engineers to use, the attributes attempt to accept a wide variety and style of values. For example, a color-related attribute of a Chaco object might accept any of the following as legal values for the color red:
Thus, the user might write:
plotitem.color = 'red'
In a predecessor to Chaco, providing such flexibility came at a cost:
So, one of the main goals of the Traits package is to provide a form of type checking that:
In the process of meeting these design goals, the Traits package evolved into a useful component in its own right, satisfying all of the above requirements and introducing several additional, powerful features of its own. In projects where the Traits package has been used, it has proven valuable for enhancing programmers’ ability to understand code, during both concurrent development and maintenance.
The Traits 3.0 package works with version 2.4 and later of Python, and is similar in some ways to the Python property language feature. Standard Python properties provide the similar capabilities to the Traits package, but with more work on the part of the programmer.
All code examples in this guide that include a file name are also available as examples in the tutorials/doc_examples/examples subdirectory of the Traits docs directory. You can run them individually, or view them in a tutorial program by running:
python <Traits dir>/enthought/traits/tutor/tutor.py <Traits dir>/docs/tutorials/doc_examples