crystal_toolkit.core.mpcomponent module — Crystal Toolkit documentation

# 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)

  Bases: `ABC`

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

  static all_app_stores() → Div

    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)

    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
  static datauri_from_fig(fig, fmt: str = 'png', width: int = 600, height: int = 400, scale: int = 4) → str

    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)

    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)

    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
    Returns

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

    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)

    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')
    Parameters

      - kwarg_label –

      - default –

      - state –

      - label –

      - help_str –

      - key_name –

      - value_name –

    Returns

  get_figure_placeholder(figure_id: str) → Div

    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
    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)

    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)
  id(name: str = 'default', is_kwarg: bool = False, idx=False, hint=None, is_store: bool = False) → str | dict[str, str]

    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
    Returns

      A Dash layout for the full component. Basic implementation

    provided, but should in general be overridden.

  reconstruct_kwarg_from_state(state, kwarg_name)
  reconstruct_kwargs_from_state(state=None, kwarg_labels=None) → dict

    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)

    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)

    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)