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:
ABCThe 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 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_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_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_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