Source code for bokeh.layouts

#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2024, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
''' Functions for arranging bokeh layout objects.

'''

#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import annotations

import logging # isort:skip
log = logging.getLogger(__name__)

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------

# Standard library imports
import math
from collections import defaultdict
from typing import (
    TYPE_CHECKING,
    Any,
    Callable,
    Iterable,
    Iterator,
    Literal,
    Sequence,
    TypeVar,
    Union,
    overload,
)

# Bokeh imports
from .core.enums import Location, LocationType, SizingModeType
from .core.property.singletons import Undefined, UndefinedType
from .models import (
    Column,
    CopyTool,
    ExamineTool,
    FlexBox,
    FullscreenTool,
    GridBox,
    GridPlot,
    LayoutDOM,
    Plot,
    Row,
    SaveTool,
    Spacer,
    Tool,
    Toolbar,
    ToolProxy,
    UIElement,
)
from .util.dataclasses import dataclass
from .util.warnings import warn

if TYPE_CHECKING:
    from typing_extensions import TypeAlias

#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------

__all__ = (
    'column',
    'grid',
    'gridplot',
    'layout',
    'row',
    'Spacer',
)

if TYPE_CHECKING:
    ToolbarOptions = Literal["logo", "autohide", "active_drag", "active_inspect", "active_scroll", "active_tap", "active_multi"]

#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------

