bokeh.core.properties — Anaconda Enterprise 4.4 documentation

Anaconda Enterprise: Documentation

# bokeh.core.properties

In order to streamline and automate the creation and use of models that can for describing plots and scenes, Bokeh provides a collection of properties and property mixins. Property classes provide automatic validation and serialization for a large collection of useful types. Mixin and container classes provide for easy bulk addition of properties to model classes.

Properties are objects that can be assigned as class attributes on Bokeh models, to provide automatic serialization, validation, and documentation.

This documentation is broken down into the following sections:

- Overview
- Basic Properties
- Container Properties
- DataSpec Properties
  - Helpers
- Special Properties

## Overview

There are many property types defined in the module, for example `Int` to represent integral values, `Seq` to represent sequences (e.g. lists or tuples, etc.). Properties can also be combined: `Seq(Float)` represents a sequence of floating point values.

For example, the following defines a model that has integer, string, and list[float] properties:

    class SomeModel(Model):
        foo = Int
        bar = String(default="something")
        baz = List(Float, help="docs for baz prop")

As seen, properties can be declared as just the property type, e.g. `foo = Int`, in which case the properties are automatically instantiated on new Model objects. Or the property can be instantiated on the class, and configured with default values and help strings.

The properties of this class can be initialized by specifying keyword arguments to the initializer:

    m = SomeModel(foo=10, bar="a str", baz=[1,2,3,4])

But also by setting the attributes on an instance:

    m.foo = 20

Attempts to set a property to a value of the wrong type will result in a `ValueError` exception:

    >>> m.foo = 2.3
    Traceback (most recent call last):

      << traceback omitted >>

    ValueError: expected a value of type Integral, got 2.3 of type float

Models with properties know how to serialize themselves, to be understood by BokehJS. Additionally, any help strings provided on properties can be easily and automatically extracted with the Sphinx extensions in the bokeh.sphinxext module.

## Basic Properties

