1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
.. _advanced-property:
The Property member
===================
.. include:: ../substitutions.sub
The |Property| member looks a lot like a normal Python property which makes it
quite different from other members. In particular because there is no way from
atom to know when the value returned by a |Property| changes, **no
notifications are emitted by default when getting or setting it**.
Defining a Property member
--------------------------
Defining a |Property| and the getter, setter and deleter associated to it can
be done in several equivalent manners illustrated below:
.. code-block:: Python
from atom.api import Atom, Property, Value
def get_v(owner):
return owner.v
def set_v(owner, value):
owner.v = value
def del_v(owner):
del owner.v
class MyAtom(Atom):
v = Value()
p1 = Property(get_v, set_v, del_v)
p2 = Property()
def _get_p2(self):
return get_v(self)
def _set_p2(self, value):
set_v(self, value
def _del_p2(self):
del_v(self)
p3 = Property()
p3.getter
def _get(self):
return get_v(self)
p3.setter
def _set(self, value):
set_v(self, value)
p3.deleter
def _del(self):
del_v(self)
Cached properties
-----------------
For **read-only** properties, atom offers the option to cache the value
returned by the getter. This can be convenient if the getter performs an
expensive operation. The cache can be reset at a later time by deleting the
property or by calling the :py:meth:`atom.property.Property.reset` method of
the member as illustrated below:
.. code-block:: python
from atom.api import Atom, Property, cached_property
class MyAtom(Atom):
cp1 = Property(cached=True)
def _get_cp1(self):
print('Called cp1')
@cached_property
def cp2(self):
print('Called cp2')
a = MyAtom()
a.cp1
a.cp1
del a.cp1
a.cp1
a.cp2
a.cp2
MyAtom.cp2.reset(a)
a.cp2
Running this code will print "Called cp1/2" only twice each.
Notifications from a Property
-----------------------------
As mentionned in the introduction, |Property| does not fire notifications
upon get/setattr. However it will always fire notifications upon
deletion/reset. To manually fire notifications from a
property, please refer to :ref:`advanced-manual-notifications`.
|
