Customimizing members: specially named methods

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 Member customization: advanced techniques.

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

Default values

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']

Static observers

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)

Validation

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-operation methods

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

Pickle

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).