Contributing Python code¶
The Bokeh codebase combines code written in Python and TypeScript. This chapter provides an overview of the most important things to know when working on Bokeh’s Python code.
Bokeh’s Python code generally follows the PEP8 standard. Some notable exceptions include:
for consistency, use double quotation marks for strings (
don’t write lines that are longer than 165 characters
To learn more about running those tests on your system, see Run codebase tests.
Source code organization¶
The Python code for the Bokeh library itself is located in the bokeh folder.
Everything that comprises a Bokeh visualization (such as tools, glyphs, widgets, or ColumnDataSources) is based on a Bokeh model. The Python code for all models is located in bokeh/models. See Models and properties below for more information on models.
Other subdirectories in this folder include:
See the reference guide for more information on the structure of this directory and its subdirectories.
Models and properties¶
Whenever you update or add models in Python, you need to also update the corresponding TypeScript code for BokehJS.
class SomeNewModel(Model): """ Some new model. """
Models contain properties, which are class attributes defined in
bokeh.core.properties. For example:
class ModelWithIntProps(Model): prop1 = Int() prop2 = Int(10)
In this example, the
ModelWithIntProps model represents objects that have
two integer values,
Bokeh uses a wide variety of property types:
These property types have several purposes:
type checking the different models
automatically generating some basic documentation for the reference guide
An example of a more realistic model might look like this:
class SomeModel(Model): prop1 = Int(127) prop2 = Either(Int, List(Int), Dict(String, List(Int))) prop3 = Enum("x", "y", "z") prop4 = Range(Float, 0.0, 1.0) prop5 = List(Instance(Range1d))
See bokeh.core.properties for more details.
Any is the super-type of all other
types and will accept any type of value. Since this circumvents all type
validation, make sure to use it sparingly, if at all.
Bokeh uses two systems for type checking Python code:
For any code not using models, Bokeh uses PEP 484 style hints. Use the Python standard typing and typing_extensions modules if necessary.
In case you want to use type information with tools other than mypy (such as
extracting information with
typing.get_type_hints, for example), you
will most likely need to use Python 3.10 or later. This is because some
of Bokeh’s type hints use the
X | Y syntax for union types as defined in