Notifications

properties.observer(names_or_instance, names=None, func=None, change_only=False)[source]

Specify a callback function that will fire on Property value change

Observer functions on a HasProperties class fire after the observed Property or Properties have been changed (unlike validator functions that fire on set before the value is changed).

You can use this method as a decorator inside a HasProperties class

@properties.observer('variable_name')
def callback_function(self, change):
    print(change)

or you can use it to register a function to a single HasProperties instance

properties.observer(my_has_props, 'variable_name', callback_function)

The variable name must refer to a Property name on the HasProperties class. A list of Property names may also be used; the same callback function will fire when any of these Properties change. Also, properties.everything may be specified instead of the variable name. In that case, the callback function will fire when any Property changes.

The callback function must take two arguments. The first is the HasProperties instance; the second is the change notification dictionary. This dictionary contains:

  • ‘name’ - the name of the changed Property
  • ‘previous’ - the value of the Property prior to change (this will be properties.undefined if the value was not previously set)
  • ‘value’ - the new value of the Property (this will be properties.undefined if the value is deleted)
  • ‘mode’ - the mode of the change; for observers, this is either ‘observe_set’ or ‘observe_change’

Finally, the keyword argument change_only may be specified as a boolean. If False (the default), the callback function will fire any time the Property is set. If True, the callback function will only fire if the new value is different than the previous value, determined by the Property.equal method.

class properties.listeners_disabled(disable_type=None)[source]

Context manager for disabling all HasProperties listeners

Code that runs inside this context manager will not fire HasProperties methods decorated with @validator or @observer. This context manager has no effect on Property validation.

with properties.listeners_disabled():
    self.quietly_update()
class properties.observers_disabled[source]

Context manager for disabling all property change observers

This context manager behaves like properties.listeners_disabled, but only affects HasProperties methods decorated with @observer

Linking across Properties/Traitlets

Properties has link functions similar to those from traitlets. This allows easy connection to IPython widgets and other projects that build on traitlets.

Link two properties so updating the source updates the target

source and target must each be tuples of HasProperties (or traitlets.HasTraits, if available) instances and property (or trait) name.

If update_now is True, the target value will be updated to the source value on link. If False, it will not update until the source value is set. The default is False to prevent conflicts with how properties and traitlets deal with uninitialized values.

The change_only keyword argument determines if target updates when the source value is set but unchanged. If True, the target only updates when the source value changes; this is the default to mirror behavior from traitlets. It should only be set to False when the source instance is HasProperties.

If a transform function is provided, the target will be updated with the transformed source value.

Re-enable an unlinked directional link

Disable a directional link

Note

This does not delete the observer callbacks; it simply makes them non-functional.

Link property values to keep them in sync

link takes two or more items to link. Each item must be a tuple of HasProperties (or traitlets.HasTraits, if available) instances and property (or trait) name. This creates a series of directional links to connect all items.

Available keyword arguments are update_now and change_only. These are passed through to the directional links.

Note

If an error is encountered when updating multiple linked items, some linked properties may not get updated. The order in which properties are updated depends on the order of items. There is no validation to ensure linked items are compatible Property types.

Warning

Linking n items sets up n*(n-1) directional links, all of which may fire on one change. Some care should be taken when creating links among a large number of items.

Re-enable all unlinked directional links used by link

Disable all directional links used by link