| 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` |