bokeh.core.property.containers¶

Provide special versions of list and dict, that can automatically notify about changes when used for property values.

Mutations to these values are detected, and the properties owning the collection is notified of the changes. Consider the following model definition:

class SomeModel(Model):

    options = List(String)

If we have an instance of this model, m then we can set the entire value of the options property at once:

m.options = ["foo", "bar"]

When we do this in the context of a Bokeh server application that is being viewed in a browser, this change is automatically noticed, and the corresponding BokehJS property in the browser is synchronized, possibly causing some change in the visual state of the application in the browser.

But it is also desirable that changes inside the options list also be detected. That is, the following kinds of operations should also be automatically synchronized between BokehJS and a Bokeh server:

m.options.append("baz")

m.options[2] = "quux"

m.options.insert(0, "bar")

The classes in this module provide this functionality.

class PropertyValueContainer(*args, **kwargs)[source]¶

A base class for property container classes that support change notifications on mutating operations.

This class maintains an internal list of property owners, and also provides a private mechanism for methods wrapped with notify_owners() to update those owners when mutating changes occur.

class PropertyValueDict(*args, **kwargs)[source]¶

A dict property value container that supports change notifications on mutating operations.

When a Bokeh model has a List property, the PropertyValueLists are transparently created to wrap those values. These PropertyValueList values are subject to normal property validation. If the property type foo = Dict(Str, Str) then attempting to set x.foo['bar'] = 10 will raise an error.

Instances of PropertyValueDict can be eplicitly created by passing any object that the standard dict initializer accepts, for example:

>>> PropertyValueDict(dict(a=10, b=20))
{'a': 10, 'b': 20}

>>> PropertyValueDict(a=10, b=20)
{'a': 10, 'b': 20}

>>> PropertyValueDict([('a', 10), ['b', 20]])
{'a': 10, 'b': 20}

The following mutating operations on dicts automatically trigger notifications:

del x[y]
x[i] = y
x.clear
x.pop
x.popitem
x.setdefault
x.update

__delitem__(*args, **kwargs)[source]¶

Container method __delitem__ instrumented to notify property owners

__setitem__(*args, **kwargs)[source]¶

Container method __setitem__ instrumented to notify property owners

clear(*args, **kwargs)[source]¶

Container method clear instrumented to notify property owners

pop(*args, **kwargs)[source]¶

Container method pop instrumented to notify property owners

popitem(*args, **kwargs)[source]¶

Container method popitem instrumented to notify property owners

setdefault(*args, **kwargs)[source]¶

Container method setdefault instrumented to notify property owners

update(*args, **kwargs)[source]¶

Container method update instrumented to notify property owners

class PropertyValueList(*args, **kwargs)[source]¶

A list property value container that supports change notifications on mutating operations.

When a Bokeh model has a List property, the PropertyValueLists are transparently created to wrap those values. These PropertyValueList values are subject to normal property validation. If the property type foo = List(Str) then attempting to set x.foo[0] = 10 will raise an error.

Instances of PropertyValueList can be explicitly created by passing any object that the standard list initializer accepts, for example:

>>> PropertyValueList([10, 20])
[10, 20]

>>> PropertyValueList((10, 20))
[10, 20]

The following mutating operations on lists automatically trigger notifications:

del x[y]
del x[i:j]
x += y
x *= y
x[i] = y
x[i:j] = y
x.append
x.extend
x.insert
x.pop
x.remove
x.reverse
x.sort

__delitem__(*args, **kwargs)[source]¶

Container method __delitem__ instrumented to notify property owners

__delslice__(*args, **kwargs)[source]¶

Container method __delslice__ instrumented to notify property owners

__iadd__(*args, **kwargs)[source]¶

Container method __iadd__ instrumented to notify property owners

__imul__(*args, **kwargs)[source]¶

Container method __imul__ instrumented to notify property owners

__setitem__(*args, **kwargs)[source]¶

Container method __setitem__ instrumented to notify property owners

__setslice__(*args, **kwargs)[source]¶

Container method __setslice__ instrumented to notify property owners

append(*args, **kwargs)[source]¶

Container method append instrumented to notify property owners

extend(*args, **kwargs)[source]¶

Container method extend instrumented to notify property owners

insert(*args, **kwargs)[source]¶

Container method insert instrumented to notify property owners

pop(*args, **kwargs)[source]¶

Container method pop instrumented to notify property owners

remove(*args, **kwargs)[source]¶

Container method remove instrumented to notify property owners

reverse(*args, **kwargs)[source]¶

Container method reverse instrumented to notify property owners

sort(*args, **kwargs)[source]¶

Container method sort instrumented to notify property owners

notify_owner(func)[source]¶

A decorator for mutating methods of property container classes that notifies owners of the property container about mutating changes.

Parameters:	func (callable) – the container method to wrap in a notification
Returns:	wrapped method

Examples

A __setitem__ could be wrapped like this:

# x[i] = y
@notify_owner
def __setitem__(self, i, y):
    return super(PropertyValueDict, self).__setitem__(i, y)

The returned wrapped method will have a docstring indicating what original method it is wrapping.