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 classes provide
for easy bulk addition of properties to model classes.
Below is the full class inheritance diagram for all standard Bokeh property
types. Click on any node to be taken to the corresponding documention.
Properties are objects that can be assigned as class level
attributes on Bokeh models, to provide automatic serialization
and validation.
For example, the following defines a model that has integer,
string, and list[float] properties:
class Model(HasProps):
foo = Int
bar = String
baz = List(Float)
The properties of this class can be initialized by specifying
keyword arguments to the initializer:
m = Model(foo=10, bar="a str", baz=[1,2,3,4])
But also by setting the attributes on an instance:
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):
File "<stdin>", line 1, in <module>
File "/Users/bryan/work/bokeh/bokeh/properties.py", line 585, in __setattr__
super(HasProps, self).__setattr__(name, value)
File "/Users/bryan/work/bokeh/bokeh/properties.py", line 159, in __set__
raise e
File "/Users/bryan/work/bokeh/bokeh/properties.py", line 152, in __set__
self.validate(value)
File "/Users/bryan/work/bokeh/bokeh/properties.py", line 707, in validate
(nice_join([ cls.__name__ for cls in self._underlying_type ]), value, type(value).__name__))
ValueError: expected a value of type int8, int16, int32, int64 or int, got 2.3 of type float
Additionally, properties know how to serialize themselves,
to be understood by BokehJS.
-
class
Angle(default=None, help=None)
Angle type property.
-
class
Any(default=None, help=None)
Any type property accepts any values.
-
class
Array(item_type, default=None, help=None)
NumPy array type property.
-
class
Bool(default=None, help=None)
Boolean type property.
-
class
Byte(default=0, help=None)
Byte type property.
-
class
Color(default=None, help=None)
Accepts color definition in a variety of ways, and produces an
appropriate serialization of its value for whatever backend.
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.)
-
class
Complex(default=None, help=None)
Complex floating point type property.
-
class
ContainerProperty(default=None, help=None)
Base class for Container-like type properties.
-
class
DashPattern(default=[], help=None)
Dash type property.
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
Date(default=datetime.date(2015, 9, 25), help=None)
Date (not datetime) type property.
-
class
Datetime(default=datetime.date(2015, 9, 25), help=None)
Datetime type property.
-
class
Dict(keys_type, values_type, default={}, help=None)
Python dict type property.
If a default value is passed in, then a shallow copy of it will be
used for each new use of this property.
-
class
Either(tp1, tp2, *type_params, **kwargs)
Takes a list of valid properties and validates against them in succession.
-
class
Enum(enum, *values, **kwargs)
An Enum with a list of allowed values. The first value in the list is
the default value, unless a default is provided with the “default” keyword
argument.
-
class
Event(default=None, help=None)
Event type property.
-
class
Float(default=None, help=None)
Floating point type property.
-
class
Function(default=None, help=None)
Function type property.
-
class
Include(delegate, help='', use_prefix=True)
Include other properties from mixin Models, with a given prefix.
-
class
Instance(instance_type, default=None, help=None)
Instance type property, for references to other Models in the object
graph.
-
class
Int(default=None, help=None)
Signed integer type property.
-
class
Interval(interval_type, start, end, default=None, help=None)
Range type property ensures values are contained inside a given interval.
-
class
JSON(default=None, help=None)
JSON type property validates that text values are valid JSON.
Note
The string 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.
-
class
List(item_type, default=[], help=None)
Python list type property.
-
class
ParameterizedProperty(default=None, help=None)
Base class for Properties that have type parameters, e.g.
List(String).
-
class
Percent(default=None, help=None)
Percentage type property.
Percents are useful for specifying alphas and coverage and extents; more
semantically meaningful than Float(0..1).
-
class
PrimitiveProperty(default=None, help=None)
A base class for simple property types. Subclasses should
define a class attribute _underlying_type that is a tuple
of acceptable type values for the property.
-
class
Property(default=None, help=None)
Base class for all type properties.
-
classmethod
autocreate(name=None)
Called by the metaclass to create a
new instance of this descriptor
if the user just assigned it to a property without trailing
parentheses.
-
class
Regex(regex, default=None, help=None)
Regex type property validates that text values match the
given regular expression.
-
class
RelativeDelta(default={}, help=None)
RelativeDelta type property for time deltas.
-
class
Seq(item_type, default=None, help=None)
Sequence (list, tuple) type property.
-
class
Size(default=None, help=None)
Size type property.
Note
Size is equivalent to an unsigned int.
-
class
String(default=None, help=None)
String type property.
-
class
This(default=None, help=None)
A reference to an instance of the class being defined.
-
class
Tuple(tp1, tp2, *type_params, **kwargs)
Tuple type property.
-
abstract(cls)
A phony decorator to mark abstract base classes.
-
field(name)
Convenience function do explicitly mark a field specification for
a Bokeh model property.
| Parameters: | name (str) – name of a data source field to reference for a property. |
|---|
| 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.
-
value(val)
Convenience function do explicitly mark a value specification for
a Bokeh model property.
| Parameters: | val (any) – a fixed value to specify for a property. |
|---|
| 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)
