| 1 |
# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX |
| 2 |
# All rights reserved. |
| 3 |
# |
| 4 |
# This software is provided without warranty under the terms of the BSD |
| 5 |
# license included in LICENSE.txt and may be redistributed only under |
| 6 |
# the conditions described in the aforementioned license. The license |
| 7 |
# is also available online at http://www.enthought.com/licenses/BSD.txt |
| 8 |
# |
| 9 |
# Thanks for using Enthought open source! |
| 10 |
|
| 11 |
""" |
| 12 |
Creating settable cached Property in Traits |
| 13 |
|
| 14 |
How to create a Traits Property which is cached but is not read-only. |
| 15 |
|
| 16 |
The example demonstrates how to create a 'settable cached' property. The example |
| 17 |
itself is nonsensical, and is provided mainly to show how to set up such a |
| 18 |
property, and how it differs from a standard 'cached' property. |
| 19 |
|
| 20 |
A normal 'cached' property does not have a 'setter' method, meaning that the |
| 21 |
property is read-only. It usually represents a value which depends upon the |
| 22 |
state of other traits for its value. The cached property provides both a |
| 23 |
mechanism for remembering (i.e. caching) the current value of the property as |
| 24 |
well as a means of automatically detecting when the value of the property |
| 25 |
changes (which causes the cache to be flushed), and notifying any associated |
| 26 |
trait listeners that the value of the property has changed. |
| 27 |
|
| 28 |
Normally there is no 'setter' for such a property because the value is derived |
| 29 |
from the value of other traits. |
| 30 |
|
| 31 |
However, it is possible to define a 'settable cached' property which in addition |
| 32 |
to the capabilities of a normal 'cached' property, also allows the property's |
| 33 |
value to be explicitly set. |
| 34 |
|
| 35 |
To accomplish this, simply add a '_set_*' method as usual for a settable property |
| 36 |
(see the '_set_c' method in the example code) which takes the value provided |
| 37 |
and changes the values the property depends on appropriately based on the new |
| 38 |
value. |
| 39 |
|
| 40 |
This allows code to set the value of the property directly if desired, subject |
| 41 |
to any constraints specified in the property declaration. For example, in the |
| 42 |
example, the 'c' trait is a 'settable cached' property whose value must be an |
| 43 |
integer. Attempting to set a non-integer value of the property will raise an |
| 44 |
exception, just like any other trait would. |
| 45 |
|
| 46 |
If any of the traits which the property depends upon change value, the current |
| 47 |
value of the property will be flushed from the cache and a change notification |
| 48 |
for the property will be generated. Any code that then attempts to read the |
| 49 |
value of the property will result in the cache being reloaded with the new value |
| 50 |
returned by the property's 'getter' method. |
| 51 |
|
| 52 |
In the example, trait 'c' is a 'settable cached' property which returns the |
| 53 |
product of 'a' times 'b', and trait 'd' is a normal 'cached' property that |
| 54 |
returns double the value of 'c'. |
| 55 |
|
| 56 |
To see the effect of these traits in action, try moving the 'a' and 'b' sliders |
| 57 |
and watching the 'c' and 'd' traits update. This demonstrates how 'c' and 'd' |
| 58 |
are properties that depend upon the values of other traits. |
| 59 |
|
| 60 |
Now try changing the value of the 'c' trait by moving the slider or typing a |
| 61 |
new value into the text entry field. You will see that the 'd' trait updates |
| 62 |
as well, illustrating that the 'c' trait can be set directly, as well as |
| 63 |
indirectly by changes to 'a' and 'b'. |
| 64 |
|
| 65 |
Also, try typing non-numeric values into the 'c' field and you will see that |
| 66 |
any values set are being type checked as well (i.e. they must be integer |
| 67 |
values). |
| 68 |
|
| 69 |
Now try typing a value into the 'd' trait and you will see that an error |
| 70 |
results (indicated by the text entry field turning red), because this is a |
| 71 |
normal 'cached' trait that has no 'setter' method defined. |
| 72 |
""" |
| 73 |
from math import sqrt |
| 74 |
|
| 75 |
from traits.api import HasTraits, Int, Range, Property, cached_property |
| 76 |
from traitsui.api import View, Item, RangeEditor |
| 77 |
|
| 78 |
# -- Demo Class ----------------------------------------------------------- |
| 79 |
|
| 80 |
|
| 81 |
class SettableCachedProperty(HasTraits): |
| 82 |
|
| 83 |
a = Range(1, 10) |
| 84 |
b = Range(1, 10) |
| 85 |
c = Property(Int, observe=['a', 'b']) |
| 86 |
d = Property(observe='c') |
| 87 |
|
| 88 |
view = View( |
| 89 |
Item('a'), |
| 90 |
Item('b'), |
| 91 |
'_', |
| 92 |
Item('c', editor=RangeEditor(low=1, high=100, mode='slider')), |
| 93 |
Item('c'), |
| 94 |
'_', |
| 95 |
Item('d', editor=RangeEditor(low=1, high=400, mode='slider')), |
| 96 |
Item('d'), |
| 97 |
width=0.3, |
| 98 |
) |
| 99 |
|
| 100 |
@cached_property |
| 101 |
def _get_c(self): |
| 102 |
return self.a * self.b |
| 103 |
|
| 104 |
def _set_c(self, value): |
| 105 |
self.a = int(sqrt(value)) |
| 106 |
self.b = int(sqrt(value)) |
| 107 |
|
| 108 |
@cached_property |
| 109 |
def _get_d(self): |
| 110 |
return self.c + self.c |
| 111 |
|
| 112 |
|
| 113 |
# -- Run the demo --------------------------------------------------------- |
| 114 |
|
| 115 |
# Create the demo: |
| 116 |
demo = SettableCachedProperty() |
| 117 |
|
| 118 |
# Run the demo (if invoked from the command line): |
| 119 |
if __name__ == '__main__': |
| 120 |
demo.configure_traits() |