Anaconda Enterprise: Documentation

# 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 familar “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 `bokeh.core.property.descriptors.``PropertyDescriptor`(name)

  Base class for a python descriptor that delegates access for a named attribute to a Bokeh |Property| instance.

  `__init__`(name)

    Create a descriptor for a hooking up a named Bokeh property as an attribute on a |HasProps| class.

    Parameters: | name (str) – the attribute name that this descriptor is for

  `__str__`()

    Basic string representation of `PropertyDescriptor`.

    Subclasses must implement this to serve their specific needs.

  `__get__`(obj, owner)

    Implement the getter for the Python descriptor protocol.

    Parameters:

    - obj (HasProps or None) – The instance to set a new property value on (for instance attribute access), or None (for class attribute access)
    - owner (obj) – The new value to set the property to

    Returns: | None
    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `__set__`(obj, value, setter=None)

    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
    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `__delete__`(obj)

    Implement the deleter for the Python descriptor protocol.

    Parameters: | obj (HasProps) – An instance to delete this property from
    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `add_prop_descriptor_to_class`(class_name, new_class_attrs, names_with_refs, container_names, dataspecs)

    `MetaHasProps` calls this during class creation as it iterates over properties to add, to update its registry of new properties.

    The parameters passed in are mutable and this function is expected to update them accordingly.

    Parameters:

    - class_name (str) – name of the class this descriptor is added to
    - new_class_attrs (dict[str, PropertyDescriptor]) – mapping of attribute names to PropertyDescriptor that this function will update
    - names_with_refs (set[str]) – set of all property names for properties that also have references, that this function will update
    - container_names (set[str]) – set of all property names for properties that are container props, that this function will update
    - dataspecs (dict[str, PropertyDescriptor]) – mapping of attribute names to PropertyDescriptor for DataSpec properties that this function will update

    Returns: | None

  `class_default`(cls)

    The default as computed for a certain class, ignoring any per-instance theming.

    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `serializable_value`(obj)

    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, json, models=None, setter=None)

    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, old)

    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

    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `has_ref`

    Whether the property can refer to another `HasProps` instance.

    This is typically True for container properties, `Instance`, etc.

    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `readonly`

    Whether this property is read-only.

    Read-only properties may only be modified by the client (i.e., by BokehJS, in the browser). Read only properties are useful for quantities that originate or that can only be computed in the browser, for instance the “inner” plot dimension of a plot area, which depend on the current layout state. It is useful for Python callbacks to be able to know these values, but they can only be computed in the actual browser.

    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

  `serialized`

    Whether the property should be serialized when serializing an object.

    This would be False for a “virtual” or “convenience” property that duplicates information already available in other properties, for example.

    Raises: | `NotImplementedError`

    Subclasses must implement this to serve their specific needs.

class `bokeh.core.property.descriptors.``BasicPropertyDescriptor`(name, property)

  A PropertyDescriptor for basic Bokeh properties (e.g, `Int`, `String`, `Float`, etc.) with simple get/set and serialization behavior.

  `__init__`(name, property)

    Create a PropertyDescriptor for basic Bokeh properties.

    Parameters:

    - name (str) – The attribute name that this property is for
    - property (Property) – A basic property to create a descriptor for

  `__str__`()

    Basic string representation of `BasicPropertyDescriptor`.

    Delegates to `self.property.__str__`

  `__get__`(obj, owner)

    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:

    - obj (HasProps or None) – The instance to set a new property value on (for instance attribute access), or None (for class attribute access)
    - owner (obj) – The new value to set the property to

    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.BasicPropertyDescriptor at 0x1148b3390>

  `__set__`(obj, value, setter=None)

    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)

    Implement the deleter for the Python descriptor protocol.

    Parameters: | obj (HasProps) – An instance to delete this property from

  `class_default`(cls)

    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)

    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

  `set_from_json`(obj, json, models=None, setter=None)

    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

  `trigger_if_changed`(obj, old)

    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

  `has_ref`

    Whether the property can refer to another `HasProps` instance.

    For basic properties, delegate to the `has_ref` attribute on the |Property|.

  `readonly`

    Whether this property is read-only.

    Read-only properties may only be modified by the client (i.e., by BokehJS in the browser).

  `serialized`

    Whether the property should be serialized when serializing an object.

    This would be False for a “virtual” or “convenience” property that duplicates information already available in other properties, for example.

class `bokeh.core.property.descriptors.``ColumnDataPropertyDescriptor`(name, property)

  A PropertyDescriptor specialized to handling `ColumnData` properties.

  `__set__`(obj, value, setter=None)

    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 `bokeh.core.property.descriptors.``DataSpecPropertyDescriptor`(name, property)

  A PropertyDescriptor for Bokeh |DataSpec| properties that serialize to field/value dictionaries.

  `serializable_value`(obj)
  `set_from_json`(obj, json, models=None, setter=None)

    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 `bokeh.core.property.descriptors.``UnitsSpecPropertyDescriptor`(name, property, units_property)

  A PropertyDecscriptor for Bokeh |UnitsSpec| properties that contribute associated `_units` properties automatically as a side effect.

  `__init__`(name, property, units_property)

    Parameters:

    - name (str) – The attribute name that this property is for
    - property (Property) – A basic property to create a descriptor for
    - units_property (Property) – An associated property to hold units information

  `__set__`(obj, value, setter=None)

    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)

    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 superclass `set_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