00_core.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [],
   "source": [
    "# default_exp core"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Library Documentation\n",
    "\n",
    "> API details for DashComponentBase, DashFigureFactory, DashComponent and DashApp"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from nbdev.showdoc import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 79,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "import sys\n",
    "from abc import ABC\n",
    "import inspect\n",
    "import types\n",
    "from importlib import import_module\n",
    "\n",
    "import shortuuid\n",
    "import oyaml as yaml\n",
    "from urllib.parse import urlparse, parse_qs, urlencode\n",
    "import ast\n",
    "\n",
    "import dash\n",
    "from dash import html, dcc\n",
    "import jupyter_dash\n",
    "\n",
    "import dash_bootstrap_components as dbc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 80,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "from dash.dependencies import Input, Output, State\n",
    "from dash.exceptions import PreventUpdate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DashComponentBase"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All classes in the library are derived from `DashComponentBase` which is a an abstract base class (ABC) that provides:\n",
    "\n",
    "- automatic storing of parameters to attributes\n",
    "- automatic storing of parameters to a `._stored_params` property\n",
    "- exporting component to a config dict with `.to_config()`\n",
    "- exporting component to a yaml file with `.to_yaml()`\n",
    "- building component from a config dict with classmethod `.from_config()`\n",
    "- building component from a yaml file with classmethod `.from_yaml()`\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "class DashComponentBase(ABC):  \n",
    "    \"\"\"Base class for all dash_oop_components classes. \n",
    "    \n",
    "    Stores parameter of child classes to attributes and ._stored_params.\n",
    "    Proved .to_config(), to_yaml(), .from_config() and .from_yaml() methods\n",
    "    \"\"\"\n",
    "    def __init__(self, no_store=None, no_attr=None, no_config=None, child_depth=3):\n",
    "        \"\"\"\n",
    "        Args:\n",
    "            no_store {list, bool}: either a list of parameters not to store or True, in which\n",
    "                case no parameters gets stored.\n",
    "            no_attr {list, bool}: either a list of parameter not to assign to attribute or True,\n",
    "                in which case no parameters get assigned to attributes\n",
    "            no_config {list, bool}: either a list of parameter not to store to ._stored_params\n",
    "                or True, in which case no parameters get saved to ._stored_params\n",
    "            child_depth (int): how deep the child is from which parameters will be read.\n",
    "                Defaults to 3 (i.e. The child of the child of DashComponentBase)\n",
    "        \"\"\"\n",
    "        self._store_child_params(no_store, no_attr, no_config, child_depth)\n",
    "\n",
    "    def _store_child_params(self, no_store=None, no_attr=None, no_config=None, child_depth=3):\n",
    "        \"\"\"\n",
    "        Args:\n",
    "            no_store {list, bool}: either a list of parameters not to store or True, in which\n",
    "                case no parameters gets stored.\n",
    "            no_attr {list, bool}: either a list of parameter not to assign to attribute or True,\n",
    "                in which case no parameters get assigned to attributes\n",
    "            no_config {list, bool}: either a list of parameter not to store to ._stored_params\n",
    "                or True, in which case no parameters get saved to ._stored_params\n",
    "            child_depth (int): how deep the child is from which parameters will be read.\n",
    "                Defaults to 3 (i.e. The child of the child of DashComponentBase)\n",
    "        \"\"\"\n",
    "             \n",
    "        if not hasattr(self, '_stored_params'): \n",
    "            self._stored_params = {}\n",
    "            \n",
    "        child_frame = sys._getframe(child_depth)\n",
    "        child_args = child_frame.f_code.co_varnames[1:child_frame.f_code.co_argcount]\n",
    "        child_dict = {arg: child_frame.f_locals[arg] for arg in child_args}\n",
    "        if 'kwargs' in child_frame.f_locals:\n",
    "            child_dict['kwargs'] = child_frame.f_locals['kwargs']\n",
    "        \n",
    "        if isinstance(no_store, bool) and no_store:\n",
    "            return\n",
    "        else:\n",
    "            if no_store is None: no_store = tuple()\n",
    "        \n",
    "        if isinstance(no_attr, bool) and no_attr: dont_attr = True\n",
    "        else:\n",
    "            if no_attr is None: no_attr = tuple()\n",
    "            dont_attr = False \n",
    "            \n",
    "        if isinstance(no_config, bool) and no_param: dont_config = True\n",
    "        else:\n",
    "            if no_config is None: no_config= tuple()\n",
    "            dont_config = False \n",
    "\n",
    "        for name, value in child_dict.items():\n",
    "            if name in {'dash_component', 'dash_figure_factory', 'dash_app'}:\n",
    "                raise ValueError(f\"Please do not use {name} as a parameter name, \"\n",
    "                                 \"as this results in a confusing and hard to parse config.\")\n",
    "            if not dont_attr and name not in no_store and name not in no_attr:\n",
    "                setattr(self, name, value)\n",
    "            if not dont_config and name not in no_store and name not in no_config:\n",
    "                self._stored_params[name] = value\n",
    "      \n",
    "    def to_config(self):\n",
    "        \"\"\"\n",
    "        returns a dict with class name, module and params \n",
    "        \"\"\"\n",
    "        return dict(dash_component=dict(\n",
    "            class_name=self.__class__.__name__, \n",
    "            module=self.__class__.__module__,\n",
    "            params=self._stored_params))\n",
    "        \n",
    "    def to_yaml(self, filepath=None):\n",
    "        \"\"\"\n",
    "        stores a yaml configuration to disk. \n",
    "        \n",
    "        If no filepath is given, returns a str of the yaml config.\n",
    "        \"\"\"\n",
    "        yaml_config = self.to_config()\n",
    "        if filepath is not None:\n",
    "            yaml.dump(yaml_config, open(filepath, \"w\"))\n",
    "            return\n",
    "        return yaml.dump(yaml_config)\n",
    "    \n",
    "    def dump(self, filepath=None):\n",
    "        \"\"\"store the object to disk. \n",
    "        \n",
    "        Default serializer is pickle, however depending on file suffix, \n",
    "        dill or joblib will be used.\"\"\"\n",
    "        if filepath is None and hasattr(self, \"filepath\"):\n",
    "            filepath = self.filepath\n",
    "        filepath = str(filepath)\n",
    "        if filepath.endswith(\".pkl\") or filepath.endswith(\".pickle\"):\n",
    "            import pickle\n",
    "            pickle.dump(self, open(filepath, \"wb\"))\n",
    "        elif filepath.endswith(\".dill\"):\n",
    "            import dill\n",
    "            dill.dump(self, open(filepath, \"wb\"))\n",
    "        elif str(filepath).endswith(\".joblib\"):\n",
    "            import joblib\n",
    "            joblib.dump(self, filepath)\n",
    "        else:\n",
    "            filepath = filepath + \".pkl\"\n",
    "            import pickle\n",
    "            pickle.dump(self, open(filepath, \"wb\"))\n",
    "    \n",
    "    @classmethod\n",
    "    def from_config(cls, config, try_pickles=False, force_pickles=False, **update_params):\n",
    "        \"\"\"\n",
    "        Loads a dash_oop_component class from a configuration dict.\n",
    "        \n",
    "        Args:\n",
    "            config (dict): configuration dict, generated from .to_config()\n",
    "            try_pickles (bool): when finding a filepath parameter try loading from that file,\n",
    "                if it fails, load from config\n",
    "            force_pickles (bool): when finding a filepath parameter try loading from that file,\n",
    "                if it fails, raise error\n",
    "            **update_params: kwargs that override settings in params\n",
    "        \n",
    "        Returns:\n",
    "            Instance of the class defined in the config.\n",
    "        \"\"\"\n",
    "        if 'dash_component' in config:\n",
    "            config = config['dash_component']\n",
    "        elif 'dash_figure_factory' in config:\n",
    "            config = config['dash_figure_factory']\n",
    "        elif 'dash_app' in config:\n",
    "            config = config['dash_app']\n",
    "        else:\n",
    "            raise ValueError(\"I only know how to build dash_component, \"\n",
    "                             \"dash_figure_factory and dash_app from config!\", str(config))\n",
    "        \n",
    "        \n",
    "        \n",
    "        params = config['params']\n",
    "        if not params: params = {}\n",
    "            \n",
    "        if (try_pickles or force_pickles) and 'filepath' in params and params['filepath'] is not None:\n",
    "            try:\n",
    "                filepath = params['filepath']\n",
    "                return cls.from_file(filepath)\n",
    "            except FileNotFoundError as e:\n",
    "                if force_pickles:\n",
    "                    raise FileNotFoundError(\n",
    "                        f\"Couldn't find {filepath}! Either change the filepath\"\n",
    "                        \" in the configuration or the yaml file, pass \"\n",
    "                        \"force_filepath=False or try_filepath=True, or pass the \"\n",
    "                        \"correct filepath as **kwargs...\")\n",
    "                else:\n",
    "                    print(f\"Couldn't find {filepath}! You could try passing correct filepath as kwarg.\"\n",
    "                          \"Now loading from config instead...\", flush=True)\n",
    "            \n",
    "        for k, v in update_params.items():\n",
    "            if k in params:\n",
    "                params[k] = v\n",
    "            elif 'kwargs' in params:\n",
    "                params['kwargs'][k]=v\n",
    "            else:\n",
    "                raise ValueError(f\"This dash_oop_component does not take {k} as an argument, \"\n",
    "                                \"nor does it take **kwargs!\")\n",
    "        \n",
    "        for k, v in params.items():\n",
    "            if isinstance(v, dict) and len(v)==1 and ('dash_figure_factory' in v or 'dash_component' in v):\n",
    "                if try_pickles or force_pickles:\n",
    "                    if ('dash_component' in v \n",
    "                        and 'filepath' in v['dash_component']['params']):\n",
    "                        filepath = v['dash_component']['params']['filepath']\n",
    "                    elif ('dash_figure_factory' in v \n",
    "                          and 'filepath' in v['dash_figure_factory']['params']):\n",
    "                        filepath = v['dash_figure_factory']['params']['filepath']\n",
    "                    else:\n",
    "                        filepath = None\n",
    "                    if filepath is not None:\n",
    "                        try:\n",
    "                            params[k] = DashComponentBase.from_file(filepath)\n",
    "                        except FileNotFoundError as e:\n",
    "                            if force_pickles:\n",
    "                                raise FileNotFoundError(\n",
    "                                    f\"Couldn't find {filepath}! Either change the filepath\"\n",
    "                                    \" in the configuration or the yaml file, pass \"\n",
    "                                    \"force_filepath=False or pass try_filepath=True\")\n",
    "                            else:\n",
    "                                print(f\"Couldn't find {filepath}! So loading from config instead...\", flush=True)\n",
    "                                params[k] = DashComponentBase.from_config(v)             \n",
    "                    else:\n",
    "                        params[k] = DashComponentBase.from_config(v)\n",
    "                else:\n",
    "                    params[k] = DashComponentBase.from_config(v)\n",
    "        \n",
    "        try:\n",
    "            component_class = getattr(import_module(config['module']), config['class_name'])\n",
    "        except ModuleNotFoundError:\n",
    "            import sys\n",
    "            from pathlib import Path\n",
    "            sys.path.append(str(Path.cwd()))\n",
    "            component_class = getattr(import_module(config['module']), config['class_name'])\n",
    "            \n",
    "        if 'kwargs' in params:\n",
    "            kwargs = params.pop('kwargs')\n",
    "        else:\n",
    "            kwargs = {}\n",
    "        \n",
    "        if \"name\" in params:\n",
    "            name = params.pop('name')\n",
    "        else:\n",
    "            name = None\n",
    "            \n",
    "        comp = component_class(**params, **kwargs)\n",
    "        if name is not None:\n",
    "            comp.name = name\n",
    "        return comp\n",
    "    \n",
    "    @classmethod\n",
    "    def from_yaml(cls, yaml_filepath, try_pickles=False, force_pickles=False,  **update_params):\n",
    "        \"\"\"\n",
    "        Loads a dash_oop_component class from a yaml file.\n",
    "        \n",
    "        Args:\n",
    "            yaml_filepath (str, Path): filepath of a .yaml file, generated from .to_yaml()\n",
    "            try_pickles (bool): when finding a filepath parameter try loading from that file,\n",
    "                if it fails, load from config\n",
    "            force_pickles (bool): when finding a filepath parameter try loading from that file,\n",
    "                if it fails, raise errors\n",
    "            update_params: a dict of parameters to be overridden by update_params\n",
    "        \n",
    "        Returns:\n",
    "            Instance of the class defined in the yaml file.\n",
    "        \"\"\"\n",
    "        config = yaml.safe_load(open(str(yaml_filepath), \"r\"))\n",
    "        return cls.from_config(config, try_pickles, force_pickles, **update_params)\n",
    "    \n",
    "    @classmethod\n",
    "    def from_file(cls, filepath):\n",
    "        \"\"\"Load a DashComponentBase from file. Depending on the suffix of the filepath \n",
    "        will either load with pickle ('.pkl'), dill ('.dill') or joblib ('joblib').\n",
    "        \n",
    "        If no suffix given, will try with pickle (and try adding ''.pkl')\n",
    "        \n",
    "        Args:\n",
    "            filepath {str, Path} the location of the stored component\n",
    "            \n",
    "        returns:\n",
    "            DashComponentBase\n",
    "        \"\"\"\n",
    "        filepath = str(filepath)\n",
    "        if filepath.endswith(\".pkl\") or str(filepath).endswith(\".pickle\"):\n",
    "            import pickle\n",
    "            return pickle.load(open(filepath, \"rb\"))\n",
    "        elif filepath.endswith(\".dill\"):\n",
    "            import dill\n",
    "            return dill.load(open(filepath, \"rb\"))\n",
    "        elif filepath.endswith(\".joblib\"):\n",
    "            import joblib\n",
    "            return joblib.load(filepath)\n",
    "        else:\n",
    "            from pathlib import Path\n",
    "            filepath = Path(filepath)\n",
    "            if not filepath.exists(): \n",
    "                if (filepath.parent / (filepath.name + \".pkl\")).exists():\n",
    "                    filepath = filepath.parent / (filepath.name + \".pkl\")\n",
    "                else:\n",
    "                    raise ValueError(f\"Cannot find file: {str(filepath)}\")\n",
    "            import pickle\n",
    "            return pickle.load(open(str(filepath), \"rb\"))\n",
    "        "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponentBase.to_config\" class=\"doc_header\"><code>DashComponentBase.to_config</code><a href=\"__main__.py#L68\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponentBase.to_config</code>()\n",
       "\n",
       "returns a dict with class name, module and params "
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponentBase.to_yaml\" class=\"doc_header\"><code>DashComponentBase.to_yaml</code><a href=\"__main__.py#L77\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponentBase.to_yaml</code>(**`filepath`**=*`None`*)\n",
       "\n",
       "stores a yaml configuration to disk. \n",
       "\n",
       "If no filepath is given, returns a str of the yaml config."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponentBase.from_config\" class=\"doc_header\"><code>DashComponentBase.from_config</code><a href=\"__main__.py#L111\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponentBase.from_config</code>(**`config`**, **`try_pickles`**=*`False`*, **`force_pickles`**=*`False`*, **\\*\\*`update_params`**)\n",
       "\n",
       "Loads a dash_oop_component class from a configuration dict.\n",
       "\n",
       "Args:\n",
       "    config (dict): configuration dict, generated from .to_config()\n",
       "    try_pickles (bool): when finding a filepath parameter try loading from that file,\n",
       "        if it fails, load from config\n",
       "    force_pickles (bool): when finding a filepath parameter try loading from that file,\n",
       "        if it fails, raise error\n",
       "    **update_params: kwargs that override settings in params\n",
       "\n",
       "Returns:\n",
       "    Instance of the class defined in the config."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponentBase.from_config\" class=\"doc_header\"><code>DashComponentBase.from_config</code><a href=\"__main__.py#L111\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponentBase.from_config</code>(**`config`**, **`try_pickles`**=*`False`*, **`force_pickles`**=*`False`*, **\\*\\*`update_params`**)\n",
       "\n",
       "Loads a dash_oop_component class from a configuration dict.\n",
       "\n",
       "Args:\n",
       "    config (dict): configuration dict, generated from .to_config()\n",
       "    try_pickles (bool): when finding a filepath parameter try loading from that file,\n",
       "        if it fails, load from config\n",
       "    force_pickles (bool): when finding a filepath parameter try loading from that file,\n",
       "        if it fails, raise error\n",
       "    **update_params: kwargs that override settings in params\n",
       "\n",
       "Returns:\n",
       "    Instance of the class defined in the config."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(DashComponentBase.to_config)\n",
    "show_doc(DashComponentBase.to_yaml)\n",
    "show_doc(DashComponentBase.from_config)\n",
    "show_doc(DashComponentBase.from_config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example use of DashComponentBase"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Define a class `T` as a childclass of `DashComponentBase` and initialize an instance `t`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 83,
   "metadata": {},
   "outputs": [],
   "source": [
    "class T(DashComponentBase): \n",
    "    def __init__(self, a=1, b=2, **kwargs):\n",
    "        super().__init__(child_depth=2)\n",
    "        \n",
    "t = T(a=2, b=3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get the configuration of the instance `t`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'dash_component': {'class_name': 'T', 'module': '__main__', 'params': {'a': 2, 'b': 3, 'kwargs': {}}}}\n"
     ]
    }
   ],
   "source": [
    "print(t.to_config())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Get the configuration in `yaml` format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: T\n",
      "  module: __main__\n",
      "  params:\n",
      "    a: 2\n",
      "    b: 3\n",
      "    kwargs: {}\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(t.to_yaml())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tests showing parameters have been assigned to attributes and  config stores all relevenat data to rebuild the instance from the config:\n",
    "- parameters have been assigned to attributes\n",
    "- class_name and module have been recorded\n",
    "- parameters have been recorded"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 86,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert t.a == 2\n",
    "assert t.b == 3\n",
    "assert t.to_config()['dash_component']['class_name'] == \"T\"\n",
    "assert t.to_config()['dash_component']['module'] == \"__main__\"\n",
    "assert t.to_config()['dash_component']['params']['a'] == t.a\n",
    "assert t.to_config()['dash_component']['params']['b'] == t.b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Store to yaml:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 87,
   "metadata": {},
   "outputs": [],
   "source": [
    "t.to_yaml(\"T.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Load from yaml and check that loaded instance `t2` is same as `t`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 88,
   "metadata": {},
   "outputs": [],
   "source": [
    "t2 = T.from_yaml(\"T.yaml\")\n",
    "\n",
    "assert t2.to_config()['dash_component']['class_name'] == \"T\"\n",
    "assert t2.to_config()['dash_component']['module'] == \"__main__\"\n",
    "assert t2.to_config()['dash_component']['params']['a'] == t.a\n",
    "assert t2.to_config()['dash_component']['params']['b'] == t.b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Override parameters upon loading:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 89,
   "metadata": {},
   "outputs": [],
   "source": [
    "t2 = T.from_yaml(\"T.yaml\", b=4)\n",
    "assert t2.b == 4"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If `**kwargs` in the class definition than unknown parameters get loads to `self.kwargs`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 90,
   "metadata": {},
   "outputs": [],
   "source": [
    "t2 = T.from_yaml(\"T.yaml\", c=5)\n",
    "assert hasattr(t2, \"kwargs\")\n",
    "assert \"c\" in t2.kwargs\n",
    "assert t2.kwargs[\"c\"] == 5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Store to file (\"pickle\", although also works with dill and joblib) and reload from file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 91,
   "metadata": {},
   "outputs": [],
   "source": [
    "t2.dump(\"t\") # stores to \"t.pkl\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 92,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: T\n",
      "  module: __main__\n",
      "  params:\n",
      "    a: 2\n",
      "    b: 3\n",
      "    kwargs:\n",
      "      c: 5\n",
      "\n"
     ]
    }
   ],
   "source": [
    "t3 = DashComponentBase.from_file(\"t.pkl\")\n",
    "print(t3.to_yaml())\n",
    "assert t3.kwargs[\"c\"] == 5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If suffix is \".pkl\" can simply leave it out. And you can load from any `DashComponentBase` child class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 93,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: T\n",
      "  module: __main__\n",
      "  params:\n",
      "    a: 2\n",
      "    b: 3\n",
      "    kwargs:\n",
      "      c: 5\n",
      "\n"
     ]
    }
   ],
   "source": [
    "t4 =  T.from_file(\"t\")\n",
    "print(t4.to_yaml())\n",
    "assert t4.kwargs[\"c\"] == 5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DashFigureFactory"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `DashFigureFactory` loads data and provides plots, tables, lists, dicts, etc that can be used for building your dashboard. \n",
    "\n",
    "This provides a clean seperation where all your data preparation and visualisation logic goes into one place (the `DashFigureFactory`) and all the dashboard layout and interaction logic goes into another (the `DashComponents`). This means that you only have to change the data representation in one place, and the whole dashboard will adapt.\n",
    "\n",
    "When used as a parameter to a `DashComponent` (e.g. parameter `figure_factory`)the parameter `figure_factory` gets replaced by the figure factory configuration dict. This means that a `DashComponent` automatically loads its underlying `DashFigureFactory` parameters upon load! \n",
    "\n",
    "In some cases you may perform a lot of costly calculations during the initialization of the `DashFigureFactory` (e.g. calculate SHAP values). In this case you may want to pickle the `DashFigureFactory` and reload it from file. If you add a parameter `filepath` to the parameters and `.dump()` the `DashFigureFactory`, then you can automatically reload it from pickle by adding `.from_yaml(\"component.yaml\", try_pickles=True)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 94,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "class DashFigureFactory(DashComponentBase):\n",
    "    \"\"\"\n",
    "    Helper class to store data for a dashboard and provide e.g. plotting functions.\n",
    "    \n",
    "    You should seperate the datastorage/plotting logic from the dashboard logic.\n",
    "    All data/plotting logic goes into a DashFigureFactory.\n",
    "    \n",
    "    All dashboard logic goes into a DashComponent.\n",
    "    \n",
    "    Stores to config under key 'dash_figure_factory'\n",
    "    \"\"\"\n",
    "    def __init__(self, no_store=None, no_attr=None, no_config=None):\n",
    "        super().__init__(no_store=None, no_attr=None, no_config=None)\n",
    "        \n",
    "    def to_config(self):\n",
    "        return dict(dash_figure_factory=dict(\n",
    "            class_name=self.__class__.__name__, \n",
    "            module=self.__class__.__module__,\n",
    "            params=self._stored_params))\n",
    "    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 95,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h2 id=\"DashFigureFactory\" class=\"doc_header\"><code>class</code> <code>DashFigureFactory</code><a href=\"\" class=\"source_link\" style=\"float:right\">[source]</a></h2>\n",
       "\n",
       "> <code>DashFigureFactory</code>(**`no_store`**=*`None`*, **`no_attr`**=*`None`*, **`no_config`**=*`None`*) :: [`DashComponentBase`](/dash_oop_components/core.html#DashComponentBase)\n",
       "\n",
       "Helper class to store data for a dashboard and provide e.g. plotting functions.\n",
       "\n",
       "You should seperate the datastorage/plotting logic from the dashboard logic.\n",
       "All data/plotting logic goes into a DashFigureFactory.\n",
       "\n",
       "All dashboard logic goes into a DashComponent.\n",
       "\n",
       "Stores to config under key 'dash_figure_factory'"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(DashFigureFactory)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example use of `DashFigureFactory`: `ListFactory`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A DashFigureFactory that simply stores a list and has a `return_list()` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 96,
   "metadata": {},
   "outputs": [],
   "source": [
    "class ListFactory(DashFigureFactory):\n",
    "    def __init__(self, list_input, filepath=None):\n",
    "        super().__init__()\n",
    "        \n",
    "    def list_length(self):\n",
    "        return len(self.list_input)\n",
    "        \n",
    "    def return_list(self, first_n_items=None):\n",
    "        if first_n_items is None: first_n_items = self.list_length()\n",
    "        if first_n_items <= len(self.list_input):\n",
    "            return self.list_input[:first_n_items]\n",
    "        return None"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 97,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['this', 'is', 'a', 'dumb', 'example']\n"
     ]
    }
   ],
   "source": [
    "list_factory = ListFactory([\"this\", \"is\", \"a\", \"dumb\", \"example\"], filepath=\"list_factory.pkl\")\n",
    "print(list_factory.return_list())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 98,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_figure_factory:\n",
      "  class_name: ListFactory\n",
      "  module: __main__\n",
      "  params:\n",
      "    list_input:\n",
      "    - this\n",
      "    - is\n",
      "    - a\n",
      "    - dumb\n",
      "    - example\n",
      "    filepath: list_factory.pkl\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(list_factory.to_yaml())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 99,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert list_factory.list_input == ['this', 'is', 'a', 'dumb', 'example']\n",
    "assert list_factory.return_list() == ['this', 'is', 'a', 'dumb', 'example']\n",
    "assert list_factory.return_list(2) == ['this', 'is']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Storing and loading from yaml:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_factory.to_yaml(\"list_factory.yaml\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 101,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_factory2 = DashFigureFactory.from_yaml(\"list_factory.yaml\")\n",
    "\n",
    "assert list_factory2.list_input == list_factory.list_input\n",
    "assert list_factory2.return_list() == list_factory.return_list()\n",
    "assert list_factory2.return_list(2) == list_factory.return_list(2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- If you use `force_pickles=True` but filepath does not exist, then it will throw a FileNotFoundError.\n",
    "- If you use `try_pickles=True` but filepath does not exist, then it will simply show a warning."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Couldn't find list_factory2.pkl! You could try passing correct filepath as kwarg.Now loading from config instead...\n"
     ]
    }
   ],
   "source": [
    "list_factory = ListFactory([\"this\", \"is\", \"a\", \"dumb\", \"example\"], filepath=\"list_factory2.pkl\")\n",
    "list_factory.to_yaml(\"list_factory2.yaml\")\n",
    "try:\n",
    "    ListFactory.from_yaml(\"list_factory2.yaml\", force_pickles=True)\n",
    "except Exception as e:\n",
    "    assert isinstance(e, FileNotFoundError)\n",
    "list_factory = ListFactory.from_yaml(\"list_factory2.yaml\", try_pickles=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So you have to make sure the file exists by dumping it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_factory = ListFactory([\"this\", \"is\", \"a\", \"dumb\", \"example\"], filepath=\"list_factory.pkl\")\n",
    "list_factory.to_yaml(\"list_factory.yaml\")\n",
    "list_factory.dump()\n",
    "list_factory2 = ListFactory.from_yaml(\"list_factory.yaml\", force_pickles=True)\n",
    "assert isinstance(list_factory2, ListFactory)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `DashComponent`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `DashComponent` combines a `dash` layout with `dash` callbacks. \n",
    "\n",
    "It provides:\n",
    "- a `.layout()` method that returns the layout for the component\n",
    "- a `.register_callbacks(app)` method that allow you to register the \n",
    "    callbacks of the component to a specific dash app\n",
    "- automatic conversion of any `DashFigureFactory` parameters to it's config \n",
    "    (this means that figure factory will be automatically loaded upon load)\n",
    "- automatic registration of all `DashComponent` subcomponents in its attributes\n",
    "    (which means that callbacks of all subcomponents will also automatically be registered)\n",
    "- a `make_hideable` staticmethod that makes it easy to hide parts of a layout \n",
    "    depending on configuration bools\n",
    "- a `querystring()` method that allows you to store the state of your dashboard in the url querystring,\n",
    "    and then load the state of the dashboard back from that url.\n",
    "    \n",
    "It inherits from `DashComponentBase` so:\n",
    "- All parameters are automatically stored to attributes and to `._stored_params`\n",
    "- Can be exported and loaded from config and yaml\n",
    "- Can be dumped to pickle/dill/joblib and loaded `.from_file()`\n",
    "\n",
    "**IMPORTANT**: \n",
    "\n",
    "- add `+self.name` to all the `id`'s in your layout to make sure layout `id`'s are unique.\n",
    "- define your callbacks in `_register_callbacks(self, app)` (**note the underscore!**)\n",
    "- If you're using `self.querystring(params)(...)`, then set the `self.name` of the component \n",
    "    to something definitive and readable, as otherwise each run it gets assigned a new random \n",
    "    uuid string everytime you reboot your app, breaking previously generated querystring urls.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "class DashComponent(DashComponentBase):\n",
    "    \"\"\"DashComponent is a bundle of a dash layout and callbacks that\n",
    "    can make use of DashFigureFactory objects. \n",
    "\n",
    "    A DashComponent can have DashComponent subcomponents, that\n",
    "    you register with register_components(). \n",
    "\n",
    "    DashComponents allow you to:\n",
    "\n",
    "    1. Write clean, re-usable, composable code for your dashboard\n",
    "    2. Store your dashboard to config files\n",
    "    3. Load your dashboard from config files\n",
    "\n",
    "    Each DashComponent should have a unique .name so that dash id's don't clash.\n",
    "    If no name is given, DashComponent generates a unique uuid name. This allows\n",
    "    for multiple instance of the same component type in a single layout. \n",
    "    But remember to add `+self.name` to all id's.\n",
    "\n",
    "    Important:\n",
    "        define your callbacks in `_register_callbacks()` (note underscore!) and\n",
    "        DashComponent will register callbacks of subcomponents in addition\n",
    "        to _register_callbacks() when calling register_callbacks()\n",
    "    \"\"\"\n",
    "    def __init__(self, title=\"Dash\", name=None, \n",
    "                 no_store=None, no_attr=None, no_config=None):\n",
    "        \"\"\"initialize the DashComponent\n",
    "\n",
    "        Args:\n",
    "            title (str, optional): Title of component. Defaults to \"Dash\".\n",
    "            name (str, optional): unique name to add to Component elements. \n",
    "                        If None then random uuid is generated to make sure \n",
    "                        it's unique. Defaults to None.\n",
    "        \"\"\"\n",
    "        super().__init__(no_store, no_attr, no_config)\n",
    "        self._convert_ff_config_params()\n",
    "        \n",
    "        self.title = title\n",
    "        if not hasattr(self, \"name\"):\n",
    "            self.name = name\n",
    "        if self.name is None:\n",
    "            self._generate_uuid_name()\n",
    "        self._stored_params[\"name\"] = self.name\n",
    "        \n",
    "        self._components = []\n",
    "        self.compute_querystring_params(whole_tree=False)\n",
    "        \n",
    "    \n",
    "    \n",
    "    def _generate_uuid_name(self):\n",
    "        self.name = str(shortuuid.ShortUUID().random(length=10))\n",
    "\n",
    "        \n",
    "    def _convert_ff_config_params(self):\n",
    "        \"\"\"convert any DashFigureFactory in the ._stored_params dict to its config\"\"\"\n",
    "        for k, v in self._stored_params.items():\n",
    "            if isinstance(v, DashFigureFactory):\n",
    "                self._stored_params[k] = self._stored_params[k].to_config()\n",
    "                \n",
    "    @staticmethod\n",
    "    def make_hideable(element, hide=False):\n",
    "        \"\"\"helper function to optionally not display an element in a layout.        \n",
    "\n",
    "        Example:\n",
    "            make_hideable(dbc.Col([cutoff.layout()]), hide=hide_cutoff)\n",
    "\n",
    "        Args:\n",
    "            hide(bool): wrap the element inside a hidden html.div. If the element \n",
    "                        is a dbc.Col or a dbc.FormGroup, wrap element.children in\n",
    "                        a hidden html.Div instead. Defaults to False.\n",
    "        \"\"\" \n",
    "        if hide:\n",
    "            if isinstance(element, dbc.Col) or isinstance(element, dbc.Row):\n",
    "                return html.Div(element.children, style=dict(display=\"none\"))\n",
    "            else:\n",
    "                return html.Div(element, style=dict(display=\"none\"))\n",
    "        else:\n",
    "            return element\n",
    "        \n",
    "    def querystring(self, params, *attrs):\n",
    "        \"\"\"\n",
    "        wrapper function that applies params loaded from querystrings\n",
    "        to the underlying dash layout function's attributes attrs. By \n",
    "        default it only applies to the \"value\" attribute.\n",
    "          \n",
    "        Use:\n",
    "            To only track the value attribute:\n",
    "                self.querystring(params)(dcc.Input)(id=\"input-\"+self.name, value=1)\n",
    "            \n",
    "            To track specific attribute(s):\n",
    "            \n",
    "                self.querystring(params, \"value\", \"min\", \"max\")(dcc.Slider)(id=\"input-\"+self.name)\n",
    "            \n",
    "        if params=='_store_querystring_params':\n",
    "            stores a list of tuple(id, attribute) to be tracked in the querystring\n",
    "            to self._querystring_params. All (nested) querystring parameters can \n",
    "            be accessed with .get_querystring_params()\n",
    "        \n",
    "        \"\"\"\n",
    "        def move_value_to_front(attrs):\n",
    "            \"\"\"the value attribute gets encoded with a single querystring, e.g. '?param=1' \n",
    "                    gets parsed as param.value=1.\n",
    "                All other attributes get encoded with two querystrings,  e.g. \n",
    "                    '?param=max&param=10' gets parsed as param.max=10.\n",
    "                Therefore an uneven number of attributes implies that the value attribute\n",
    "                has been encoded. By always putting value first, we can simply take the\n",
    "                first querystring param as value, and then parse the rest.\"\"\"\n",
    "            if not attrs:\n",
    "                # if not attributes passed: encode value attribute\n",
    "                return tuple(['value'])\n",
    "            if not 'value' in attrs:\n",
    "                # if 'value' not in attributes then can keep the order as passed\n",
    "                return attrs\n",
    "            else:\n",
    "                # if 'value' in attributes, then make sure it's first in the list:\n",
    "                attrs_list = list(attrs)\n",
    "                attrs_list.insert(0, attrs_list.pop(attrs_list.index('value')))\n",
    "                return tuple(attrs_list)\n",
    "        \n",
    "        if params==\"_store_querystring_params\":\n",
    "            attrs = move_value_to_front(attrs)\n",
    "            def wrapper(func):\n",
    "                def apply_value(*args, **kwargs):\n",
    "                    for attr in attrs:\n",
    "                        self._querystring_params.append(tuple([kwargs['id'], attr]))\n",
    "                    return func(*args, **kwargs)\n",
    "                return apply_value\n",
    "            return wrapper\n",
    "        if params is None:\n",
    "            def wrapper(func):\n",
    "                def apply_value(*args, **kwargs):\n",
    "                    return func(*args, **kwargs)\n",
    "                return apply_value\n",
    "            return wrapper\n",
    "        else:\n",
    "            def wrapper(func):\n",
    "                def apply_value(*args, **kwargs):\n",
    "                    if 'id' in kwargs and kwargs['id'] in params:\n",
    "                        param_values = params[kwargs['id']]\n",
    "                        for pv in param_values:\n",
    "                            kwargs[pv[0]] = pv[1]\n",
    "                    return func(*args, **kwargs)\n",
    "                return apply_value\n",
    "            return wrapper\n",
    "        \n",
    "    def get_querystring_params(self):\n",
    "        \"\"\"\n",
    "        Returns a list of tuple(id, attribute) of all element attributes\n",
    "        in all (sub-)components that have been wrapped by self.querystring() \n",
    "        and should be tracked in the url querystring.\"\"\"\n",
    "        \n",
    "        _params = []\n",
    "        _params.extend(self._querystring_params)\n",
    "        \n",
    "        self.register_components()\n",
    "        for comp in self._components:\n",
    "            _params.extend(comp.get_querystring_params())\n",
    "        return _params\n",
    "    \n",
    "    def _clear_querystring_params(self, whole_tree=True):\n",
    "        \"\"\"clears the querystring params. \n",
    "        \n",
    "        Args:\n",
    "            whole_tree (bool): if True, clear all _querystring_prams\\\n",
    "                in all subcomponents.\"\"\"\n",
    "        self._querystring_params = []\n",
    "        \n",
    "        if whole_tree:\n",
    "            self.register_components()\n",
    "            for comp in self._components:\n",
    "                comp._clear_querystring_params(whole_tree)\n",
    "    \n",
    "    def compute_querystring_params(self, whole_tree=True):\n",
    "        \"\"\"compute ._querystring_params. \n",
    "        \n",
    "        Args:\n",
    "            whole_tree (bool): if True, compute all _querystring_prams\\\n",
    "                in all subcomponents.\"\"\"\n",
    "        self._querystring_params = []\n",
    "        \n",
    "        try:\n",
    "            self.layout(\"_store_querystring_params\")\n",
    "        except:\n",
    "            pass\n",
    "        \n",
    "        if whole_tree:\n",
    "            self.register_components()\n",
    "            for comp in self._components:\n",
    "                comp.compute_querystring_params(whole_tree)\n",
    "                \n",
    "    def get_unreachable_querystring_params(self):\n",
    "        \"\"\"returns all element (id, attr) querystring parameters \n",
    "        that have a self.querystring() wrapper but because params\n",
    "        has not been passed correctly down to subcomponents .layout()\n",
    "        function, will not actually get updated.\n",
    "        \"\"\"\n",
    "        try:\n",
    "            _ = self.layout(None)\n",
    "        except:\n",
    "            return self.get_querystring_params()\n",
    "    \n",
    "        self._clear_querystring_params(whole_tree=True)\n",
    "        _ = self.layout(\"_store_querystring_params\")\n",
    "        reachable_params = self.get_querystring_params()\n",
    "        \n",
    "        self.compute_querystring_params(whole_tree=True)\n",
    "        all_params = self.get_querystring_params()\n",
    "        \n",
    "        unreachable_params = [param for param in all_params if param not in reachable_params]\n",
    "        return unreachable_params\n",
    "    \n",
    "    def id(self, component_id):\n",
    "        if self.name is None:\n",
    "            self._generate_uuid_name()\n",
    "        return component_id + '-' + self.name\n",
    "        \n",
    "    def Input(self, component_id, component_property):\n",
    "        if self.name is None:\n",
    "            self._generate_uuid_name()\n",
    "        return Input(component_id + '-' + self.name, component_property)\n",
    "    \n",
    "    def Output(self, component_id, component_property):\n",
    "        if self.name is None:\n",
    "            self._generate_uuid_name()\n",
    "        return Output(component_id + '-' + self.name, component_property)\n",
    "    \n",
    "    def State(self, component_id, component_property):\n",
    "        if self.name is None:\n",
    "            self._generate_uuid_name()\n",
    "        return State(component_id + '-' + self.name, component_property)\n",
    "        \n",
    "    def register_components(self): \n",
    "        \"\"\"register subcomponents so that their callbacks will be registered\n",
    "        \n",
    "        Searches self.__dict__, finds all DashComponents and adds them to self._components\n",
    "        \"\"\"\n",
    "        if not hasattr(self, '_components'):\n",
    "            self._components = []\n",
    "        for k, v in self.__dict__.items():\n",
    "            if k != '_components' and isinstance(v, DashComponent) and v not in self._components:\n",
    "                self._components.append(v)\n",
    "                \n",
    "    def tabs(self, params, id, tabs):\n",
    "        return dcc.Tabs(id=id, value=id+\"-\"+tabs[0].name, \n",
    "                     children=[\n",
    "                         dcc.Tab(id=id+\"-\"+tab.name, \n",
    "                                 value=id+\"-\"+tab.name, \n",
    "                                 label=tab.title, \n",
    "                                 children=tab.layout(params)) for tab in tabs])\n",
    "    \n",
    "    def layout(self, params=None):\n",
    "        \"\"\"layout to be defined by the particular ExplainerComponent instance.\n",
    "        All element id's should append +self.name to make sure they are unique.\"\"\"\n",
    "        return None\n",
    "    \n",
    "    def component_callbacks(self, app):\n",
    "        \"\"\"register callbacks specific to this ExplainerComponent.\"\"\"\n",
    "        if hasattr(self, \"_register_callbacks\"):\n",
    "            print(\"Warning: the use of _register_callbacks() will be deprecated!\"\n",
    "                  \" Use component_callbacks() from now on.\")\n",
    "            self._register_callbacks(app)\n",
    "\n",
    "    def register_callbacks(self, app):\n",
    "        \"\"\"First register callbacks of all subcomponents, then call\n",
    "        _register_callbacks(app)\n",
    "        \"\"\"\n",
    "        self.register_components()\n",
    "        for comp in self._components:\n",
    "            comp.register_callbacks(app)\n",
    "        self.component_callbacks(app)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h2 id=\"DashComponent\" class=\"doc_header\"><code>class</code> <code>DashComponent</code><a href=\"\" class=\"source_link\" style=\"float:right\">[source]</a></h2>\n",
       "\n",
       "> <code>DashComponent</code>(**`title`**=*`'Dash'`*, **`name`**=*`None`*, **`no_store`**=*`None`*, **`no_attr`**=*`None`*, **`no_config`**=*`None`*) :: [`DashComponentBase`](/dash_oop_components/core.html#DashComponentBase)\n",
       "\n",
       "DashComponent is a bundle of a dash layout and callbacks that\n",
       "can make use of DashFigureFactory objects. \n",
       "\n",
       "A DashComponent can have DashComponent subcomponents, that\n",
       "you register with register_components(). \n",
       "\n",
       "DashComponents allow you to:\n",
       "\n",
       "1. Write clean, re-usable, composable code for your dashboard\n",
       "2. Store your dashboard to config files\n",
       "3. Load your dashboard from config files\n",
       "\n",
       "Each DashComponent should have a unique .name so that dash id's don't clash.\n",
       "If no name is given, DashComponent generates a unique uuid name. This allows\n",
       "for multiple instance of the same component type in a single layout. \n",
       "But remember to add `+self.name` to all id's.\n",
       "\n",
       "Important:\n",
       "    define your callbacks in `_register_callbacks()` (note underscore!) and\n",
       "    DashComponent will register callbacks of subcomponents in addition\n",
       "    to _register_callbacks() when calling register_callbacks()"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.make_hideable\" class=\"doc_header\"><code>DashComponent.make_hideable</code><a href=\"__main__.py#L61\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.make_hideable</code>(**`element`**, **`hide`**=*`False`*)\n",
       "\n",
       "helper function to optionally not display an element in a layout.        \n",
       "\n",
       "Example:\n",
       "    make_hideable(dbc.Col([cutoff.layout()]), hide=hide_cutoff)\n",
       "\n",
       "Args:\n",
       "    hide(bool): wrap the element inside a hidden html.div. If the element \n",
       "                is a dbc.Col or a dbc.FormGroup, wrap element.children in\n",
       "                a hidden html.Div instead. Defaults to False."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.querystring\" class=\"doc_header\"><code>DashComponent.querystring</code><a href=\"__main__.py#L81\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.querystring</code>(**`params`**, **\\*`attrs`**)\n",
       "\n",
       "wrapper function that applies params loaded from querystrings\n",
       "to the underlying dash layout function's attributes attrs. By \n",
       "default it only applies to the \"value\" attribute.\n",
       "  \n",
       "Use:\n",
       "    To only track the value attribute:\n",
       "        self.querystring(params)(dcc.Input)(id=\"input-\"+self.name, value=1)\n",
       "    \n",
       "    To track specific attribute(s):\n",
       "    \n",
       "        self.querystring(params, \"value\", \"min\", \"max\")(dcc.Slider)(id=\"input-\"+self.name)\n",
       "    \n",
       "if params=='_store_querystring_params':\n",
       "    stores a list of tuple(id, attribute) to be tracked in the querystring\n",
       "    to self._querystring_params. All (nested) querystring parameters can \n",
       "    be accessed with .get_querystring_params()"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.get_querystring_params\" class=\"doc_header\"><code>DashComponent.get_querystring_params</code><a href=\"__main__.py#L147\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.get_querystring_params</code>()\n",
       "\n",
       "Returns a list of tuple(id, attribute) of all element attributes\n",
       "in all (sub-)components that have been wrapped by self.querystring() \n",
       "and should be tracked in the url querystring."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.get_unreachable_querystring_params\" class=\"doc_header\"><code>DashComponent.get_unreachable_querystring_params</code><a href=\"__main__.py#L192\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.get_unreachable_querystring_params</code>()\n",
       "\n",
       "returns all element (id, attr) querystring parameters \n",
       "that have a self.querystring() wrapper but because params\n",
       "has not been passed correctly down to subcomponents .layout()\n",
       "function, will not actually get updated."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.layout\" class=\"doc_header\"><code>DashComponent.layout</code><a href=\"__main__.py#L252\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.layout</code>(**`params`**=*`None`*)\n",
       "\n",
       "layout to be defined by the particular ExplainerComponent instance.\n",
       "All element id's should append +self.name to make sure they are unique."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.component_callbacks\" class=\"doc_header\"><code>DashComponent.component_callbacks</code><a href=\"__main__.py#L257\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.component_callbacks</code>(**`app`**)\n",
       "\n",
       "register callbacks specific to this ExplainerComponent."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashComponent.register_callbacks\" class=\"doc_header\"><code>DashComponent.register_callbacks</code><a href=\"__main__.py#L264\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashComponent.register_callbacks</code>(**`app`**)\n",
       "\n",
       "First register callbacks of all subcomponents, then call\n",
       "_register_callbacks(app)"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(DashComponent)\n",
    "show_doc(DashComponent.make_hideable)\n",
    "show_doc(DashComponent.querystring)\n",
    "show_doc(DashComponent.get_querystring_params)\n",
    "show_doc(DashComponent.get_unreachable_querystring_params)\n",
    "show_doc(DashComponent.layout)\n",
    "show_doc(DashComponent.component_callbacks)\n",
    "show_doc(DashComponent.register_callbacks)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `DashComponentTabs`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tracking every single parameter in a big multi tab dashboard can result in extremely long querystring urls. \n",
    "However often you would only want to share the analysis on a single tab anyway, so we can shorten the url by only keeping track of the parameters of the tab that you are on at the moment. To make this possible we define a drop-in replacement for `dcc.Tabs` called `DashComponentTabs`.\n",
    "\n",
    "When you pass an `id` and a list of `DashComponents`, this generates automatically\n",
    "a\n",
    "```\n",
    "dcc.Tabs(id=id, children = [dcc.Tab(tab.layout(), label=tab.title) for tab in tabs])\n",
    "```\n",
    "\n",
    "When you pass a `component` parameter and do not set `single_tab_querystrings=False`, then `DashComponentTabs` stores the querystring parameter for each tab in `component._tab_params`. This will get used by `DashApp` to exclude all parameters that are not on the current tab from being stored in the querystring url.\n",
    "\n",
    "Example usage:\n",
    "\n",
    "```python\n",
    "    self.querystring(params)(DashComponentTabs)(\n",
    "                component=self, id=\"tabs\", tabs=[self.list1, self.list2], params=params)\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 106,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "class DashComponentTabs(dcc.Tabs):\n",
    "    \n",
    "    def __init__(self, id=None, tabs=None, params=None, value=None, \n",
    "                 component=None, single_tab_querystrings=True, **kwargs):\n",
    "        assert id is not None, \"Need to pass an id! id cannot be None!\"\n",
    "        assert tabs is not None, \"Need to pass a list of tabs!\"\n",
    "        assert all([isinstance(tab, DashComponent) for tab in tabs]), \\\n",
    "            \"all items in tabs should be a DashComponent!\"\n",
    "        assert len(set([tab.name for tab in tabs]))==len(tabs), \\\n",
    "            \"all tabs should have a unique .name property!\"\n",
    "        \n",
    "        children = [dcc.Tab(id=id+\"-\"+tab.name, \n",
    "                         value=tab.name, \n",
    "                         label=tab.title, \n",
    "                         children=tab.layout(params)) for tab in tabs]\n",
    "        if value is None:\n",
    "            value = tabs[0].name # default to first tab\n",
    "        if \"value\" in kwargs:\n",
    "            del kwargs[\"value\"]\n",
    "        if component is not None and single_tab_querystrings:\n",
    "            if not hasattr(component, \"_tab_params\"):\n",
    "                component._tab_params = {}\n",
    "            \n",
    "            component._tab_params[id] = {\n",
    "                tab.name: tab.get_querystring_params() for tab in tabs}\n",
    "            \n",
    "        super().__init__(id=id, children=children, value=str(value), **kwargs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `DashConnector`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "class DashConnector(DashComponent):\n",
    "        \n",
    "    def register_components(self): \n",
    "        \"\"\"register subcomponents so that their callbacks will be registered.\n",
    "        \n",
    "        In the case of a DashConnector this is a dummy, as no subcomponents need to\n",
    "        be registered.\n",
    "        \"\"\"\n",
    "        if not hasattr(self, '_components'):\n",
    "            self._components = []  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example use of `DashComponent`:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [],
   "source": [
    "import dash_html_components as html\n",
    "import dash_core_components as dcc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Single DashComponent"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- You can pass a `name` to a `DashComponent` to be used as a unique suffix for all the layout id's.\n",
    "    If you don't pass a name, a random uuid identifier `self.name` gets generated instead. However if \n",
    "    you are going to track querystrings, it's best to pass a specific, short and readable name.\n",
    "- You can store the state of your dashboard to the url querystring by wrapping the\n",
    "    elements that you would like to track in a `self.querystrings(params)(...)` wrapper. \n",
    "    - The state of the querystring will be passed down to the layout function as `params`.\n",
    "    - You pass these params to `self.querystring`, and indicate which elements of the layour function\n",
    "        you would like to track and reload from state.\n",
    "    - If no attributes are listed, by default \"value\" gets tracked\n",
    "- callbacks should be defined in `_register_callbacks(app)` (**note the underscore!**)\n",
    "    - the `register_callbacks(app)` will then first register all callbacks \n",
    "        of subcomponents and then call this `_register_callbacks(app)` method.\n",
    " "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [],
   "source": [
    "class T(DashComponent):\n",
    "    def __init__(self, name=None):\n",
    "        super().__init__()\n",
    "    \n",
    "    def layout(self, params=None):\n",
    "        return html.Div([\n",
    "            self.querystring(params)(dcc.Input)(id=self.id(\"input1\")),\n",
    "            self.querystring(params, \"min\", \"max\")(dcc.Input)(id=self.id(\"input2\")),\n",
    "            self.querystring(params, \"min\", \"max\", \"value\")(dcc.Input)(id=self.id(\"input3\"))\n",
    "        ])\n",
    "            "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 110,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('input1-0', 'value'),\n",
       " ('input2-0', 'min'),\n",
       " ('input2-0', 'max'),\n",
       " ('input3-0', 'value'),\n",
       " ('input3-0', 'min'),\n",
       " ('input3-0', 'max')]"
      ]
     },
     "execution_count": 110,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "t= T(name=\"0\")\n",
    "t.get_querystring_params()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "metadata": {},
   "outputs": [],
   "source": [
    "t= T(name=\"0\")\n",
    "t.get_querystring_params()\n",
    "input1_attributes = [qs[1] for qs in t.get_querystring_params() if qs[0]==\"input1-0\"]\n",
    "input2_attributes = [qs[1] for qs in t.get_querystring_params() if qs[0]==\"input2-0\"]\n",
    "input3_attributes = [qs[1] for qs in t.get_querystring_params() if qs[0]==\"input3-0\"]\n",
    "\n",
    "assert input1_attributes == ['value'], \"if no attributes explicitly listen, default to track 'value'\"\n",
    "assert not 'value' in input2_attributes, \"value should not be in attributes if other attributes are explicitly listed\"\n",
    "assert input3_attributes[0] == 'value', \"value should always be the first attributes in the list!\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `DashComponent` example: `ListComponent`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 112,
   "metadata": {},
   "outputs": [],
   "source": [
    "class ListComponent(DashComponent):\n",
    "    def __init__(self, list_factory, first_n=2, name=None):\n",
    "        super().__init__()\n",
    "        \n",
    "    def layout(self, params=None):\n",
    "        return html.Div([\n",
    "            self.querystring(params)(dcc.Input)(\n",
    "                id=self.id(\"input-first-n\"), \n",
    "                type=\"number\", \n",
    "                value=self.first_n,\n",
    "                min=0,\n",
    "                max=self.list_factory.list_length()),\n",
    "            html.Div(id=self.id(\"output-div\"), \n",
    "                     children=\" \".join(self.list_factory.return_list(self.first_n))),\n",
    "        ])\n",
    "    \n",
    "    def component_callbacks(self, app):\n",
    "        @app.callback(\n",
    "            self.Output(\"output-div\", \"children\"),\n",
    "            self.Input(\"input-first-n\", \"value\")\n",
    "        )\n",
    "        def update_div(first_n):\n",
    "            if first_n is not None:\n",
    "                return \" \".join(self.list_factory.return_list(first_n))\n",
    "            raise PreventUpdate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 113,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_component = ListComponent(list_factory, name=\"1\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 114,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('input-first-n-1', 'value')]"
      ]
     },
     "execution_count": 114,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list_component.get_querystring_params()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 115,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert list_component.list_factory.return_list() == ['this', 'is', 'a', 'dumb', 'example']\n",
    "assert isinstance(list_component.layout(), html.Div)\n",
    "assert list_component.get_querystring_params()[0][1] == 'value'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: ListComponent\n",
      "  module: __main__\n",
      "  params:\n",
      "    list_factory:\n",
      "      dash_figure_factory:\n",
      "        class_name: ListFactory\n",
      "        module: __main__\n",
      "        params:\n",
      "          list_input:\n",
      "          - this\n",
      "          - is\n",
      "          - a\n",
      "          - dumb\n",
      "          - example\n",
      "          filepath: list_factory.pkl\n",
      "    first_n: 2\n",
      "    name: '1'\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(list_component.to_yaml())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Store and reload the component (with the figure factory automatically getting reloaded as well!):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 117,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_component.to_yaml(\"list_component.yaml\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 118,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_component2 = ListComponent.from_yaml(\"list_component.yaml\")\n",
    "assert isinstance(list_component2, ListComponent)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 119,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_component.dump()\n",
    "list_component2 = ListComponent.from_yaml(\"list_component.yaml\", try_pickles=True)\n",
    "assert isinstance(list_component2, ListComponent)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 120,
   "metadata": {},
   "outputs": [],
   "source": [
    "assert list_component2.list_factory.return_list() == list_component.list_factory.return_list()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 121,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'list_factory.pkl'"
      ]
     },
     "execution_count": 121,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list_factory.to_config()['dash_figure_factory']['params']['filepath']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See that `force_pickle=True` fails when the `DashFigureFactory`'s filepath is non-existent, but\n",
    "that `try_pickles=True` simply reload the `DashFigureFactory` from config:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 122,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_factory._stored_params['filepath'] = \"non_existing_file.pkl\"\n",
    "list_component = ListComponent(list_factory)\n",
    "list_component.to_yaml(\"list_component.yaml\")\n",
    "try:\n",
    "    list_component.from_yaml(\"list_component.yaml\", force_pickles=True)\n",
    "except Exception as e:\n",
    "    assert isinstance(e, FileNotFoundError)\n",
    "list_factory._stored_params['filepath'] = \"file_factory.pkl\"\n",
    "list_component.to_yaml(\"list_component.yaml\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Composite `DashComponent` Example: `ListComposite`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `ListComposite` if a combination of two `ListComponents`, both with different initial settings for `first_n`.\n",
    "\n",
    "- the subcomponents get defined in the init with `self.list1 = ...` and `self.list2 = ...`\n",
    "- the subcomponents get included in the layout by including `self.list1.layout()` and `self.list2.layout()`\n",
    "- callbacks can be written that include elements from the ListComposite and the subcomponents\n",
    "    - you need to add the `.name` from the subcomponents to properly identify the element id's\n",
    "    - in this case the reset button resets the two inputs of the subcomponents:\n",
    "        ```python\n",
    "        @app.callback(\n",
    "            Output(\"input-first-n-\"+self.list1.name, \"value\"),\n",
    "            Output(\"input-first-n-\"+self.list2.name, \"value\"),\n",
    "            Input(\"reset-button-\"+self.name, \"n_clicks\")\n",
    "        )\n",
    "        ```\n",
    "- additional callbacks should be defined under `_register_callbacks(self, app)`! (**note the underscore!**)\n",
    "- callbacks of the subcomponents also get automatically registered, and included when `DashApp` calls\n",
    "    `register_components(app)` (**note the lack of underscore here!**)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 123,
   "metadata": {},
   "outputs": [],
   "source": [
    "class ListComposite(DashComponent):\n",
    "    def __init__(self, list_factory, first_n1=2, first_n2=3, name=None):\n",
    "        super().__init__()\n",
    "        self.list1 = ListComponent(list_factory, first_n=first_n1, name=\"1\")\n",
    "        self.list2 = ListComponent(list_factory, first_n=first_n2, name=\"2\")\n",
    "        \n",
    "    def layout(self, params=None):\n",
    "        return html.Div([\n",
    "            html.Button(\"Reset\", id=self.id(\"reset-button\")),\n",
    "            self.querystring(params)(DashComponentTabs)(\n",
    "                component=self, id=\"tabs\", tabs=[self.list1, self.list2], params=params)\n",
    "        ])\n",
    "    \n",
    "    def component_callbacks(self, app):\n",
    "        @app.callback(\n",
    "            self.list1.Output(\"input-first-n\", \"value\"),\n",
    "            self.list2.Output(\"input-first-n\", \"value\"),\n",
    "            self.Input(\"reset-button\", \"n_clicks\")\n",
    "        )\n",
    "        def reset_inpus(n_clicks):\n",
    "            if n_clicks:\n",
    "                return self.first_n1, self.first_n2\n",
    "            raise PreventUpdate"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 124,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_composite = ListComposite(list_factory, name=\"main\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 125,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('input-first-n-1', 'value'), ('input-first-n-2', 'value')]"
      ]
     },
     "execution_count": 125,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list_composite.get_querystring_params()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 126,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Div([Button(children='Reset', id='reset-button-main'), Tabs(children=[Tab(children=Div([Input(value=2, type='number', min=0, max=5, id='input-first-n-1'), Div(children='this is', id='output-div-1')]), id='tabs-1', label='Dash', value='1'), Tab(children=Div([Input(value=3, type='number', min=0, max=5, id='input-first-n-2'), Div(children='this is a', id='output-div-2')]), id='tabs-2', label='Dash', value='2')], id='tabs', value='1')])"
      ]
     },
     "execution_count": 126,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list_composite.layout()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 127,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'tabs': {'1': [('input-first-n-1', 'value')],\n",
       "  '2': [('input-first-n-2', 'value')]}}"
      ]
     },
     "execution_count": 127,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list_composite._tab_params"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[]\n",
      "[('input-first-n-1', 'value')]\n",
      "[('input-first-n-2', 'value')]\n"
     ]
    }
   ],
   "source": [
    "print(list_composite._querystring_params)\n",
    "print(list_composite.list1._querystring_params)\n",
    "print(list_composite.list2._querystring_params)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 129,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('tabs', 'value'), ('input-first-n-1', 'value'), ('input-first-n-2', 'value')]"
      ]
     },
     "execution_count": 129,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "list_composite.compute_querystring_params()\n",
    "querystring_params = list_composite.get_querystring_params()\n",
    "assert len(querystring_params) == 3, \\\n",
    " \"should be three querystring params, one from each subcomponent plus 'tabs'!\"\n",
    "querystring_params"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 130,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 130,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "unreachable_querystring_params = list_composite.get_unreachable_querystring_params()\n",
    "assert len(unreachable_querystring_params) == 0, \\\n",
    "    \"should be no unreachable params in this component!\"\n",
    "unreachable_querystring_params"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: ListComposite\n",
      "  module: __main__\n",
      "  params:\n",
      "    list_factory:\n",
      "      dash_figure_factory:\n",
      "        class_name: ListFactory\n",
      "        module: __main__\n",
      "        params:\n",
      "          list_input:\n",
      "          - this\n",
      "          - is\n",
      "          - a\n",
      "          - dumb\n",
      "          - example\n",
      "          filepath: file_factory.pkl\n",
      "    first_n1: 2\n",
      "    first_n2: 3\n",
      "    name: main\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(list_composite.to_yaml())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "subcomponents are automatically registerd to a `_components` list when calling `register_components()`.\n",
    "\n",
    "(this gets called initially in `register_callbacks()`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 132,
   "metadata": {},
   "outputs": [],
   "source": [
    "list_composite.register_components()\n",
    "list_composite._components\n",
    "assert len(list_composite._components) == 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we build a dash app from this list_composite, we can check that all three callbacks (one for the composite, and one each for each subcomponent) have indeed been registered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 133,
   "metadata": {},
   "outputs": [],
   "source": [
    "app = dash.Dash()\n",
    "app.layout = list_composite.layout()\n",
    "list_composite.register_callbacks(app)\n",
    "assert len(app.callback_map) == 3, \\\n",
    "    (\"Should be three callbacks (one for the composite, and one each for each \"\n",
    "     \"subcomponent) have indeed been registered)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using `DashConnectors` between `DashComponents`:\n",
    "\n",
    "You can define `DashConnectors` that connect the inputs and outputs of multiple `DashComponents`. \n",
    "You can do this because you have access to the `.name` property of each subcomponent.\n",
    "\n",
    "`DashConnectors` never register callbacks from any of its subcomponents.\n",
    "\n",
    "Using DashConnectors can help clean up your code, especially if you can re-use them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 134,
   "metadata": {},
   "outputs": [],
   "source": [
    "class ResetConnector(DashConnector):\n",
    "    def __init__(self, list_composite, list_component1, list_component2):\n",
    "        super().__init__()\n",
    "        \n",
    "    def component_callbacks(self, app):\n",
    "        @app.callback(\n",
    "            [self.list_component1.Output(\"input-first-n\", \"value\"),\n",
    "             self.list_component2.Output(\"input-first-n\", \"value\")],\n",
    "             self.list_composite.Input(\"reset-button\", \"n_clicks\")\n",
    "        )\n",
    "        def reset_inpus(n_clicks):\n",
    "            if n_clicks:\n",
    "                return self.list_composite.first_n1, self.list_composite.first_n2\n",
    "            raise PreventUpdate\n",
    "            \n",
    "class ListComposite(DashComponent):\n",
    "    def __init__(self, list_factory, first_n1=2, first_n2=3, name=None):\n",
    "        super().__init__()\n",
    "        self.list1 = ListComponent(self.list_factory, first_n=first_n1, name=\"1\")\n",
    "        self.list2 = ListComponent(self.list_factory, first_n=first_n2, name=\"2\")\n",
    "        self.connector = ResetConnector(self, self.list1, self.list2)\n",
    "        \n",
    "    def layout(self, params=None):\n",
    "        return html.Div([\n",
    "            html.Button(\"Reset\", id=\"reset-button-\"+self.name),\n",
    "            self.querystring(params)(DashComponentTabs)(\n",
    "                component=self, id=\"tabs\", tabs=[self.list1, self.list2], params=params)\n",
    "        ])\n",
    "        "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 135,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_component:\n",
      "  class_name: ListComposite\n",
      "  module: __main__\n",
      "  params:\n",
      "    list_factory:\n",
      "      dash_figure_factory:\n",
      "        class_name: ListFactory\n",
      "        module: __main__\n",
      "        params:\n",
      "          list_input:\n",
      "          - this\n",
      "          - is\n",
      "          - a\n",
      "          - dumb\n",
      "          - example\n",
      "          filepath: file_factory.pkl\n",
      "    first_n1: 2\n",
      "    first_n2: 3\n",
      "    name: 7wFsEqmpVq\n",
      "\n"
     ]
    }
   ],
   "source": [
    "list_composite = ListComposite(list_factory)\n",
    "print(list_composite.to_yaml())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 136,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "def concat_docstring(source=None):\n",
    "    \"Decorator: `__doc__` from `source` to __doc__\"\n",
    "    def _f(f):\n",
    "        if isinstance(f, types.FunctionType):\n",
    "            from_f = f\n",
    "        else:\n",
    "            from_f = f.__init__\n",
    "            \n",
    "        if isinstance(source, types.FunctionType):\n",
    "            source_f = source\n",
    "        elif source.__init__.__doc__ is not None:\n",
    "            source_f = source.__init__\n",
    "        else:\n",
    "            source_f = source\n",
    "        from_f.__doc__ = (\n",
    "            str(from_f.__doc__) + \"\\n\\n\\\"\" + \n",
    "            f\"Docstring from {source.__name__}\" +\n",
    "            \"\\n\\n\" +\n",
    "            str(source_f.__doc__))\n",
    "        return f\n",
    "    return _f"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 137,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "def parse_url_to_params(url):\n",
    "    \"\"\"\n",
    "    Returns a dict that summarizes the state of the app at the time that the\n",
    "    querystring url was generated. Lists are (somewhat hackily) detected \n",
    "    by the first char=='['), get evaluated using ast. Numbers are \n",
    "    appropriately cast as either int or float.\n",
    "    \n",
    "    Params:\n",
    "        url (str): url to be parsed. The querystring parameters should\n",
    "            come in pairs e.g.:?input-id=value&binput-id=1\n",
    "    \n",
    "    Returns:\n",
    "        dict: dictionary with the component_id as key and a list \n",
    "            of (param, value) pairs (e.g. {'input-id': [('value', 1)]}\n",
    "    \"\"\"\n",
    "\n",
    "    parse_result = urlparse(url)\n",
    "\n",
    "    statedict = parse_qs(parse_result.query)\n",
    "    if statedict:\n",
    "        for key, values in statedict.items():\n",
    "            if len(values) % 2 == 0: # even length means no value attr\n",
    "                new_value = list(map(list, zip(values[0::2], values[1::2])))\n",
    "                statedict[key] = new_value\n",
    "            else: # uneven length means value attr is the first element\n",
    "                new_value = list([['value', values[0]]])\n",
    "                new_value.extend(list(map(list, zip(values[1::2], values[2::2]))))\n",
    "                statedict[key] = new_value\n",
    "                \n",
    "            # go through every parsed value pv and check whether it is a list\n",
    "            # or a number and cast appropriately:\n",
    "            for pv in statedict[key]:\n",
    "                # if it's a list\n",
    "                if isinstance(pv[1], str) and pv[1][0]=='[':\n",
    "                    pv[1] = ast.literal_eval(pv[1])\n",
    "\n",
    "                #if it's a number\n",
    "                if (isinstance(pv[1], str) and\n",
    "                    pv[1].lstrip('-').replace('.','',1).isdigit()):\n",
    "\n",
    "                    if pv[1].isdigit():\n",
    "                        pv[1] = int(pv[1])\n",
    "                    else:\n",
    "                        pv[1] = float(pv[1])\n",
    "    else: #return empty dict\n",
    "        statedict = dict()\n",
    "    return statedict"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 138,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "def parse_url_to_qs_and_vals(url):\n",
    "    \"\"\"\n",
    "    Returns a dict that summarizes the state of the app at the time that the\n",
    "    querystring url was generated. Lists are (somewhat hackily) detected \n",
    "    by the first char=='['), get evaluated using ast. Numbers are \n",
    "    appropriately cast as either int or float.\n",
    "    \n",
    "    Params:\n",
    "        url (str): url to be parsed. The querystring parameters should\n",
    "            come in pairs e.g.:?input-id=value&binput-id=1\n",
    "    \n",
    "    Returns:\n",
    "        dict: dictionary with the component_id as key and a list \n",
    "            of (param, value) pairs (e.g. {'input-id': [('value', 1)]}\n",
    "    \"\"\"\n",
    "\n",
    "    parse_result = urlparse(url)\n",
    "\n",
    "    statedict = parse_qs(parse_result.query)\n",
    "    qs_params = []\n",
    "    values = []\n",
    "    \n",
    "    if statedict:\n",
    "        for key, vals in statedict.items():\n",
    "            if len(vals) % 2 == 0: # even length means no value attr\n",
    "                qs_params.extend(list(map(tuple, zip([key]*int(0.5*len(vals)), vals[0::2]))))\n",
    "                values.extend(vals[1::2])\n",
    "            else: # uneven length means value attr is the first element\n",
    "                qs_params.append(tuple([key, \"value\"]))\n",
    "                values.append(vals[0])\n",
    "                                 \n",
    "                qs_params.extend(list(map(tuple, zip([key]*int(0.5*(len(vals)-1)), vals[1::2]))))\n",
    "                values.extend(vals[2::2])\n",
    "\n",
    "    for i in range(len(values)):\n",
    "        if isinstance(values[i], str) and values[i][0]=='[':\n",
    "            values[i] = ast.literal_eval(values[i])\n",
    "\n",
    "        #if it's a number\n",
    "        if (isinstance(values[i], str) and\n",
    "            values[i].lstrip('-').replace('.','',1).isdigit()):\n",
    "\n",
    "            if values[i].isdigit():\n",
    "                values[i] = int(values[i])\n",
    "            else:\n",
    "                values[i] = float(values[i])\n",
    "\n",
    "    return qs_params, values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 139,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "def encode_querystring_params_to_url(querystring_params, values):\n",
    "    \"\"\"encodes a list of querystring_params and a list of values to \n",
    "    a url. \n",
    "    \n",
    "    Params:\n",
    "        querystring_params (list[tuples]): format e.g. \n",
    "            [('input-id', 'value'), ('input-id', 'type')]\n",
    "        values (list): list of values to be encoded, e.g.\n",
    "            [1, 'number']\n",
    "            \n",
    "    Returns:\n",
    "        str: url of format ?input-id=value&binput-id=1&input-id=type&binput-id='number'     \n",
    "    \"\"\"\n",
    "    statelist = [(id, tuple([val])) if attr==\"value\" else (id, (attr, val)) \n",
    "                     for (id, attr), val\n",
    "                         in zip(querystring_params, values) if val is not None]\n",
    "    params = urlencode(statelist,  doseq=True)\n",
    "    return f'?{params}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 140,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "def update_url_with_new_params(old_url, qs_params, vals):\n",
    "    old_qs_params, old_vals = parse_url_to_qs_and_vals(old_url)\n",
    "    for qs_param, val in zip(qs_params, vals):\n",
    "        if qs_param in old_qs_params:\n",
    "            old_vals[old_qs_params.index(qs_param)] = val\n",
    "        else:\n",
    "            old_qs_params.append(qs_param)\n",
    "            old_vals.append(val)\n",
    "    return encode_querystring_params_to_url(old_qs_params, old_vals)\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DashApp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In order to run your `DashboardComponent` dashboard you can pass it to a `DashApp` and run it:\n",
    "\n",
    "```python\n",
    "DashApp(dashboard_component).run()\n",
    "```\n",
    "\n",
    "Args:\n",
    "- `dashboard_component` (DashComponent): component to be run\n",
    "- `port` (int): port to run the server\n",
    "- `mode` ({'dash', 'external', 'inline', 'jupyterlab'}): type of dash server to start\n",
    "- `querystrings` (bool): save state to url querystring and load from querystring\n",
    "- `kwargs`: all kwargs will be passed down to dash.Dash. See below the docstring of dash.Dash\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 141,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "class DashApp(DashComponentBase):\n",
    "    \"\"\"Wrapper class for dash apps. Assigns layout and callbacks from \n",
    "    a DashComponent to a Dash app, and runs it.\n",
    "    \n",
    "    Can run both Dash and JupyterDash apps.\n",
    "    \n",
    "    \"\"\"\n",
    "    @concat_docstring(dash.Dash)\n",
    "    def __init__(self, dashboard_component,  \n",
    "                 port=8050, mode='dash', querystrings=False, bootstrap=False,\n",
    "                 **kwargs):\n",
    "        \"\"\"\n",
    "        \n",
    "        Args:\n",
    "            dashboard_component (DashComponent): component to be run\n",
    "            port (int): port to run the server\n",
    "            mode ({'dash', 'external', 'inline', 'jupyterlab'}): type of dash server to start\n",
    "            querystrings (bool): save state to querystring and load from querystring\n",
    "            bootstrap: include default bootstrap css\n",
    "            kwargs: all kwargs will be passed down to dash.Dash. See below the docstring of dash.Dash\n",
    "            \n",
    "        Returns:\n",
    "            DashApp: simply start .run() to start the dashboard\n",
    "        \"\"\"\n",
    "        super().__init__(child_depth=2)\n",
    "        self._stored_params['dashboard_component'] = dashboard_component.to_config()\n",
    "        self.app = self._get_dash_app()\n",
    "                \n",
    "    def _get_dash_app(self):\n",
    "        if self.bootstrap:\n",
    "            bootstrap_theme = self.bootstrap if isinstance(self.bootstrap, str) else dbc.themes.BOOTSTRAP\n",
    "            if 'external_stylesheets' not in self.kwargs:\n",
    "                self.kwargs['external_stylesheets'] = [bootstrap_theme]\n",
    "            else:\n",
    "                self.kwargs['external_stylesheets'].append(bootstrap_theme)\n",
    "                \n",
    "        if self.querystrings:\n",
    "            self.kwargs[\"suppress_callback_exceptions\"] = True\n",
    "        if self.mode == 'dash':\n",
    "            app = dash.Dash(**self.kwargs)\n",
    "        elif self.mode in {'inline', 'external', 'jupyterlab'}:\n",
    "            app = jupyter_dash.JupyterDash(**self.kwargs)\n",
    "            \n",
    "        if not self.querystrings:\n",
    "            app.layout = self.dashboard_component.layout()\n",
    "            \n",
    "        else:\n",
    "            \n",
    "            try:\n",
    "                self.dashboard_component.compute_querystring_params()\n",
    "                self.dashboard_component.layout(None)\n",
    "            except Exception as e:\n",
    "                print(e)\n",
    "                raise ValueError(\"The layout method method of dashboard_component does not take \"\n",
    "                                 \"a params parameter. Please rewrite as `def layout(self, params=None):` !\")\n",
    "            \n",
    "            unreachable_params = self.dashboard_component.get_unreachable_querystring_params()\n",
    "            if unreachable_params:\n",
    "                print(\"Warning: The following elements will be tracked in the querystring, \"\n",
    "                      \"but do not get passed as params to the (subcomponent) .layout(params) function, and so \"\n",
    "                      \"will not be rebuilt when reloading from the url querystring! Please \"\n",
    "                      \"make sure that you pass params down to the layout of all subcomponents! \"\n",
    "                      \"e.g. def layout(self, params=None): return html.Div([self.sub_component.layout(params)]) \\n\\n\",\n",
    "                      unreachable_params)\n",
    "            app.layout = html.Div([\n",
    "                        dcc.Location(id='url', refresh=False),\n",
    "                        html.Div(id='page-layout')\n",
    "                    ])\n",
    "\n",
    "            @app.callback(Output('page-layout', 'children'),\n",
    "                  [Input('url', 'href')])\n",
    "            def page_load(href):\n",
    "                if not href:\n",
    "                    return html.Div()\n",
    "                params = parse_url_to_params(href)\n",
    "                return self.dashboard_component.layout(params)\n",
    "            \n",
    "            @app.callback(Output('url', 'search'),\n",
    "                          [Input(id, param) for (id, param) \n",
    "                                  in self.dashboard_component.get_querystring_params()],\n",
    "                         [State('url', 'search')],\n",
    "                         prevent_initial_call=True\n",
    "                 )\n",
    "            def update_url_state(*values):\n",
    "                if hasattr(self.dashboard_component, \"_tab_params\"):\n",
    "                    tab_params = self.dashboard_component._tab_params\n",
    "                    qs_params = self.dashboard_component.get_querystring_params()\n",
    "                    qs_keys, qs_attrs = zip(*qs_params)\n",
    "                    \n",
    "                    excluded_params = []\n",
    "                    for tab in set(qs_keys) & set(tab_params.keys()):\n",
    "                        tab_value = values[qs_params.index(tuple([tab, \"value\"]))]\n",
    "                        for tab_name, tab_qs  in tab_params[tab].items():\n",
    "                            if tab_name != tab_value:\n",
    "                                excluded_params.extend(tab_qs)\n",
    "                                \n",
    "                    qs_vals = [(qs, v) for qs, v in zip(qs_params, values) if qs not in excluded_params]\n",
    "                    q, v = zip(*qs_vals)\n",
    "                    return encode_querystring_params_to_url(q, v)\n",
    "                    \n",
    "                old_url = values[-1]\n",
    "                ctx = dash.callback_context\n",
    "                params = [tuple(trigger['prop_id'].split('.')) for trigger in ctx.triggered]\n",
    "                idxs = [self.dashboard_component.get_querystring_params().index(param) \n",
    "                            for param in params]\n",
    "                vals = list(map(values.__getitem__, idxs))\n",
    "                return update_url_with_new_params(old_url, params, vals)\n",
    "                    \n",
    "            \n",
    "        self.dashboard_component.register_callbacks(app)\n",
    "\n",
    "        app.title = self.dashboard_component.title\n",
    "        return app\n",
    "    \n",
    "    def to_config(self):\n",
    "        return dict(dash_app=dict(\n",
    "            class_name=self.__class__.__name__, \n",
    "            module=self.__class__.__module__,\n",
    "            params=self._stored_params))\n",
    "    \n",
    "    def flask_server(self):\n",
    "        \"\"\"returns flask server inside self.app, for building wsgi apps\"\"\"\n",
    "        return self.app.server\n",
    "    \n",
    "    def run(self, port=None):\n",
    "        \"\"\"Run the dash app\"\"\"\n",
    "        self.app.run_server(port=port if port is not None else self.port)\n",
    "        "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 142,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "<h2 id=\"DashApp\" class=\"doc_header\"><code>class</code> <code>DashApp</code><a href=\"\" class=\"source_link\" style=\"float:right\">[source]</a></h2>\n",
       "\n",
       "> <code>DashApp</code>(**`dashboard_component`**, **`port`**=*`8050`*, **`mode`**=*`'dash'`*, **`querystrings`**=*`False`*, **`bootstrap`**=*`False`*, **\\*\\*`kwargs`**) :: [`DashComponentBase`](/dash_oop_components/core.html#DashComponentBase)\n",
       "\n",
       "Wrapper class for dash apps. Assigns layout and callbacks from \n",
       "a DashComponent to a Dash app, and runs it.\n",
       "\n",
       "Can run both Dash and JupyterDash apps."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashApp.__init__\" class=\"doc_header\"><code>DashApp.__init__</code><a href=\"__main__.py#L10\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashApp.__init__</code>(**`dashboard_component`**, **`port`**=*`8050`*, **`mode`**=*`'dash'`*, **`querystrings`**=*`False`*, **`bootstrap`**=*`False`*, **\\*\\*`kwargs`**)\n",
       "\n",
       "        \n",
       "        Args:\n",
       "            dashboard_component (DashComponent): component to be run\n",
       "            port (int): port to run the server\n",
       "            mode ({'dash', 'external', 'inline', 'jupyterlab'}): type of dash server to start\n",
       "            querystrings (bool): save state to querystring and load from querystring\n",
       "            bootstrap: include default bootstrap css\n",
       "            kwargs: all kwargs will be passed down to dash.Dash. See below the docstring of dash.Dash\n",
       "            \n",
       "        Returns:\n",
       "            DashApp: simply start .run() to start the dashboard\n",
       "        \n",
       "\n",
       "\"Docstring from Dash\n",
       "\n",
       "Dash is a framework for building analytical web applications.\n",
       "    No JavaScript required.\n",
       "\n",
       "    If a parameter can be set by an environment variable, that is listed as:\n",
       "        env: ``DASH_****``\n",
       "    Values provided here take precedence over environment variables.\n",
       "\n",
       "    :param name: The name Flask should use for your app. Even if you provide\n",
       "        your own ``server``, ``name`` will be used to help find assets.\n",
       "        Typically ``__name__`` (the magic global var, not a string) is the\n",
       "        best value to use. Default ``'__main__'``, env: ``DASH_APP_NAME``\n",
       "    :type name: string\n",
       "\n",
       "    :param server: Sets the Flask server for your app. There are three options:\n",
       "        ``True`` (default): Dash will create a new server\n",
       "        ``False``: The server will be added later via ``app.init_app(server)``\n",
       "            where ``server`` is a ``flask.Flask`` instance.\n",
       "        ``flask.Flask``: use this pre-existing Flask server.\n",
       "    :type server: boolean or flask.Flask\n",
       "\n",
       "    :param assets_folder: a path, relative to the current working directory,\n",
       "        for extra files to be used in the browser. Default ``'assets'``.\n",
       "        All .js and .css files will be loaded immediately unless excluded by\n",
       "        ``assets_ignore``, and other files such as images will be served if\n",
       "        requested.\n",
       "    :type assets_folder: string\n",
       "\n",
       "    :param assets_url_path: The local urls for assets will be:\n",
       "        ``requests_pathname_prefix + assets_url_path + '/' + asset_path``\n",
       "        where ``asset_path`` is the path to a file inside ``assets_folder``.\n",
       "        Default ``'assets'``.\n",
       "    :type asset_url_path: string\n",
       "\n",
       "    :param assets_ignore: A regex, as a string to pass to ``re.compile``, for\n",
       "        assets to omit from immediate loading. Ignored files will still be\n",
       "        served if specifically requested. You cannot use this to prevent access\n",
       "        to sensitive files.\n",
       "    :type assets_ignore: string\n",
       "\n",
       "    :param assets_external_path: an absolute URL from which to load assets.\n",
       "        Use with ``serve_locally=False``. assets_external_path is joined\n",
       "        with assets_url_path to determine the absolute url to the\n",
       "        asset folder. Dash can still find js and css to automatically load\n",
       "        if you also keep local copies in your assets folder that Dash can index,\n",
       "        but external serving can improve performance and reduce load on\n",
       "        the Dash server.\n",
       "        env: ``DASH_ASSETS_EXTERNAL_PATH``\n",
       "    :type assets_external_path: string\n",
       "\n",
       "    :param include_assets_files: Default ``True``, set to ``False`` to prevent\n",
       "        immediate loading of any assets. Assets will still be served if\n",
       "        specifically requested. You cannot use this to prevent access\n",
       "        to sensitive files. env: ``DASH_INCLUDE_ASSETS_FILES``\n",
       "    :type include_assets_files: boolean\n",
       "\n",
       "    :param url_base_pathname: A local URL prefix to use app-wide.\n",
       "        Default ``'/'``. Both `requests_pathname_prefix` and\n",
       "        `routes_pathname_prefix` default to `url_base_pathname`.\n",
       "        env: ``DASH_URL_BASE_PATHNAME``\n",
       "    :type url_base_pathname: string\n",
       "\n",
       "    :param requests_pathname_prefix: A local URL prefix for file requests.\n",
       "        Defaults to `url_base_pathname`, and must end with\n",
       "        `routes_pathname_prefix`. env: ``DASH_REQUESTS_PATHNAME_PREFIX``\n",
       "    :type requests_pathname_prefix: string\n",
       "\n",
       "    :param routes_pathname_prefix: A local URL prefix for JSON requests.\n",
       "        Defaults to ``url_base_pathname``, and must start and end\n",
       "        with ``'/'``. env: ``DASH_ROUTES_PATHNAME_PREFIX``\n",
       "    :type routes_pathname_prefix: string\n",
       "\n",
       "    :param serve_locally: If ``True`` (default), assets and dependencies\n",
       "        (Dash and Component js and css) will be served from local URLs.\n",
       "        If ``False`` we will use CDN links where available.\n",
       "    :type serve_locally: boolean\n",
       "\n",
       "    :param compress: Use gzip to compress files and data served by Flask.\n",
       "        Default ``False``\n",
       "    :type compress: boolean\n",
       "\n",
       "    :param meta_tags: html <meta> tags to be added to the index page.\n",
       "        Each dict should have the attributes and values for one tag, eg:\n",
       "        ``{'name': 'description', 'content': 'My App'}``\n",
       "    :type meta_tags: list of dicts\n",
       "\n",
       "    :param index_string: Override the standard Dash index page.\n",
       "        Must contain the correct insertion markers to interpolate various\n",
       "        content into it depending on the app config and components used.\n",
       "        See https://dash.plotly.com/external-resources for details.\n",
       "    :type index_string: string\n",
       "\n",
       "    :param external_scripts: Additional JS files to load with the page.\n",
       "        Each entry can be a string (the URL) or a dict with ``src`` (the URL)\n",
       "        and optionally other ``<script>`` tag attributes such as ``integrity``\n",
       "        and ``crossorigin``.\n",
       "    :type external_scripts: list of strings or dicts\n",
       "\n",
       "    :param external_stylesheets: Additional CSS files to load with the page.\n",
       "        Each entry can be a string (the URL) or a dict with ``href`` (the URL)\n",
       "        and optionally other ``<link>`` tag attributes such as ``rel``,\n",
       "        ``integrity`` and ``crossorigin``.\n",
       "    :type external_stylesheets: list of strings or dicts\n",
       "\n",
       "    :param suppress_callback_exceptions: Default ``False``: check callbacks to\n",
       "        ensure referenced IDs exist and props are valid. Set to ``True``\n",
       "        if your layout is dynamic, to bypass these checks.\n",
       "        env: ``DASH_SUPPRESS_CALLBACK_EXCEPTIONS``\n",
       "    :type suppress_callback_exceptions: boolean\n",
       "\n",
       "    :param prevent_initial_callbacks: Default ``False``: Sets the default value\n",
       "        of ``prevent_initial_call`` for all callbacks added to the app.\n",
       "        Normally all callbacks are fired when the associated outputs are first\n",
       "        added to the page. You can disable this for individual callbacks by\n",
       "        setting ``prevent_initial_call`` in their definitions, or set it\n",
       "        ``True`` here in which case you must explicitly set it ``False`` for\n",
       "        those callbacks you wish to have an initial call. This setting has no\n",
       "        effect on triggering callbacks when their inputs change later on.\n",
       "\n",
       "    :param show_undo_redo: Default ``False``, set to ``True`` to enable undo\n",
       "        and redo buttons for stepping through the history of the app state.\n",
       "    :type show_undo_redo: boolean\n",
       "\n",
       "    :param extra_hot_reload_paths: A list of paths to watch for changes, in\n",
       "        addition to assets and known Python and JS code, if hot reloading is\n",
       "        enabled.\n",
       "    :type extra_hot_reload_paths: list of strings\n",
       "\n",
       "    :param plugins: Extend Dash functionality by passing a list of objects\n",
       "        with a ``plug`` method, taking a single argument: this app, which will\n",
       "        be called after the Flask server is attached.\n",
       "    :type plugins: list of objects\n",
       "\n",
       "    :param title: Default ``Dash``. Configures the document.title\n",
       "    (the text that appears in a browser tab).\n",
       "\n",
       "    :param update_title: Default ``Updating...``. Configures the document.title\n",
       "    (the text that appears in a browser tab) text when a callback is being run.\n",
       "    Set to None or '' if you don't want the document.title to change or if you\n",
       "    want to control the document.title through a separate component or\n",
       "    clientside callback.\n",
       "\n",
       "    :param long_callback_manager: Long callback manager instance to support the\n",
       "    ``@app.long_callback`` decorator. Currently an instance of one of\n",
       "    ``DiskcacheLongCallbackManager`` or ``CeleryLongCallbackManager``\n",
       "    "
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashApp.flask_server\" class=\"doc_header\"><code>DashApp.flask_server</code><a href=\"__main__.py#L123\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashApp.flask_server</code>()\n",
       "\n",
       "returns flask server inside self.app, for building wsgi apps"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/markdown": [
       "<h4 id=\"DashApp.run\" class=\"doc_header\"><code>DashApp.run</code><a href=\"__main__.py#L127\" class=\"source_link\" style=\"float:right\">[source]</a></h4>\n",
       "\n",
       "> <code>DashApp.run</code>(**`port`**=*`None`*)\n",
       "\n",
       "Run the dash app"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "show_doc(DashApp)\n",
    "show_doc(DashApp.__init__)\n",
    "show_doc(DashApp.flask_server)\n",
    "show_doc(DashApp.run)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Example use of `DashApp`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can build and run dash app by simply passing a `DashComposite` to `DashApp` and then running it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 143,
   "metadata": {},
   "outputs": [],
   "source": [
    "db = DashApp(list_composite, mode='external', port=9000, querystrings=True, bootstrap=dbc.themes.FLATLY)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- You can set the port with `port=8051`\n",
    "- You can run the dashboard inline in a notebook by pasing `mode='inline'`\n",
    "    - or `mode='external'` or `mode='jupyterlab'`\n",
    "    - default is `mode='dash'`\n",
    "- Track parameters in the url querystring with querystrings=True\n",
    "- Any additional parameters will be passed on the to `dash.Dash()` constructor"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 144,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide \n",
    "run_app = False"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 145,
   "metadata": {},
   "outputs": [],
   "source": [
    "if run_app:\n",
    "    db.run()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also store and reload an entire dashboard:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 146,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dash_app:\n",
      "  class_name: DashApp\n",
      "  module: __main__\n",
      "  params:\n",
      "    dashboard_component:\n",
      "      dash_component:\n",
      "        class_name: ListComposite\n",
      "        module: __main__\n",
      "        params:\n",
      "          list_factory:\n",
      "            dash_figure_factory:\n",
      "              class_name: ListFactory\n",
      "              module: __main__\n",
      "              params:\n",
      "                list_input:\n",
      "                - this\n",
      "                - is\n",
      "                - a\n",
      "                - dumb\n",
      "                - example\n",
      "                filepath: file_factory.pkl\n",
      "          first_n1: 2\n",
      "          first_n2: 3\n",
      "          name: 7wFsEqmpVq\n",
      "    port: 9000\n",
      "    mode: external\n",
      "    querystrings: true\n",
      "    bootstrap: https://cdn.jsdelivr.net/npm/bootswatch@5.1.3/dist/flatly/bootstrap.min.css\n",
      "    kwargs:\n",
      "      external_stylesheets:\n",
      "      - https://cdn.jsdelivr.net/npm/bootswatch@5.1.3/dist/flatly/bootstrap.min.css\n",
      "      suppress_callback_exceptions: true\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(db.to_yaml())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 147,
   "metadata": {},
   "outputs": [],
   "source": [
    "db.to_yaml(\"dashboard.yaml\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 148,
   "metadata": {},
   "outputs": [],
   "source": [
    "db2 = DashApp.from_yaml(\"dashboard.yaml\", force_pickles=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 149,
   "metadata": {},
   "outputs": [],
   "source": [
    "if run_app:\n",
    "    db2.run()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 150,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Converted 00_core.ipynb.\n",
      "Converted 01_cli.ipynb.\n",
      "Converted 02_Example.ipynb.\n",
      "Converted 03_querystrings.ipynb.\n",
      "Converted 04_GunicornDeployment.ipynb.\n",
      "Converted index.ipynb.\n"
     ]
    }
   ],
   "source": [
    "from nbdev.export import *\n",
    "notebook2script()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}