Atom offers multiple ways to customize the inner working of members. The easiest one is to use specially named methods on your class definition. Since this covers most of the use cases, it is the only one that is covered here more details and advanced methods can be found in :ref:`advanced-customization`.
The customization method should use the name of the member to customize with one of the following prefixes depending on the operation to customize:
_default_
: to define default values._observe_
: to define a static observer._validate_
: to define a custom validation algorithm._post_getattr_
: to customize the post-getattr step._post_setattr_
: to customize the post-setattr step._post_validate_
: to customize the post-setattr step._getstate_
: to determine if a member should be pickled
A default value handler should take no argument and return the default value for the member.
class MyAtom(Atom):
v = Value()
def _default_v(self):
return [{}, 1, 'a']
A static observer is basically an observer so it should take the change dictionary as argument (save for |Signal|).
class MyAtom(Atom):
v = Value()
def _observe_v(self, change):
print(change)
A validation handler should accept both the old value of the member and the new value to validate. It should return a valid value.
class MyAtom(Atom):
v = Value()
def _validate_v(self, old, new):
if old and not isinstance(new, type(old)):
raise TypeError()
return new
Post-gettatr should take a single argument, ie the value that was retrieve during the get step, and return whatever value it decides to.
class MyAtom(Atom):
v = Value()
def _post_getattr_v(self, value):
print('v was accessed')
return value
Post-setattr and post-validate both take the old and the new value of the member as input, and post-validate should return a valid value.
class MyAtom(Atom):
v = Value()
def _post_setattr_v(self, old, new):
print('v was set')
return value
class MyAtom(Atom):
v = Value()
def _post_validate_v(self, old, new):
print('v was validated')
return value
Getstate method should take as single argument the name of the member they apply to and return a bool indicating whether or not the member value should be included in the object pickle.
class MyAtom(Atom):
v = Value()
def _getstate_v(self, name):
print('do not pickle v')
return False
Note
Contrary to other operations, answering to the question whether a member should be pickled or not can be done for a given Atom class and has little to do with the current state of the class instance. For such cases, it is possible to directly set the member getstate mode as follows:
from atom.api import GetState
class A(Atom):
# This member will never be pickled.
unpickeable = Value()
unpickeable.set_getstate_mode(GetState.Exclude, None)
Useful variants from the |GetState| enum are:
- Include: also include the member value in the pickle
- Exclude: never include the member value in the pickle
- IncludeNonDefault: include the member value only if it already exists (i.e. we won't need to invoke default to get a value).