Debian Codegraph @

docs/source/traits_user_manual/intro.rst

raw
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