Debian Codegraph @

docs/source/traits_user_manual/internals.rst

raw
1 .. index:: internals
2
3 Traits internals
4 ================
5
6 This section of the documentation is intended both for those developing Traits
7 itself, and for those using Traits who would like a better understanding of
8 the Traits internals.
9
10
11 Fundamentals
12 ------------
13
14 The runtime behavior of Traits is governed by two key classes: |CTrait| and
15 |HasTraits|. Each of these classes inherits from a superclass implemented in
16 the |ctraits| C extension module: |CTrait| inherits from |cTrait|, while
17 |HasTraits| inherits from |CHasTraits|.
18
19 The |CHasTraits| and |cTrait| base classes are not intended for direct use and
20 do not provide a complete, coherent API: that API is provided by their
21 respective subclasses |HasTraits| and |CTrait|. The existence and precise
22 semantics of the base classes should be regarded as implementation details.
23 In what follows, we'll frequently refer to behavior of |HasTraits| and |CTrait|
24 even when the behavior we're referring to is actually implemented by
25 |CHasTraits| or |cTrait|.
26
27 We'll examine both of these classes, along with some of their hidden state, in
28 more detail below.
29
30
31 Key class: |HasTraits|
32 ~~~~~~~~~~~~~~~~~~~~~~
33
34 The primary purpose of the |HasTraits| class is to override Python's normal
35 rules for attribute access. It does this by overriding the
36 ``__getattribute__``, ``__setattr__`` and ``__delattr__`` special methods. At C
37 level, this is done through providing ``tp_getattro`` and ``tp_setattro``
38 "slots" to the |CHasTraits| ``PyTypeObject``: ``tp_getattro`` controls
39 attribute retrieval operations, while ``tp_setattro`` is called for both
40 attribute set and attribute deletion operations.
41
42 To support trait get and set operations, a |HasTraits| object (that is, in
43 normal use, an instance of a user-defined subclass of |HasTraits|) has two key
44 pieces of state: a dictionary of **class traits**, and a second dictionary of
45 **instance traits**. Each dictionary is a mapping from trait attribute names to
46 |CTrait| objects. A |CTrait| object encapsulates the rules for getting and
47 setting the corresponding attribute, as well as providing an attachment point
48 for trait notifications.
49
50 In addition to these two dictionaries, a |HasTraits| object has a ``__dict__``
51 that stores attribute values for that object in the normal way.
52
53 Analogously to class variables and instance variables in a normal Python class,
54 the class traits dictionary for a given |HasTraits| subclass is shared between
55 instances of that class, while the instance traits dictionary is specific to a
56 particular |HasTraits| instance. (As an internal optimization, the instance
57 traits dictionary is created on demand when first needed, while the class
58 traits dictionary is always present for each instance.)
59
60 For introspection and debugging purposes, both of these dictionaries can
61 be retrieved directly, using the |_instance_traits| and |_class_traits|
62 methods. However, it's not recommended to use either of these methods in
63 production code, and you should be especially careful when modifying either
64 of these dictionaries.
65
66 For example, consider the following |HasTraits| subclass::
67
68 from traits.api import Float, HasTraits, Str
69
70 class Ingredient(HasTraits):
71 """ An ingredient in a recipe listing. """
72
73 #: The name of the ingredient.
74 name = Str()
75
76 #: Ingredient quantity.
77 quantity = Float()
78
79 Here's what happens when we create an instance of this ingredient and inspect
80 the instance and class trait dictionaries::
81
82 >>> eggs = Ingredient(name="eggs", quantity=12)
83 >>> eggs._instance_traits()
84 {}
85 >>> eggs._class_traits()
86 {
87 'name': <traits.ctrait.CTrait object at 0x1020cd400>,
88 'quantity': <traits.ctrait.CTrait object at 0x1020cd360>,
89 'trait_added': <traits.ctrait.CTrait object at 0x1020cd4a0>,
90 'trait_modified': <traits.ctrait.CTrait object at 0x1020079a0>,
91 }
92 >>> eggs.__dict__
93 {'name': 'eggs', 'quantity': 12.0}
94
95 Note that the actual values for the ingredient are stored in the ``__dict__``
96 as usual, not in the ``CTrait`` objects.
97
98 If we create a second ingredient, it shares class traits (but not
99 instance traits) with the first one::
100
101 >>> flour = Ingredient(name="flour", quantity=3.5)
102 >>> flour._class_traits() is eggs._class_traits()
103 True
104 >>> flour._instance_traits() is eggs._instance_traits()
105 False
106
107
108 Key class: |CTrait|
109 ~~~~~~~~~~~~~~~~~~~
110
111 A |CTrait| object has two main purposes:
112
113 - It encapsulates the rules for getting and setting a traited attribute on
114 a |HasTraits| object.
115 - It provides an attachment point for trait notifiers.
116
117 The hidden state for a |CTrait| instance is encapsulated in the
118 ``trait_object`` C ``struct`` in the |ctraits| source. There are several
119 interesting fields, not all of which are exposed at Python level.
120
121 Of particular interest are the ``getattr`` and ``setattr`` fields, which
122 hold pointers to C functions that act as the entry points for attribute
123 access via the given trait. See below for a fuller description of attribute
124 access mechanics.
125
126
127 Attribute retrieval
128 ~~~~~~~~~~~~~~~~~~~
129
130 When evaluating ``obj.name`` for a ``HasTraits`` object ``obj``, the following
131 sequence of steps occurs (see ``has_traits_getattro`` in the C source):
132
133 - The ``name`` is looked up in ``obj.__dict__``. If found, the corresponding
134 value is returned immediately.
135 - If ``name`` is not found in ``obj.__dict__``, we look first for an instance
136 trait named ``name``, and then for a class trait named ``name``. Thus an
137 instance trait with a given name will shadow a class trait with the same
138 name.
139 - If a matching trait is found, its ``getattr`` field is invoked to retrieve
140 the trait's value for the given object.
141 - If no matching trait is found, we try to access the attribute value
142 using Python's usual attribute rules (via the ``PyObject_GenericGetAttr``
143 C-API call).
144 - Finally, if the ``PyObject_GenericGetAttr`` call fails, we invoke the
145 **prefix trait** machinery to get a new ``CTrait`` object, and use that
146 new trait to get a value.
147
148 Note that the above sequence of steps applies to method access as well as
149 attribute access. Note also that there's no mechanism to automatically
150 search for ``CTrait`` objects in superclasses of the immediate ``HasTraits``
151 subclass.
152
153
154 Attribute set operations
155 ~~~~~~~~~~~~~~~~~~~~~~~~
156
157 The rules for setting an attribute (evaluating ``obj.name = value`` for a
158 ``HasTraits`` object ``obj``) are analogous to those for attribute retrieval.
159 The starting point is ``has_traits_setattro`` in the source.
160
161 - First we look for the name ``name`` in ``obj._instance_traits()``,
162 and retrieve the corresponding ``CTrait`` instance if present.
163 - If no matching entry is found, we then look up ``name`` in
164 ``obj._class_traits()``, and again retrieve the corresponding ``CTrait``.
165 - If still not found, we invoke the **prefix trait** machinery to get a new
166 ``CTrait`` object. By default, this goes through the
167 ``HasTraits.__prefix_trait__`` method (which is implemented in Python), and
168 this may still fail with an exception.
169 - If one of the above steps succeeded, we now have a ``CTrait`` object, and
170 its ``setattr`` function is invoked (passing along the trait object, ``obj``,
171 ``name`` and ``value``) to perform the actual attribute set operation.
172
173
174 Attribute deletion
175 ~~~~~~~~~~~~~~~~~~
176
177 Attribute deletion (``del obj.name``) goes through the same code path as
178 attribute set operations. Most ``CTrait`` types do not permit deletion.
179
180 Traits Containers
181 -----------------
182
183 Traits has the ability to watch for changes in standard Python containers:
184 lists, dictionaries and sets. To achieve this Traits provides special
185 subclasses of the standard Python classes that can validate elements and can
186 fire trait notifications when the contents change. These classes are,
187 respectively, |TraitList|, |TraitDict| and |TraitSet| (not to be confused with
188 the deprecated Trait Handlers of the same names).
189
190 In addition to being able to take an appropriate value to initialize the
191 container (such as a sequence or mapping), these container subclasses also
192 take keyword-only arguments for validators (either a single item validator for
193 |TraitList| and |TraitSet|, or key and value validators for |TraitDict|) and
194 notifiers.
195
196 These classes were introduced in Traits 6.1 and the implementation details
197 described here are provisional and may change.
198
199 Backwards Compatibility
200 ~~~~~~~~~~~~~~~~~~~~~~~
201
202 In practice, most traits containers are instances of |TraitListObject|,
203 |TraitDictObject| and |TraitSetObject| which are subclasses that are
204 created by the validators of |List|, |Dict| and |Set| traits respectively and
205 supplied with appropriate element validators that wrap the standard trait
206 validators so that constructs like ``List(Str)`` can work.
207
208 These objects are designed to be API compatible with the classes of the
209 same name from Traits 6.0 and before, and so have different constructors and
210 may behave slightly differently from the base classes in some cases.
211
212 In particular |TraitListObject| classes can have restrictions on their
213 length, which is not part of the base |TraitList| API.
214
215 All of these backward compatibility classes are strongly tied to a particular
216 object and trait, and are not designed to operate as stand-alone entities.
217 These relationships are required to support the `object.*_items`-style event
218 traits, but complicate the implementation, for example by having to use
219 weak references to the object, and having to take this additional structure
220 into account when serializing and deserializing.
221
222 It is a long-term goal to phase out the use of these backwards compatibility
223 classes.
224
225 Container Validators
226 ~~~~~~~~~~~~~~~~~~~~
227
228 Container validators are callables that are expected to take a single value
229 and either return a validated value or raise a TraitError. The default
230 validators simply pass the input value directly through, but validators can
231 potentially do much more. Validators are expected to be idempotent:
232 ``validate(validate(x)) == validate(x)`` should hold as long as
233 ``validate(x)`` does not raise an error.
234
235 For example, the following validator casts the list items to integers,
236 raising a TraitError if that fails::
237
238 def int_validator(value):
239 try:
240 return int(value)
241 except ValueError:
242 raise TraitError(
243 "List items must be castable to an int, but a value %r was specified."
244 % value
245 )
246
247 So if we were to use this as the validator for a |TraitList| we would get the
248 following behaviour::
249
250 >>> int_list = TraitList(item_validator=int_validator)
251 >>> int_list.append("5")
252 >>> int_list
253 [5]
254 >>> int_list.extend([3, 5, "aaaarrrghh"])
255 TraitError: List items must be castable to an int, but a value 'aaaarrrghh' was specified.
256
257 In Traits 6.1 validation is not done uniformly before performing operations
258 to keep behaviour the same as Traits 6.0 and earlier, so results of operations can
259 sometimes be surprising::
260
261 >>> int_list.append("6")
262 >>> int_list.remove("6")
263 ValueError: list.remove(x): x not in list
264
265 This is expected to be resolved in a future traits version by providing clear
266 guidance to users about when validation is performed, and possibly changing the
267 behaviour.
268
269 Container Notifiers
270 ~~~~~~~~~~~~~~~~~~~
271
272 Container objects also have a list of notifiers that fire when the contents of
273 the container change. Like trait notifiers, container notifiers are low-level
274 callbacks that are used by the higher-level, more user-friendly observer and
275 listener systems. They have a fixed signature, which is slightly different for
276 lists, dicts and sets, but in all cases starts with the container object itself.
277 Notifiers are called in the order that they appear in the notifiers list and
278 should not mutate the parameters that they have been passed.
279
280 List notifiers must take 4 arguments: the **trait_list** object, the **index**
281 value or slice that identifies where the change occurred, a list of
282 **removed** elements, and a list of **added** elements. The |TraitList|
283 methods make an attempt to normalize indices and slices to make things easier
284 for notification writers.
285
286 Dict notifiers expect 4 arguments: the **trait_dict** object, a dictionary of
287 **removed** items, a dictionary of **added** elements, and a dictionary of
288 **changed** items, where the values are the old values held in the keys.
289
290 Set notifiers expect 3 arguments: the **trait_set** object, the set of
291 **removed** elements, and the set of **added** elements.
292
293 Users should not usually need to interact with the container notifiers directly,
294 just as they do not usually need to interact with trait notifiers.
295
296
297 ..
298 # substitutions
299
300 .. |_class_traits| replace:: :meth:`~traits.ctraits.CHasTraits._class_traits`
301 .. |_instance_traits| replace:: :meth:`~traits.ctraits.CHasTraits._instance_traits`
302 .. |cTrait| replace:: :class:`~traits.ctraits.cTrait`
303 .. |CTrait| replace:: :class:`~traits.ctrait.CTrait`
304 .. |ctraits| replace:: :mod:`~traits.ctraits`
305 .. |CHasTraits| replace:: :class:`~traits.ctraits.CHasTraits`
306 .. |HasTraits| replace:: :class:`~traits.has_traits.HasTraits`
307 .. |TraitList| replace:: :class:`~traits.trait_list_object.TraitList`
308 .. |TraitDict| replace:: :class:`~traits.trait_dict_object.TraitDict`
309 .. |TraitSet| replace:: :class:`~traits.trait_dict_object.TraitSet`
310 .. |TraitListObject| replace:: :class:`~traits.trait_list_object.TraitListObject`
311 .. |TraitDictObject| replace:: :class:`~traits.trait_dict_object.TraitDictObject`
312 .. |TraitSetObject| replace:: :class:`~traits.trait_dict_object.TraitSetObject`
313 .. |List| replace:: :class:`~traits.trait_types.List`
314 .. |Dict| replace:: :class:`~traits.trait_types.Dict`
315 .. |Set| replace:: :class:`~traits.trait_types.Set`