bokeh.core.property.descriptors¶
Provide Python descriptors for delegating to Bokeh properties.
The Python descriptor protocol allows fine-grained control over all attribute access on instances (“You control the dot”). Bokeh uses the descriptor protocol to provide easy-to-use, declarative, type-based class properties that can automatically validate and serialize their values, as well as help provide sophisticated documentation.
A Bokeh property really consist of two parts: a familiar “property”
portion, such as Int
, String
, etc., as well as an associated
Python descriptor that delegates attribute access to the property instance.
For example, a very simplified definition of a range-like object might be:
from bokeh.model import Model
from bokeh.core.properties import Float
class Range(Model):
start = Float(help="start point")
end = Float(help="end point")
When this class is created, the MetaHasProps
metaclass wires up both
the start
and end
attributes to a Float
property. Then, when
a user accesses those attributes, the descriptor delegates all get and
set operations to the Float
property.
rng = Range()
# The descriptor __set__ method delegates to Float, which can validate
# the value 10.3 as a valid floating point value
rng.start = 10.3
# But can raise a validation exception if an attempt to set to a list
# is made
rng.end = [1,2,3] # ValueError !
More sophisticated properties such as DataSpec
and its subclasses can
exert control over how values are serialized. Consider this example with
the Circle
glyph and its x
attribute that is a NumberSpec
:
from bokeh.models import Circle
c = Circle()
c.x = 10 # serializes to {'value': 10}
c.x = 'foo' # serializes to {'field': 'foo'}
There are many other examples like this throughout Bokeh. In this way users may operate simply and naturally, and not be concerned with the low-level details around validation, serialization, and documentation.
This module provides the class PropertyDescriptor
and various subclasses
that can be used to attach Bokeh properties to Bokeh models.
Note
These classes form part of the very low-level machinery that implements the Bokeh model and property system. It is unlikely that any of these classes or their methods will be applicable to any standard usage or to anyone who is not directly developing on Bokeh’s own infrastructure.
- class ColumnDataPropertyDescriptor(name: str, property: Property[T])[source]¶
A
PropertyDescriptor
specialized to handlingColumnData
properties.- __set__(obj, value, *, setter=None)[source]¶
Implement the setter for the Python descriptor protocol.
This method first separately extracts and removes any
units
field in the JSON, and sets the associated units property directly. The remaining value is then passed to the superclass__set__
to be handled.Note
An optional argument
setter
has been added to the standard setter arguments. When needed, this value should be provided by explicitly invoking__set__
. See below for more information.- Parameters
obj (HasProps) – The instance to set a new property value on
value (obj) – The new value to set the property to
setter (ClientSession or ServerSession or None, optional) –
This is used to prevent “boomerang” updates to Bokeh apps. (default: None)
In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
- Returns
None
- class DataSpecPropertyDescriptor(name: str, property: Property[T])[source]¶
A
PropertyDescriptor
for BokehDataSpec
properties that serialize to field/value dictionaries.- set_from_json(obj, json, *, models=None, setter=None)[source]¶
Sets the value of this property from a JSON value.
This method first
- Parameters
obj (HasProps) –
json (JSON-dict) –
models (seq[Model], optional) –
setter (ClientSession or ServerSession or None, optional) –
This is used to prevent “boomerang” updates to Bokeh apps. (default: None)
In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
- Returns
None
- class PropertyDescriptor(name: str, property: Property[T])[source]¶
A base class for Bokeh properties with simple get/set and serialization behavior.
- __init__(name: str, property: Property[T]) None [source]¶
Create a PropertyDescriptor for basic Bokeh properties.
- __str__() str [source]¶
Basic string representation of
PropertyDescriptor
.Delegates to
self.property.__str__
- __get__(obj: HasProps | None, owner: Type[HasProps] | None) T [source]¶
Implement the getter for the Python descriptor protocol.
For instance attribute access, we delegate to the
Property
. For class attribute access, we return ourself.- Parameters
- Returns
None
Examples
>>> from bokeh.models import Range1d >>> r = Range1d(start=10, end=20) # instance attribute access, returns the property value >>> r.start 10 # class attribute access, returns the property descriptor >>> Range1d.start <bokeh.core.property.descriptors.PropertyDescriptor at 0x1148b3390>
- __set__(obj: HasProps, value: T, *, setter: Setter | None = None) None [source]¶
Implement the setter for the Python descriptor protocol.
Note
An optional argument
setter
has been added to the standard setter arguments. When needed, this value should be provided by explicitly invoking__set__
. See below for more information.- Parameters
obj (HasProps) – The instance to set a new property value on
value (obj) – The new value to set the property to
setter (ClientSession or ServerSession or None, optional) –
This is used to prevent “boomerang” updates to Bokeh apps. (default: None)
In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
- Returns
None
- __delete__(obj: HasProps) None [source]¶
Implement the deleter for the Python descriptor protocol.
- Parameters
obj (HasProps) – An instance to delete this property from
- class_default(cls)[source]¶
Get the default value for a specific subtype of
HasProps
, which may not be used for an individual instance.- Parameters
cls (class) – The class to get the default value for.
- Returns
object
- instance_default(obj: HasProps) T [source]¶
Get the default value that will be used for a specific instance.
- Parameters
obj (HasProps) – The instance to get the default value for.
- Returns
object
- serializable_value(obj: HasProps) Any [source]¶
Produce the value as it should be serialized.
Sometimes it is desirable for the serialized value to differ from the
__get__
in order for the__get__
value to appear simpler for user or developer convenience.- Parameters
obj (HasProps) – the object to get the serialized attribute for
- Returns
JSON-like
- set_from_json(obj: HasProps, json: Any, *, models: Dict[ID, HasProps] | None = None, setter: Setter | None = None)[source]¶
Sets the value of this property from a JSON value.
- Parameters
obj – (HasProps) : instance to set the property value on
json – (JSON-value) : value to set to the attribute to
models (dict or None, optional) –
Mapping of model ids to models (default: None)
This is needed in cases where the attributes to update also have values that have references.
setter (ClientSession or ServerSession or None, optional) –
This is used to prevent “boomerang” updates to Bokeh apps. (default: None)
In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
- Returns
None
- trigger_if_changed(obj: HasProps, old: Unknown) None [source]¶
Send a change event notification if the property is set to a value is not equal to
old
.- Parameters
obj (HasProps) – The object the property is being set on.
old (obj) – The previous value of the property to compare
- Returns
None
- property has_ref: bool¶
Whether the property can refer to another
HasProps
instance.For basic properties, delegate to the
has_ref
attribute on theProperty
.
- class UnitsSpecPropertyDescriptor(name, property, units_property)[source]¶
A
PropertyDescriptor
for BokehPropertyUnitsSpec
properties that contribute associated_units
properties automatically as a side effect.- __set__(obj, value, *, setter=None)[source]¶
Implement the setter for the Python descriptor protocol.
This method first separately extracts and removes any
units
field in the JSON, and sets the associated units property directly. The remaining value is then passed to the superclass__set__
to be handled.Note
An optional argument
setter
has been added to the standard setter arguments. When needed, this value should be provided by explicitly invoking__set__
. See below for more information.- Parameters
obj (HasProps) – The instance to set a new property value on
value (obj) – The new value to set the property to
setter (ClientSession or ServerSession or None, optional) –
This is used to prevent “boomerang” updates to Bokeh apps. (default: None)
In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
- Returns
None
- set_from_json(obj, json, *, models=None, setter=None)[source]¶
Sets the value of this property from a JSON value.
This method first separately extracts and removes any
units
field in the JSON, and sets the associated units property directly. The remaining JSON is then passed to the superclassset_from_json
to be handled.- Parameters
obj – (HasProps) : instance to set the property value on
json – (JSON-value) : value to set to the attribute to
models (dict or None, optional) –
Mapping of model ids to models (default: None)
This is needed in cases where the attributes to update also have values that have references.
setter (ClientSession or ServerSession or None, optional) –
This is used to prevent “boomerang” updates to Bokeh apps. (default: None)
In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
- Returns
None