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.
-
class
properties.
directional_link
(source, target, update_now=False, change_only=True, transform=None)[source]¶ 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.
-
class
properties.
link
(*items, **kwargs)[source]¶ 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 upn*(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.