@overload
def row(children: list[UIElement], *, sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Row: ...
@overload
def row(*children: UIElement, sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Row: ...

[docs] def row(*children: UIElement | list[UIElement], sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Row: """ Create a row of Bokeh Layout objects. Forces all objects to have the same sizing_mode, which is required for complex layouts to work. Args: children (list of :class:`~bokeh.models.LayoutDOM` ): A list of instances for the row. Can be any of the following - |Plot|, :class:`~bokeh.models.Widget`, :class:`~bokeh.models.Row`, :class:`~bokeh.models.Column`, :class:`~bokeh.models.Spacer`. sizing_mode (``"fixed"``, ``"stretch_both"``, ``"scale_width"``, ``"scale_height"``, ``"scale_both"`` ): How will the items in the layout resize to fill the available space. Default is ``"fixed"``. For more information on the different modes see :attr:`~bokeh.models.LayoutDOM.sizing_mode` description on :class:`~bokeh.models.LayoutDOM`. Returns: Row: A row of LayoutDOM objects all with the same sizing_mode. Examples: >>> row(plot1, plot2) >>> row(children=[widgets, plot], sizing_mode='stretch_both') """ _children = _parse_children_arg(*children, children=kwargs.pop("children", None)) _handle_child_sizing(_children, sizing_mode, widget="row") return Row(children=_children, sizing_mode=sizing_mode, **kwargs)
@overload def column(children: list[UIElement], *, sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Column: ... @overload def column(*children: UIElement, sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Column: ...
[docs] def column(*children: UIElement | list[UIElement], sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Column: """ Create a column of Bokeh Layout objects. Forces all objects to have the same sizing_mode, which is required for complex layouts to work. Args: children (list of :class:`~bokeh.models.LayoutDOM` ): A list of instances for the column. Can be any of the following - |Plot|, :class:`~bokeh.models.Widget`, :class:`~bokeh.models.Row`, :class:`~bokeh.models.Column`, :class:`~bokeh.models.Spacer`. sizing_mode (``"fixed"``, ``"stretch_both"``, ``"scale_width"``, ``"scale_height"``, ``"scale_both"`` ): How will the items in the layout resize to fill the available space. Default is ``"fixed"``. For more information on the different modes see :attr:`~bokeh.models.LayoutDOM.sizing_mode` description on :class:`~bokeh.models.LayoutDOM`. Returns: Column: A column of LayoutDOM objects all with the same sizing_mode. Examples: >>> column(plot1, plot2) >>> column(children=[widgets, plot], sizing_mode='stretch_both') """ _children = _parse_children_arg(*children, children=kwargs.pop("children", None)) _handle_child_sizing(_children, sizing_mode, widget="column") return Column(children=_children, sizing_mode=sizing_mode, **kwargs)
[docs] def layout(*args: UIElement, children: list[UIElement] | None = None, sizing_mode: SizingModeType | None = None, **kwargs: Any) -> Column: """ Create a grid-based arrangement of Bokeh Layout objects. Args: children (list of lists of :class:`~bokeh.models.LayoutDOM` ): A list of lists of instances for a grid layout. Can be any of the following - |Plot|, :class:`~bokeh.models.Widget`, :class:`~bokeh.models.Row`, :class:`~bokeh.models.Column`, :class:`~bokeh.models.Spacer`. sizing_mode (``"fixed"``, ``"stretch_both"``, ``"scale_width"``, ``"scale_height"``, ``"scale_both"`` ): How will the items in the layout resize to fill the available space. Default is ``"fixed"``. For more information on the different modes see :attr:`~bokeh.models.LayoutDOM.sizing_mode` description on :class:`~bokeh.models.LayoutDOM`. Returns: Column: A column of ``Row`` layouts of the children, all with the same sizing_mode. Examples: >>> layout([[plot_1, plot_2], [plot_3, plot_4]]) >>> layout( children=[ [widget_1, plot_1], [slider], [widget_2, plot_2, plot_3] ], sizing_mode='fixed', ) """ _children = _parse_children_arg(*args, children=children) return _create_grid(_children, sizing_mode, **kwargs)
[docs] def gridplot( children: list[list[UIElement | None]], *, sizing_mode: SizingModeType | None = None, toolbar_location: LocationType | None = "above", ncols: int | None = None, width: int | None = None, height: int | None = None, toolbar_options: dict[ToolbarOptions, Any] | None = None, merge_tools: bool = True) -> GridPlot: ''' Create a grid of plots rendered on separate canvases. The ``gridplot`` function builds a single toolbar for all the plots in the grid. ``gridplot`` is designed to layout a set of plots. For general grid layout, use the :func:`~bokeh.layouts.layout` function. Args: children (list of lists of |Plot|): An array of plots to display in a grid, given as a list of lists of Plot objects. To leave a position in the grid empty, pass None for that position in the children list. OR list of |Plot| if called with ncols. sizing_mode (``"fixed"``, ``"stretch_both"``, ``"scale_width"``, ``"scale_height"``, ``"scale_both"`` ): How will the items in the layout resize to fill the available space. Default is ``"fixed"``. For more information on the different modes see :attr:`~bokeh.models.LayoutDOM.sizing_mode` description on :class:`~bokeh.models.LayoutDOM`. toolbar_location (``above``, ``below``, ``left``, ``right`` ): Where the toolbar will be located, with respect to the grid. Default is ``above``. If set to None, no toolbar will be attached to the grid. ncols (int, optional): Specify the number of columns you would like in your grid. You must only pass an un-nested list of plots (as opposed to a list of lists of plots) when using ncols. width (int, optional): The width you would like all your plots to be height (int, optional): The height you would like all your plots to be. toolbar_options (dict, optional) : A dictionary of options that will be used to construct the grid's toolbar (an instance of :class:`~bokeh.models.Toolbar`). If none is supplied, Toolbar's defaults will be used. merge_tools (``True``, ``False``): Combine tools from all child plots into a single toolbar. Returns: GridPlot: Examples: >>> gridplot([[plot_1, plot_2], [plot_3, plot_4]]) >>> gridplot([plot_1, plot_2, plot_3, plot_4], ncols=2, width=200, height=100) >>> gridplot( children=[[plot_1, plot_2], [None, plot_3]], toolbar_location='right' sizing_mode='fixed', toolbar_options=dict(logo='gray') ) ''' if toolbar_options is None: toolbar_options = {} if toolbar_location: if not hasattr(Location, toolbar_location): raise ValueError(f"Invalid value of toolbar_location: {toolbar_location}") children = _parse_children_arg(children=children) if ncols: if any(isinstance(child, list) for child in children): raise ValueError("Cannot provide a nested list when using ncols") children = list(_chunks(children, ncols)) # Additional children set-up for grid plot if not children: children = [] # Make the grid toolbars: list[Toolbar] = [] items: list[tuple[UIElement, int, int]] = [] for y, row in enumerate(children): for x, item in enumerate(row): if item is None: continue elif isinstance(item, LayoutDOM): if merge_tools: for plot in item.select(dict(type=Plot)): toolbars.append(plot.toolbar) plot.toolbar_location = None if width is not None: item.width = width if height is not None: item.height = height if sizing_mode is not None and _has_auto_sizing(item): item.sizing_mode = sizing_mode items.append((item, y, x)) elif isinstance(item, UIElement): continue else: raise ValueError("Only UIElement and LayoutDOM items can be inserted into a grid") def merge(cls: type[Tool], group: list[Tool]) -> Tool | ToolProxy | None: if issubclass(cls, (SaveTool, CopyTool, ExamineTool, FullscreenTool)): return cls() else: return None tools: list[Tool | ToolProxy] = [] for toolbar in toolbars: tools.extend(toolbar.tools) if merge_tools: tools = group_tools(tools, merge=merge) logos = [ toolbar.logo for toolbar in toolbars ] autohides = [ toolbar.autohide for toolbar in toolbars ] active_drags = [ toolbar.active_drag for toolbar in toolbars ] active_inspects = [ toolbar.active_inspect for toolbar in toolbars ] active_scrolls = [ toolbar.active_scroll for toolbar in toolbars ] active_taps = [ toolbar.active_tap for toolbar in toolbars ] active_multis = [ toolbar.active_multi for toolbar in toolbars ] V = TypeVar("V") def assert_unique(values: list[V], name: ToolbarOptions) -> V | UndefinedType: if name in toolbar_options: return toolbar_options[name] n = len(set(values)) if n == 0: return Undefined elif n > 1: warn(f"found multiple competing values for 'toolbar.{name}' property; using the latest value") return values[-1] logo = assert_unique(logos, "logo") autohide = assert_unique(autohides, "autohide") active_drag = assert_unique(active_drags, "active_drag") active_inspect = assert_unique(active_inspects, "active_inspect") active_scroll = assert_unique(active_scrolls, "active_scroll") active_tap = assert_unique(active_taps, "active_tap") active_multi = assert_unique(active_multis, "active_multi") toolbar = Toolbar( tools=tools, logo=logo, autohide=autohide, active_drag=active_drag, active_inspect=active_inspect, active_scroll=active_scroll, active_tap=active_tap, active_multi=active_multi, ) gp = GridPlot( children=items, toolbar=toolbar, toolbar_location=toolbar_location, sizing_mode=sizing_mode, ) return gp
# XXX https://github.com/python/mypy/issues/731 @overload def grid(children: list[UIElement | list[UIElement | list[Any]]], *, sizing_mode: SizingModeType | None = ...) -> GridBox: ... @overload def grid(children: Row | Column, *, sizing_mode: SizingModeType | None = ...) -> GridBox: ... @overload def grid(children: list[UIElement | None], *, sizing_mode: SizingModeType | None = ..., nrows: int) -> GridBox: ... @overload def grid(children: list[UIElement | None], *, sizing_mode: SizingModeType | None = ..., ncols: int) -> GridBox: ... @overload def grid(children: list[UIElement | None], *, sizing_mode: SizingModeType | None = ..., nrows: int, ncols: int) -> GridBox: ... @overload def grid(children: str, *, sizing_mode: SizingModeType | None = ...) -> GridBox: ...
[docs] def grid(children: Any = [], sizing_mode: SizingModeType | None = None, nrows: int | None = None, ncols: int | None = None) -> GridBox: """ Conveniently create a grid of layoutable objects. Grids are created by using ``GridBox`` model. This gives the most control over the layout of a grid, but is also tedious and may result in unreadable code in practical applications. ``grid()`` function remedies this by reducing the level of control, but in turn providing a more convenient API. Supported patterns: 1. Nested lists of layoutable objects. Assumes the top-level list represents a column and alternates between rows and columns in subsequent nesting levels. One can use ``None`` for padding purpose. >>> grid([p1, [[p2, p3], p4]]) GridBox(children=[ (p1, 0, 0, 1, 2), (p2, 1, 0, 1, 1), (p3, 2, 0, 1, 1), (p4, 1, 1, 2, 1), ]) 2. Nested ``Row`` and ``Column`` instances. Similar to the first pattern, just instead of using nested lists, it uses nested ``Row`` and ``Column`` models. This can be much more readable that the former. Note, however, that only models that don't have ``sizing_mode`` set are used. >>> grid(column(p1, row(column(p2, p3), p4))) GridBox(children=[ (p1, 0, 0, 1, 2), (p2, 1, 0, 1, 1), (p3, 2, 0, 1, 1), (p4, 1, 1, 2, 1), ]) 3. Flat list of layoutable objects. This requires ``nrows`` and/or ``ncols`` to be set. The input list will be rearranged into a 2D array accordingly. One can use ``None`` for padding purpose. >>> grid([p1, p2, p3, p4], ncols=2) GridBox(children=[ (p1, 0, 0, 1, 1), (p2, 0, 1, 1, 1), (p3, 1, 0, 1, 1), (p4, 1, 1, 1, 1), ]) """ @dataclass class row: children: list[row | col] @dataclass class col: children: list[row | col] @dataclass class Item: layout: LayoutDOM r0: int c0: int r1: int c1: int @dataclass class Grid: nrows: int ncols: int items: list[Item] def flatten(layout) -> GridBox: def gcd(a: int, b: int) -> int: a, b = abs(a), abs(b) while b != 0: a, b = b, a % b return a def lcm(a: int, *rest: int) -> int: for b in rest: a = (a*b) // gcd(a, b) return a def nonempty(child: Grid) -> bool: return child.nrows != 0 and child.ncols != 0 def _flatten(layout: row | col | LayoutDOM) -> Grid: if isinstance(layout, row): children = list(filter(nonempty, map(_flatten, layout.children))) if not children: return Grid(0, 0, []) nrows = lcm(*[ child.nrows for child in children ]) ncols = sum(child.ncols for child in children) items: list[Item] = [] offset = 0 for child in children: factor = nrows//child.nrows for i in child.items: items.append(Item(i.layout, factor*i.r0, i.c0 + offset, factor*i.r1, i.c1 + offset)) offset += child.ncols return Grid(nrows, ncols, items) elif isinstance(layout, col): children = list(filter(nonempty, map(_flatten, layout.children))) if not children: return Grid(0, 0, []) nrows = sum(child.nrows for child in children) ncols = lcm(*[ child.ncols for child in children ]) items = [] offset = 0 for child in children: factor = ncols//child.ncols for i in child.items: items.append(Item(i.layout, i.r0 + offset, factor*i.c0, i.r1 + offset, factor*i.c1)) offset += child.nrows return Grid(nrows, ncols, items) else: return Grid(1, 1, [Item(layout, 0, 0, 1, 1)]) grid = _flatten(layout) children = [] for i in grid.items: if i.layout is not None: children.append((i.layout, i.r0, i.c0, i.r1 - i.r0, i.c1 - i.c0)) return GridBox(children=children) layout: row | col if isinstance(children, list): if nrows is not None or ncols is not None: N = len(children) if ncols is None: ncols = math.ceil(N/nrows) layout = col([ row(children[i:i+ncols]) for i in range(0, N, ncols) ]) else: def traverse(children: list[LayoutDOM], level: int = 0): if isinstance(children, list): container = col if level % 2 == 0 else row return container([ traverse(child, level+1) for child in children ]) else: return children layout = traverse(children) elif isinstance(children, LayoutDOM): def is_usable(child: LayoutDOM) -> bool: return _has_auto_sizing(child) and child.spacing == 0 def traverse(item: LayoutDOM, top_level: bool = False): if isinstance(item, FlexBox) and (top_level or is_usable(item)): container = col if isinstance(item, Column) else row return container(list(map(traverse, item.children))) else: return item layout = traverse(children, top_level=True) elif isinstance(children, str): raise NotImplementedError else: raise ValueError("expected a list, string or model") grid = flatten(layout) if sizing_mode is not None: grid.sizing_mode = sizing_mode for child in grid.children: layout = child[0] if _has_auto_sizing(layout): layout.sizing_mode = sizing_mode return grid
#----------------------------------------------------------------------------- # Dev API #----------------------------------------------------------------------------- T = TypeVar("T", bound=Tool) MergeFn: TypeAlias = Callable[[type[T], list[T]], Union[Tool, ToolProxy, None]] def group_tools(tools: list[Tool | ToolProxy], *, merge: MergeFn[Tool] | None = None, ignore: set[str] | None = None) -> list[Tool | ToolProxy]: """ Group common tools into tool proxies. """ @dataclass class ToolEntry: tool: Tool props: Any by_type: defaultdict[type[Tool], list[ToolEntry]] = defaultdict(list) computed: list[Tool | ToolProxy] = [] if ignore is None: ignore = {"overlay", "renderers"} for tool in tools: if isinstance(tool, ToolProxy): computed.append(tool) else: props = tool.properties_with_values() for attr in ignore: if attr in props: del props[attr] by_type[tool.__class__].append(ToolEntry(tool, props)) for cls, entries in by_type.items(): if merge is not None: merged = merge(cls, [entry.tool for entry in entries]) if merged is not None: computed.append(merged) continue while entries: head, *tail = entries group: list[Tool] = [head.tool] for item in list(tail): if item.props == head.props: group.append(item.tool) entries.remove(item) entries.remove(head) if len(group) == 1: computed.append(group[0]) elif merge is not None and (tool := merge(cls, group)) is not None: computed.append(tool) else: computed.append(ToolProxy(tools=group)) return computed #----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- def _has_auto_sizing(item: LayoutDOM) -> bool: return item.sizing_mode is None and item.width_policy == "auto" and item.height_policy == "auto" L = TypeVar("L", bound=LayoutDOM) def _parse_children_arg(*args: L | list[L], children: list[L] | None = None) -> list[L]: # Set-up Children from args or kwargs if len(args) > 0 and children is not None: raise ValueError("'children' keyword cannot be used with positional arguments") if not children: if len(args) == 1: [arg] = args if isinstance(arg, list): return arg return list(args) return children def _handle_child_sizing(children: list[UIElement], sizing_mode: SizingModeType | None, *, widget: str) -> None: for item in children: if isinstance(item, UIElement): continue if not isinstance(item, LayoutDOM): raise ValueError(f"Only LayoutDOM items can be inserted into a {widget}. Tried to insert: {item} of type {type(item)}") if sizing_mode is not None and _has_auto_sizing(item): item.sizing_mode = sizing_mode def _create_grid(iterable: Iterable[UIElement | list[UIElement]], sizing_mode: SizingModeType | None, layer: int = 0, **kwargs) -> Row | Column: """Recursively create grid from input lists.""" return_list: list[UIElement] = [] for item in iterable: if isinstance(item, list): return_list.append(_create_grid(item, sizing_mode, layer + 1)) elif isinstance(item, LayoutDOM): if sizing_mode is not None and _has_auto_sizing(item): item.sizing_mode = sizing_mode return_list.append(item) elif isinstance(item, UIElement): return_list.append(item) else: raise ValueError( f"""Only LayoutDOM items can be inserted into a layout. Tried to insert: {item} of type {type(item)}""", ) if layer % 2 == 0: return column(children=return_list, sizing_mode=sizing_mode, **kwargs) else: return row(children=return_list, sizing_mode=sizing_mode, **kwargs) I = TypeVar("I") def _chunks(l: Sequence[I], ncols: int) -> Iterator[Sequence[I]]: """Yield successive n-sized chunks from list, l.""" assert isinstance(ncols, int), "ncols must be an integer" for i in range(0, len(l), ncols): yield l[i: i + ncols] #----------------------------------------------------------------------------- # Code #-----------------------------------------------------------------------------