Debian Codegraph @

examples/tutorials/traits_4.0/decorators/cached_property.py

raw
1 # (C) Copyright 2005-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 # --(cached_property Decorator)------------------------------------------------
12 """
13 cached_property Decorator
14 =========================
15
16 New in Traits 3.0 is the *cached_property* method decorator which helps
17 streamline the process of writing properties which cache their current value.
18
19 Defining properties is a very powerful technique for exposing as traits items
20 whose value depends upon the current state of other object traits. In
21 particular, this can be very useful for creating synthetic traits which are
22 editable or displayable in a traits-based user interface.
23
24 In some cases however, the cost of computing the current value of a property
25 may be fairly expensive, so it is often a good idea to *cache* the most
26 recently computed value of the property, and return it as the value of the
27 property until one of the traits the property depends upon changes value, at
28 which point the cache should be cleared and the property value recomputed the
29 next time its value is requested.
30
31 Combined with the **Property** *depends_on* metadata, the *cached_property*
32 decorator greatly simplifies the process of writing a cached property. Take a
33 look at the following code for example::
34
35 class TestScores(HasPrivateTraits):
36
37 scores = List(Int)
38 average = Property(depends_on='scores')
39
40 @cached_property
41 def _get_average(self):
42 s = self.scores
43 return (float(reduce(lambda n1, n2: n1 + n2, s, 0)) / len(s))
44
45 Presumably this is much easier to write and understand that the following
46 equivalent code written without using *depends_on* and *cached_property*::
47
48 class TestScores(HasPrivateTraits):
49
50 scores = List(Int)
51 average = Property
52
53 def _get_average(self):
54 if self._average is None:
55 s = self.scores
56 self._average = (float(reduce(lambda n1, n2: n1 + n2, s, 0))
57 / len(s))
58 return self._average
59
60 def _scores_changed(self):
61 old, self._average = self._average, None
62 self.trait_property_changed('average', old, self._average)
63
64 def _scores_items_changed(self):
65 self._scores_changed()
66
67 The *cached_property* decorator takes no arguments, and should simply be
68 written on the line preceding the property's *getter* method, as shown in the
69 previous example.
70
71 Use of the *cached_property* decorator also eliminates the need to add *cached
72 = True* metadata to the property declaration, as was previously required when
73 using *depends_on* metadata with a cached property definition.
74 """
75
76 from traits.api import cached_property, HasPrivateTraits, Int, List, Property
77
78
79 # --[TestScores Class]---------------------------------------------------------
80 class TestScores(HasPrivateTraits):
81
82 scores = List(Int)
83 average = Property(depends_on="scores")
84
85 @cached_property
86 def _get_average(self):
87 print("...computing average:", end=" ")
88 s = self.scores
89 return sum(s) / len(s)
90
91
92 # --[Example*]-----------------------------------------------------------------
93 # Create a sample TestScores object with some sample scores:
94 test_scores = TestScores(scores=[89, 93, 76, 84, 62, 96, 75, 81, 69, 90])
95
96 # Display the average:
97 print("First average:", test_scores.average)
98 print("Check that again:", test_scores.average)
99
100 # Now add a few more late scores into the mix:
101 test_scores.scores.extend([85, 61, 70])
102
103 # And display the new average:
104 print("Second average:", test_scores.average)