class `bokeh.core.properties.` `Angle`(default=None, help=None, serialized=True, readonly=False)

  Accept floating point angle values.

  `Angle` is equivalent to `Float` but is provided for cases when it is more semantically meaningful.

  Parameters: | default (float or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

class `bokeh.core.properties.` `Any`(default=None, help=None, serialized=True, readonly=False)

  Accept all values.

  The `Any` property does not do any validation or transformation.

  Parameters: | default (obj or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class AnyModel(HasProps):
      ...     prop = Any()
      ...

      >>> m = AnyModel()

      >>> m.prop = True

      >>> m.prop = 10

      >>> m.prop = 3.14

      >>> m.prop = "foo"

      >>> m.prop = [1, 2, 3]

class `bokeh.core.properties.` `Auto`

  Accepts only the string “auto”.

  Useful for properties that can be configured to behave “automatically”.

  Example

  This property is often most useful in conjunction with the `Either` property.

      >>> class AutoModel(HasProps):
      ...     prop = Either(Float, Auto)
      ...

      >>> m = AutoModel()

      >>> m.prop = 10.2

      >>> m.prop = "auto"

      >>> m.prop = "foo"      # ValueError !!

      >>> m.prop = [1, 2, 3]  # ValueError !!

class `bokeh.core.properties.` `Bool`(default=None, help=None, serialized=True, readonly=False)

  Accept boolean values.

  Parameters: | default (obj or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class BoolModel(HasProps):
      ...     prop = Bool(default=False)
      ...

      >>> m = BoolModel()

      >>> m.prop = True

      >>> m.prop = False

      >>> m.prop = 10  # ValueError !!

class `bokeh.core.properties.` `Byte`(default=0, help=None)

  Accept integral byte values (0-255).

  Example

      >>> class ByteModel(HasProps):
      ...     prop = Byte(default=0)
      ...

      >>> m = ByteModel()

      >>> m.prop = 255

      >>> m.prop = 256  # ValueError !!

      >>> m.prop = 10.3 # ValueError !!

class `bokeh.core.properties.` `Color`(default=None, help=None)

  Accept color values in a variety of ways.

  For colors, because we support named colors and hex values prefaced with a “#”, when we are handed a string value, there is a little interpretation: if the value is one of the 147 SVG named colors or it starts with a “#”, then it is interpreted as a value.

  If a 3-tuple is provided, then it is treated as an RGB (0..255). If a 4-tuple is provided, then it is treated as an RGBa (0..255), with alpha as a float between 0 and 1. (This follows the HTML5 Canvas API.)

  Example

      >>> class ColorModel(HasProps):
      ...     prop = Color()
      ...

      >>> m = ColorModel()

      >>> m.prop = "firebrick"

      >>> m.prop = "#a240a2"

      >>> m.prop = (100, 100, 255)

      >>> m.prop = (100, 100, 255, 0.5)

      >>> m.prop = "junk"              # ValueError !!

      >>> m.prop = (100.2, 57.3, 10.2) # ValueError !!

class `bokeh.core.properties.` `Complex`(default=None, help=None, serialized=True, readonly=False)

  Accept complex floating point values.

  Parameters: | default (complex or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

class `bokeh.core.properties.` `DashPattern`(default=[], help=None)

  Accept line dash specifications.

  Express patterns that describe line dashes. `DashPattern` values can be specified in a variety of ways:

  - An enum: “solid”, “dashed”, “dotted”, “dotdash”, “dashdot”
  - a tuple or list of integers in the HTML5 Canvas dash specification style. Note that if the list of integers has an odd number of elements, then it is duplicated, and that duplicated list becomes the new dash list.

  To indicate that dashing is turned off (solid lines), specify the empty list [].

class `bokeh.core.properties.` `Date`(default=None, help=None)

  Accept Date (but not DateTime) values.

class `bokeh.core.properties.` `Datetime`(default=datetime.date(2017, 11, 16), help=None)

  Accept Datetime values.

class `bokeh.core.properties.` `Either`(tp1, tp2, *type_params, **kwargs)

  Accept values according to a sequence of other property types.

  Example:

      >>> class EitherModel(HasProps):
      ...     prop = Either(Bool, Int, Auto)
      ...

      >>> m = EitherModel()

      >>> m.prop = True

      >>> m.prop = 10

      >>> m.prop = "auto"

      >>> m.prop = 10.3   # ValueError !!

      >>> m.prop = "foo"  # ValueError !!

class `bokeh.core.properties.` `Enum`(enum, *values, **kwargs)

  Accept values from enumerations.

  The first value in enumeration is used as the default value, unless the `default` keyword argument is used.

  See bokeh.core.enums for more information.

class `bokeh.core.properties.` `Float`(default=None, help=None, serialized=True, readonly=False)

  Accept floating point values.

  Parameters: | default (float or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class FloatModel(HasProps):
      ...     prop = Float()
      ...

      >>> m = FloatModel()

      >>> m.prop = 10

      >>> m.prop = 10.3

      >>> m.prop = "foo"  # ValueError !!

class `bokeh.core.properties.` `Instance`(instance_type, default=None, help=None)

  Accept values that are instances of |HasProps|.

class `bokeh.core.properties.` `Int`(default=None, help=None, serialized=True, readonly=False)

  Accept signed integer values.

  Parameters: | default (int or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class IntModel(HasProps):
      ...     prop = Int()
      ...

      >>> m = IntModel()

      >>> m.prop = 10

      >>> m.prop = -200

      >>> m.prop = 10.3  # ValueError !!

class `bokeh.core.properties.` `Interval`(interval_type, start, end, default=None, help=None)

  Accept numeric values that are contained within a given interval.

  Parameters: | interval_type (numeric property) – numeric types for the range, e.g. `Int`, `Float` start (number) – A minimum allowable value for the range. Values less than `start` will result in validation errors. end (number) – A maximum allowable value for the range. Values greater than `end` will result in validation errors.

  Example

      >>> class RangeModel(HasProps):
      ...     prop = Range(Float, 10, 20)
      ...

      >>> m = RangeModel()

      >>> m.prop = 10

      >>> m.prop = 20

      >>> m.prop = 15

      >>> m.prop = 2     # ValueError !!

      >>> m.prop = 22    # ValueError !!

      >>> m.prop = "foo" # ValueError !!

class `bokeh.core.properties.` `JSON`(default=None, help=None, serialized=True, readonly=False)

  Accept JSON string values.

  The value is transmitted and received by BokehJS as a string containing JSON content. i.e., you must use `JSON.parse` to unpack the value into a JavaScript hash.

  Parameters: | default (string or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

class `bokeh.core.properties.` `MinMaxBounds`(accept_datetime=False, default='auto', help=None)

  Accept (min, max) bounds tuples for use with Ranges.

  Bounds are provided as a tuple of `(min, max)` so regardless of whether your range is increasing or decreasing, the first item should be the minimum value of the range and the second item should be the maximum. Setting min > max will result in a `ValueError`.

  Setting bounds to None will allow your plot to pan/zoom as far as you want. If you only want to constrain one end of the plot, you can set min or max to `None` e.g. `DataRange1d(bounds=(None, 12))`

class `bokeh.core.properties.` `Percent`(default=None, help=None, serialized=True, readonly=False)

  Accept floating point percentage values.

  `Percent` can be useful and semantically meaningful for specifying things like alpha values and extents.

  Parameters: | default (float or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class PercentModel(HasProps):
      ...     prop = Percent()
      ...

      >>> m = PercentModel()

      >>> m.prop = 0.0

      >>> m.prop = 0.2

      >>> m.prop = 1.0

      >>> m.prop = -2  # ValueError !!

      >>> m.prop = 5   # ValueError !!

class `bokeh.core.properties.` `Regex`(regex, default=None, help=None)

  Accept strings that match a given regular expression.

  Parameters: | default (string or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class RegexModel(HasProps):
      ...     prop = Regex("foo[0-9]+bar")
      ...

      >>> m = RegexModel()

      >>> m.prop = "foo123bar"

      >>> m.prop = "foo"      # ValueError !!

      >>> m.prop = [1, 2, 3]  # ValueError !!

class `bokeh.core.properties.` `Size`(default=None, help=None, serialized=True, readonly=False)

  Accept non-negative numeric values.

  Parameters: | default (float or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class SizeModel(HasProps):
      ...     prop = Size()
      ...

      >>> m = SizeModel()

      >>> m.prop = 0

      >>> m.prop = 10e6

      >>> m.prop = -10   # ValueError !!

      >>> m.prop = "foo" # ValueError !!

class `bokeh.core.properties.` `String`(default=None, help=None, serialized=True, readonly=False)

  Accept string values.

  Parameters: | default (string or None, optional) – A default value for attributes created from this property to have (default: None) help (str or None, optional) – A documentation string for this property. It will be automatically used by the bokeh_prop extension when generating Spinx documentation. (default: None) serialized (bool, optional) – Whether attributes created from this property should be included in serialization (default: True) readonly (bool, optional) – Whether attributes created from this property are read-only. (default: False)

  Example

      >>> class StringModel(HasProps):
      ...     prop = String()
      ...

      >>> m = StringModel()

      >>> m.prop = "foo"

      >>> m.prop = 10.3       # ValueError !!

      >>> m.prop = [1, 2, 3]  # ValueError !!

class `bokeh.core.properties.` `TimeDelta`(default=datetime.timedelta(0), help=None)

  Accept TimeDelta values.

## Container Properties

class `bokeh.core.properties.` `Array`(item_type, default=None, help=None)

  Accept NumPy array values.

class `bokeh.core.properties.` `ColumnData`(keys_type, values_type, default={}, help=None)

  Accept a Python dictionary suitable as the `data` attribute of a `ColumnDataSource`.

  This class is a specialization of `Dict` that handles efficiently encoding columns that are NumPy arrays.

class `bokeh.core.properties.` `Dict`(keys_type, values_type, default={}, help=None)

  Accept Python dict values.

  If a default value is passed in, then a shallow copy of it will be used for each new use of this property.

class `bokeh.core.properties.` `List`(item_type, default=[], help=None)

  Accept Python list values.

class `bokeh.core.properties.` `RelativeDelta`(default={}, help=None)

  Accept RelativeDelta dicts for time delta values.

class `bokeh.core.properties.` `Seq`(item_type, default=None, help=None)

  Accept non-string ordered sequences of values, e.g. list, tuple, array.

class `bokeh.core.properties.` `Tuple`(tp1, tp2, *type_params, **kwargs)

  Accept Python tuple values.

## DataSpec Properties

class `bokeh.core.properties.` `AngleSpec`(default=None, units_default='rad', help=None)

  A |DataSpec| property that accepts numeric fixed values, and also provides an associated units property to store angle units.

  Acceptable values for units are `"rad"` and `"deg"`.

class `bokeh.core.properties.` `ColorSpec`(default, help=None, key_type=<bokeh.core.properties.Enum object>)

  A |DataSpec| property that accepts |Color| fixed values.

  The `ColorSpec` property attempts to first interpret string values as colors. Otherwise, string values are interpreted as field names. For example:

      m.color = "#a4225f"   # value (hex color string)

      m.color = "firebrick" # value (named CSS color string)

      m.color = "foo"       # field (named "foo")

  This automatic interpretation can be override using the dict format directly, or by using the |field| function:

      m.color = { "field": "firebrick" } # field (named "firebrick")

      m.color = field("firebrick")       # field (named "firebrick")

class `bokeh.core.properties.` `DataDistanceSpec`(default=None, help=None, key_type=<bokeh.core.properties.Enum object>, accept_datetime=True)

  A |DataSpec| property that accepts numeric fixed values for data-space distances, and also provides an associated units property that reports `"data"` as the units.

  Note

  Units are always `"data"`.

class `bokeh.core.properties.` `DataSpec`(key_type, value_type, default, help=None)

  Base class for properties that accept either a fixed value, or a string name that references a column in a `ColumnDataSource`.

  Many Bokeh models have properties that a user might want to set either to a single fixed value, or to have the property take values from some column in a data source. As a concrete example consider a glyph with an `x` property for location. We might want to set all the glyphs that get drawn to have the same location, say `x=10`. It would be convenient to just be able to write:

      glyph.x = 10

  Alternatively, maybe the each glyph that gets drawn should have a different location, according to the “pressure” column of a data source. In this case we would like to be able to write:

      glyph.x = "pressure"

  Bokeh `DataSpec` properties (and subclasses) afford this ease of and consistency of expression. Ultimately, all `DataSpec` properties resolve to dictionary values, with either a `"value"` key, or a `"field"` key, depending on how it is set.

  For instance:

      glyph.x = 10          # => { 'value': 10 }

      glyph.x = "pressure"  # => { 'field': 'pressure' }

  When these underlying dictionary dictionary values are received in the browser, BokehJS knows how to interpret them and take the correct, expected action (i.e., draw the glyph at `x=10`, or draw the glyph with `x` coordinates from the “pressure” column). In this way, both use-cases may be expressed easily in python, without having to handle anything differently, from the user perspective.

  It is worth noting that `DataSpec` properties can also be set directly with properly formed dictionary values:

      glyph.x = { 'value': 10 }         # same as glyph.x = 10

      glyph.x = { 'field': 'pressure' } # same as glyph.x = "pressure"

  Setting the property directly as a dict can be useful in certain situations. For instance some `DataSpec` subclasses also add a `"units"` key to the dictionary. This key is often set automatically, but the dictionary format provides a direct mechanism to override as necessary. Additionally, `DataSpec` can have a `"transform"` key, that specifies a client-side transform that should be applied to any fixed or field values before they are uses. As an example, you might want to apply a `Jitter` transform to the `x` values:

      glyph.x = { 'value': 10, 'transform': Jitter(width=0.4) }

  Note that `DataSpec` is not normally useful on its own. Typically, a model will define properties using one of the sublclasses such as `NumberSpec` or `ColorSpec`. For example, a Bokeh model with `x`, `y` and `color` properties that can handle fixed values or columns automatically might look like:

      class SomeModel(Model):

          x = NumberSpec(default=0, help="docs for x")

          y = NumberSpec(default=0, help="docs for y")

          color = ColorSpec(help="docs for color") # defaults to None

class `bokeh.core.properties.` `DistanceSpec`(default=None, units_default='data', help=None)

  A |DataSpec| property that accepts numeric fixed values or strings that refer to columns in a `ColumnDataSource`, and also provides an associated units property to store units information. Acceptable values for units are `"screen"` and `"data"`.

class `bokeh.core.properties.` `FontSizeSpec`(default, help=None, key_type=<bokeh.core.properties.Enum object>)

  A |DataSpec| property that accepts font-size fixed values.

  The `FontSizeSpec` property attempts to first interpret string values as font sizes (i.e. valid CSS length values). Otherwise string values are interpreted as field names. For example:

      m.font_size = "10pt"  # value

      m.font_size = "1.5em" # value

      m.font_size = "foo"   # field

  A full list of all valid CSS length units can be found here:

  https://drafts.csswg.org/css-values/#lengths

class `bokeh.core.properties.` `NumberSpec`(default=None, help=None, key_type=<bokeh.core.properties.Enum object>, accept_datetime=True)

  A |DataSpec| property that accepts numeric and datetime fixed values.

  By default, date and datetime values are immediately converted to milliseconds since epoch. It it possible to disable processing of datetime values by passing `accept_datetime=False`.

  Timedelta values are interpreted as absolute milliseconds.

      m.location = 10.3  # value

      m.location = "foo" # field

class `bokeh.core.properties.` `ScreenDistanceSpec`(default=None, help=None, key_type=<bokeh.core.properties.Enum object>, accept_datetime=True)

  A |DataSpec| property that accepts numeric fixed values for screen distances, and also provides an associated units property that reports `"screen"` as the units.

  Note

  Units are always `"screen"`.

class `bokeh.core.properties.` `StringSpec`(default, help=None, key_type=<bokeh.core.properties.Enum object>)

  A |DataSpec| property that accepts string fixed values.

  Because acceptable fixed values and field names are both strings, it can be necessary explicitly to disambiguate these possibilities. By default, string values are interpreted as fields, but the |value| function can be used to specify that a string should interpreted as a value:

      m.title = value("foo") # value

      m.title = "foo"        # field

class `bokeh.core.properties.` `UnitsSpec`(default, units_type, units_default, help=None)

  A |DataSpec| property that accepts numeric fixed values, and also provides an associated units property to store units information.

### Helpers

`bokeh.core.properties.` `field`(name, transform=None)

  Convenience function to explicitly return a “field” specification for a Bokeh `DataSpec` property.

  Parameters: | name (str) – name of a data source field to reference for a `DataSpec` property. transform (Transform, optional) – a transform to apply (default: None)
  Returns: | `{ "field": name }`
  Return type: | dict

  Note

  This function is included for completeness. String values for property specifications are by default interpreted as field names.

`bokeh.core.properties.` `value`(val, transform=None)

  Convenience function to explicitly return a “value” specification for a Bokeh `DataSpec` property.

  Parameters: | val (any) – a fixed value to specify for a `DataSpec` property. transform (Transform, optional) – a transform to apply (default: None)
  Returns: | `{ "value": name }`
  Return type: | dict

  Note

  String values for property specifications are by default interpreted as field names. This function is especially useful when you want to specify a fixed value with text properties.

  Example

      # The following will take text values to render from a data source
      # column "text_column", but use a fixed value "12pt" for font size
      p.text("x", "y", text="text_column",
             text_font_size=value("12pt"), source=source)

## Special Properties

class `bokeh.core.properties.` `Include`(delegate, help='', use_prefix=True)

  Include “mix-in” property collection in a Bokeh model.

  See bokeh.core.property_mixins for more details.

class `bokeh.core.properties.` `Override`(**kwargs)

  Override attributes of Bokeh property in derived Models.

  When subclassing a Bokeh Model, it may be desirable to change some of the attributes of the property itself, from those on the base class. This is accomplished using the `Override` class.

  Currently, `Override` can only be use to override the `default` value for the property.

  Keyword Arguments:
  | default (obj) – a default value for this property on a subclass

  Example

  Consider the following class definitions:

      from bokeh.model import Model
      from bokeh.properties import Int, Override

      class Parent(Model):
          foo = Int(default=10)

      class Child(Parent):
          foo = Override(default=20)

  The parent class has an integer property `foo` with default value 10. The child class uses the following code:

      foo = Override(default=20)

  to specify that the default value for the `foo` property should be 20 on instances of the child class:

      >>> p = Parent()
      >>> p.foo
      10

      >>> c = Child()
      >>> c.foo
      20