| 1 |
============ |
| 2 |
Introduction |
| 3 |
============ |
| 4 |
The Traits package for the Python language allows Python programmers to use |
| 5 |
a special kind of type definition called a trait. This document introduces the |
| 6 |
concepts behind, and usage of, the Traits package. |
| 7 |
|
| 8 |
For more information on the Traits package, refer to the `Traits GitHub |
| 9 |
repository <http://github.com/enthought/traits>`_. For additional documentation |
| 10 |
on the Traits package, refer to the `Traits API Reference |
| 11 |
<https://docs.enthought.com/traits/traits_api_reference/index.html>`_ |
| 12 |
|
| 13 |
What Are Traits? |
| 14 |
---------------- |
| 15 |
A trait is a type definition that can be used for normal Python object |
| 16 |
attributes, giving the attributes some additional characteristics: |
| 17 |
|
| 18 |
.. index:: initialization |
| 19 |
|
| 20 |
* **Initialization**: A trait has a *default value*, which is |
| 21 |
automatically set as the initial value of an attribute, before its first |
| 22 |
use in a program. |
| 23 |
|
| 24 |
.. index:: validation |
| 25 |
|
| 26 |
* **Validation**: A trait attribute is *explicitly typed*. The type of a |
| 27 |
trait-based attribute is evident in the code, and only values that meet a |
| 28 |
programmer-specified set of criteria (i.e., the trait definition) can be |
| 29 |
assigned to that attribute. Note that the default value need not meet the |
| 30 |
criteria defined for assignment of values. Traits 4.0 also supports defining |
| 31 |
and using abstract interfaces, as well as adapters between interfaces. |
| 32 |
|
| 33 |
.. index:: deferral |
| 34 |
|
| 35 |
* **Deferral**: The value of a trait attribute can be contained either |
| 36 |
in the defining object or in another object that is *deferred to* by the |
| 37 |
trait. |
| 38 |
|
| 39 |
.. index:: notification |
| 40 |
|
| 41 |
* **Notification**: Setting the value of a trait attribute can *notify* |
| 42 |
other parts of the program that the value has changed. |
| 43 |
|
| 44 |
.. index:: visualization |
| 45 |
|
| 46 |
* **Visualization**: User interfaces that allow a user to *interactively |
| 47 |
modify* the values of trait attributes can be automatically constructed using |
| 48 |
the traits' definitions. This feature requires that a supported GUI |
| 49 |
toolkit be installed. However, if this feature is not used, the Traits package |
| 50 |
does not otherwise require GUI support. For details on the visualization |
| 51 |
features of Traits, see the `TraitsUI User Manual |
| 52 |
<http://docs.enthought.com/traitsui/traitsui_user_manual/index.html>`_. |
| 53 |
|
| 54 |
A class can freely mix trait-based attributes with normal Python attributes, |
| 55 |
or can opt to allow the use of only a fixed or open set of trait attributes |
| 56 |
within the class. Trait attributes defined by a class are automatically |
| 57 |
inherited by any subclass derived from the class. |
| 58 |
|
| 59 |
The following example [1]_ illustrates each of the features of the Traits |
| 60 |
package. These features are elaborated in the rest of this guide. |
| 61 |
|
| 62 |
.. index:: examples; Traits features |
| 63 |
|
| 64 |
:: |
| 65 |
|
| 66 |
# all_traits_features.py --- Shows primary features of the Traits |
| 67 |
# package |
| 68 |
|
| 69 |
from traits.api import Delegate, HasTraits, Instance,\ |
| 70 |
Int, Str |
| 71 |
class Parent ( HasTraits ): |
| 72 |
|
| 73 |
# INITIALIZATION: last_name' is initialized to '': |
| 74 |
last_name = Str( '' ) |
| 75 |
|
| 76 |
|
| 77 |
class Child ( HasTraits ): |
| 78 |
|
| 79 |
age = Int |
| 80 |
|
| 81 |
# VALIDATION: 'father' must be a Parent instance: |
| 82 |
father = Instance( Parent ) |
| 83 |
|
| 84 |
# DELEGATION: 'last_name' is delegated to father's 'last_name': |
| 85 |
last_name = Delegate( 'father' ) |
| 86 |
|
| 87 |
# NOTIFICATION: This method is called when 'age' changes: |
| 88 |
def _age_changed ( self, old, new ): |
| 89 |
print('Age changed from %s to %s ' % ( old, new )) |
| 90 |
|
| 91 |
# Set up the example: |
| 92 |
joe = Parent() |
| 93 |
joe.last_name = 'Johnson' |
| 94 |
moe = Child() |
| 95 |
moe.father = joe |
| 96 |
|
| 97 |
# DELEGATION in action: |
| 98 |
print("Moe's last name is %s " % moe.last_name) |
| 99 |
# Result: |
| 100 |
# Moe's last name is Johnson |
| 101 |
|
| 102 |
# NOTIFICATION in action |
| 103 |
moe.age = 10 |
| 104 |
# Result: |
| 105 |
# Age changed from 0 to 10 |
| 106 |
|
| 107 |
# VISUALIZATION: Displays a UI for editing moe's attributes |
| 108 |
# (if a supported GUI toolkit is installed) |
| 109 |
moe.configure_traits() |
| 110 |
|
| 111 |
Background |
| 112 |
---------- |
| 113 |
Python does not require the data type of variables to be declared. As any |
| 114 |
experienced Python programmer knows, this flexibility has both good and bad |
| 115 |
points. The Traits package was developed to address some of the problems |
| 116 |
caused by not having declared variable types, in those cases where problems |
| 117 |
might arise. In particular, the motivation for Traits came as a direct result |
| 118 |
of work done on Chaco, an open source scientific plotting package. |
| 119 |
|
| 120 |
.. index:: Chaco |
| 121 |
|
| 122 |
Chaco provides a set of high-level plotting objects, each of which has a number |
| 123 |
of user-settable attributes, such as line color, text font, relative location, |
| 124 |
and so on. To make the objects easy for scientists and engineers to use, the |
| 125 |
attributes attempt to accept a wide variety and style of values. For example, |
| 126 |
a color-related attribute of a Chaco object might accept any of the following |
| 127 |
as legal values for the color red: |
| 128 |
|
| 129 |
* 'red' |
| 130 |
* 0xFF0000 |
| 131 |
* ( 1.0, 0.0, 0.0, 1.0 ) |
| 132 |
|
| 133 |
Thus, the user might write:: |
| 134 |
|
| 135 |
plotitem.color = 'red' |
| 136 |
|
| 137 |
In a predecessor to Chaco, providing such flexibility came at a cost: |
| 138 |
|
| 139 |
* When the value of an attribute was used by an object internally (for example, |
| 140 |
setting the correct pen color when drawing a plot line), the object would |
| 141 |
often have to map the user-supplied value to a suitable internal |
| 142 |
representation, a potentially expensive operation in some cases. |
| 143 |
* If the user supplied a value outside the realm accepted by the object |
| 144 |
internally, it often caused disastrous or mysterious program behavior. |
| 145 |
This behavior was often difficult to track down because the cause and effect |
| 146 |
were usually widely separated in terms of the logic flow of the program. |
| 147 |
|
| 148 |
So, one of the main goals of the Traits package is to provide a form of type |
| 149 |
checking that: |
| 150 |
|
| 151 |
* Allows for flexibility in the set of values an attribute can have, such as |
| 152 |
allowing 'red', 0xFF0000 and ( 1.0, 0.0, 0.0, 1.0 ) as equivalent ways of |
| 153 |
expressing the color red. |
| 154 |
* Catches illegal value assignments at the point of error, and provides a |
| 155 |
meaningful and useful explanation of the error and the set of allowable |
| 156 |
values. |
| 157 |
* Eliminates the need for an object's implementation to map user-supplied |
| 158 |
attribute values into a separate internal representation. |
| 159 |
|
| 160 |
In the process of meeting these design goals, the Traits package evolved into |
| 161 |
a useful component in its own right, satisfying all of the above requirements |
| 162 |
and introducing several additional, powerful features of its own. In projects |
| 163 |
where the Traits package has been used, it has proven valuable for enhancing |
| 164 |
programmers' ability to understand code, during both concurrent |
| 165 |
development and maintenance. |
| 166 |
|
| 167 |
The Traits |version| package works with versions 3.5 and later of |
| 168 |
Python. It is similar in some ways to the Python property language feature. |
| 169 |
Standard Python properties provide the similar capabilities to the Traits |
| 170 |
package, but with more work on the part of the programmer. |
| 171 |
|
| 172 |
.. rubric:: Footnotes |
| 173 |
.. [1] All code examples in this guide that include a file name are also |
| 174 |
available as examples in the tutorials/doc_examples/examples |
| 175 |
subdirectory of the Traits examples directory. You can run them |
| 176 |
individually, or view them in a tutorial program by running: |
| 177 |
|
| 178 |
python <Traits dir>/examples/tutorials/tutor.py <Traits dir>/examples/tutorials/doc_examples |