crystal_toolkit.core.mpcomponent module

class crystal_toolkit.core.mpcomponent.MPComponent(default_data: MSONable | dict | str | None = None, id: str | None = None, links: dict[str, str] | None = None, storage_type: Literal['memory', 'local', 'session'] = 'memory', disable_callbacks: bool = False)[source]

Bases: ABC

The abstract base class for an MPComponent. MPComponent is designed to help render an MSONable object.

static all_app_stores() Div[source]

This must be included somewhere in your Crystal Toolkit Dash app’s layout for interactivity to work. This is a hidden element that contains the MSON for each MPComponent.

Returns: a html.Div Dash Layout

property all_ids: list[str]

List of all ids generated by this component

Type

return

property all_stores: list[str]

List of all store ids generated by this component

Type

return

app = None
cache = None
create_store(name: str, initial_data: MSONable | dict | str | None = None, storage_type: Literal['memory', 'local', 'session'] = 'memory', debug_clear: bool = False)[source]

Generate a dcc.Store to hold something (MSONable object, Dict or string), and register it so that it will be included in the Dash app automatically.

The initial data will be stored in a class attribute as self._initial_data[name].

Parameters
  • name – name for the store

  • initial_data – initial data to include

  • storage_type – as in dcc.Store

  • debug_clear – set to True to empty the store if using

  • storage (persistent) –

static crystal_toolkit_layout(layout: Div) Div[source]
static datauri_from_fig(fig, fmt: str = 'png', width: int = 600, height: int = 400, scale: int = 4) str[source]

Generate a data URI from a Plotly Figure.

Parameters
  • fig – Plotly Figure object or corresponding dictionary

  • fmt – “png”, “jpg”, etc. (see PlotlyScope for supported formats)

  • width – width in pixels

  • height – height in pixels

  • scale – scale factor

Returns

static from_data(data)[source]

Converts the contents of a dcc.Store back into a Python object. :param data: contents of a dcc.Store created by to_data :return: a Python object

generate_callbacks(app, cache)[source]

Generate all callbacks associated with the layouts in this app. Assume that “suppress_callback_exceptions” is True, since it is not always guaranteed that all layouts will be displayed to the end user at all times, but it’s important the callbacks are defined on the server.

get_all_kwargs_id() dict[source]
Returns

get_bool_input(kwarg_label: str, default: bool | None = None, state: dict | None = None, label: str | None = None, help_str: str = None, **kwargs)[source]

For Python classes which take boolean values as inputs, this will generate a corresponding Dash input layout.

Parameters

kwarg_label – The name of the corresponding Python input, this is used

to name the component. :param label: A description for this input. :param default: A default value for this input. :param state: Used to set default state for this input, use a dict with the

kwarg_label as a key

and the default value as a value. Ignored if default is set. It can be useful

to use state if you want to set defaults for multiple inputs from a single dictionary.

Parameters

help_str – Text for a tooltip when hovering over label.

Returns

a Dash layout

get_choice_input(kwarg_label: str, default: str | None = None, state: dict | None = None, label: str | None = None, help_str: str = None, options: list[dict] | None = None, clearable: bool = False, **kwargs)[source]

For Python classes which take pre-defined values as inputs, this will generate a corresponding input layout using mpc.Select.

Parameters

kwarg_label – The name of the corresponding Python input, this is used

to name the component. :param label: A description for this input. :param default: A default value for this input. :param state: Used to set default state for this input, use a dict with the kwarg_label as a key and the default value as a value. Ignored if default is set. It can be useful to use state if you want to set defaults for multiple inputs from a single dictionary. :param help_str: Text for a tooltip when hovering over label. :param options: Options to choose from, as per dcc.Dropdown :param clearable: If True, will allow Dropdown to be cleared after a selection is made. :return: a Dash layout

get_dict_input(kwarg_label: str, default: Any | None = None, state: dict | None = None, label: str | None = None, help_str: str = None, key_name: str = 'key', value_name: str = 'value')[source]
Parameters
  • kwarg_label

  • default

  • state

  • label

  • help_str

  • key_name

  • value_name

Returns

get_figure_placeholder(figure_id: str) Div[source]

Get a layout to act as a placeholder for an interactive figure.

When used with generate_static_figure_callbacks, and assuming kaleido is installed on the server, a static image placeholder will be generated.

Returns

get_kwarg_id(kwarg_name) dict[source]
Parameters

kwarg_name

Returns

get_numerical_input(kwarg_label: str, default: int | float | list | None = None, state: dict | None = None, label: str | None = None, help_str: str = None, is_int: bool = False, shape: tuple[int, ...] = (), **kwargs)[source]

For Python classes which take matrices as inputs, this will generate a corresponding Dash input layout.

Parameters

kwarg_label – The name of the corresponding Python input, this is used

to name the component. :param label: A description for this input. :param default: A default value for this input. :param state: Used to set default state for this input, use a dict with the kwarg_label as a key and the default value as a value. Ignored if default is set. It can be useful to use state if you want to set defaults for multiple inputs from a single dictionary. :param help_str: Text for a tooltip when hovering over label. :param is_int: if True, will use a numeric input :param shape: (3, 3) for matrix, (1, 3) for vector, (1, 1) for scalar :return: a Dash layout

get_slider_input(kwarg_label: str, default: Any | None = None, state: dict = None, label: str | None = None, help_str: str = None, multiple: bool = False, **kwargs)[source]
id(name: str = 'default', is_kwarg: bool = False, idx=False, hint=None, is_store: bool = False) str | dict[str, str][source]

Generate an id from a name combined with the base id of the MPComponent itself, useful for generating ids of individual components in the layout.

In the special case of the id of an element that is used to re-construct a keyword argument for a specific class, it will store information necessary to reconstruct that keyword argument (e.g. its type hint and, in the case of a vector or matrix, the corresponding index).

A hint could be a tuple for a numpy array of that shape, e.g. (3, 3) for a 3x3 matrix, (1, 3) for a vector, or “literal” to parse kwarg value using ast.literal_eval, or “bool” to parse a boolean value. In future iterations, we may be able to replace this with native Python type hints. The problem here is being able to specify array shape where appropriate.

Parameters

name – e.g. “default”

Returns: e.g. “MPComponent_default”

property initial_data

Initial data for all the stores defined by component, keyed by store name.

Type

return

layout() Div[source]
Returns

A Dash layout for the full component. Basic implementation

provided, but should in general be overridden.

reconstruct_kwarg_from_state(state, kwarg_name)[source]
reconstruct_kwargs_from_state(state=None, kwarg_labels=None) dict[source]

Generate

Parameters
  • state – optional, a Dash callback context input or state

  • kwarg_labels – optional, parse only a specific kwarg or list of kwargs

Returns

A dictionary of keyword arguments with their values

static register_app(app: Dash)[source]

This method must be called at least once in your Crystal Toolkit Dash app if you want to enable interactivity with the MPComponents. The “app” variable is a special global variable used by Dash/Flask, and registering it with MPComponent allows callbacks to be registered with the app on instantiation.

Parameters

app – a Dash app instance

static register_cache(cache: Cache)[source]

This method must be called at least once in your Crystal Toolkit Dash app if you want to enable callback caching. Callback caching is one of the easiest ways to see significant performance improvements, especially for callbacks that are computationally expensive.

Parameters

cache – a flask_caching Cache instance

static register_crystal_toolkit(app, layout, cache=None)[source]