01_cli.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# default_exp cli"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#hide\n",
    "from nbdev.showdoc import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "from dash_oop_components.core import *"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "import os\n",
    "import webbrowser\n",
    "from pathlib import Path\n",
    "import click"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# dashapp CLI\n",
    "> a simple way of launching dashboards directly from the commandline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With `dash_oop_components` you can easily dump the configuration for a `dash` dashboard to a configuration `.yaml` file. Along with the library a `dashapp` command line tool (CLI) gets installed to make it easy to directly launch a dashboard from the commandline. \n",
    "\n",
    "This is useful for when:\n",
    "- you quickly want to launch a dashboard without starting python or jupyter, or finding the correct gunicorn config\n",
    "- you want to instruct others how to easily launch your dashboard without messing around with python or gunicorn"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `dashapp` command line tool"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You first need to store your dash app to a config yaml file using e.g \n",
    "    \n",
    "```python \n",
    "db = DashApp(dashboard_component, port=8000, querystrings=True, bootstrap=True)\n",
    "db.to_yaml(\"dashboard.yaml\")\n",
    "```\n",
    "\n",
    "You can then run the app directly from the commandline and have it opened in a browser:\n",
    "\n",
    "```sh  \n",
    "$ dashapp dashboard.yaml\n",
    "```        \n",
    "\n",
    "To try loading the figure factory from pickle, add the `--try-pickles` flag:\n",
    "    \n",
    "```sh\n",
    "$ dashapp --try-pickles dashboard.yaml\n",
    "```     \n",
    "    \n",
    "You can also store a `DashComponent` and run it from the command-line, by saving it to yaml:\n",
    "    \n",
    "```python\n",
    "dashboard_component = CovidDashboard(plot_factory)\n",
    "dashboard_component.to_yaml(\"dashboard_component.yaml\")\n",
    "```\n",
    "\n",
    "And running it:\n",
    "    \n",
    "```sh\n",
    "$ dashapp dashboard_component.yaml\n",
    "```\n",
    "\n",
    "To include the bootstrap css and store parameters in url querystring and set port to 9000:\n",
    "   \n",
    "```sh\n",
    "$ dashapp dashboard_component.yaml --querystrings --bootstrap --port 9000  \n",
    "```\n",
    "\n",
    "If you follow the naming convention of storing the yaml to `dashboard.yaml`, \n",
    "or `dashboard_component.yaml`, you can omit the argument and simply run:\n",
    "    \n",
    "```sh\n",
    "$ dashapp\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "Options:\n",
    "  -nb, --no-browser     Launch a dashboard, but do not launch a browser.\n",
    "  -tp, --try-pickles    if DashFigureFactory parameter config has filepath\n",
    "                        defined, try to load it from pickle.\n",
    "\n",
    "  -fp, --force-pickles  if DashFigureFactory parameter config has filepath\n",
    "                        defined, load it from pickle or raise exception.\n",
    "\n",
    "  -q, --querystrings    Store state in url querystring\n",
    "  -b, --bootstrap       include default bootstrap css\n",
    "  -p, --port INTEGER    specific port to run dashboard on\n",
    "  --help                Show this message and exit.\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#export\n",
    "\n",
    "\n",
    "@click.command()\n",
    "@click.argument(\"dashboard_yaml\", nargs=1, required=False)\n",
    "@click.option(\"--no-browser\", \"-nb\", \"no_browser\", is_flag=True,\n",
    "                 help=\"Launch a dashboard, but do not launch a browser.\")\n",
    "@click.option(\"--try-pickles\", \"-tp\", \"try_pickles\", is_flag=True,\n",
    "                 help=\"if DashFigureFactory parameter config has filepath defined, try to load it from pickle.\")\n",
    "@click.option(\"--force-pickles\", \"-fp\", \"force_pickles\", is_flag=True,\n",
    "                 help=\"if DashFigureFactory parameter config has filepath defined, load it from pickle or raise exception.\")\n",
    "@click.option(\"--querystrings\", \"-q\", \"querystrings\", is_flag=True,\n",
    "                 help=\"Store state in url querystring\")\n",
    "@click.option(\"--bootstrap\", \"-b\", \"bootstrap\", is_flag=True,\n",
    "                 help=\"include default bootstrap css\")\n",
    "@click.option(\"--port\", \"-p\", \"port\", default=None, type=click.INT,\n",
    "                help=\"specific port to run dashboard on\")\n",
    "def dashapp(dashboard_yaml, no_browser, try_pickles, force_pickles, querystrings, bootstrap, port):\n",
    "    \"\"\"\n",
    "    dashapp is a CLI tool from the dash_oop_components library, used to launch a dash app from the commandline. \n",
    "\n",
    "    You first need to store your dash app to a config yaml file using e.g \n",
    "    \n",
    "    \\b\n",
    "        db = DashApp(dashboard_component, port=8000)\n",
    "        db.to_yaml(\"dashboard.yaml\")\n",
    "    \n",
    "    \\b\n",
    "    You can then run the app directly from the commandline with and open it in a browser:\n",
    "    \n",
    "        $ dashapp dashboard.yaml\n",
    "        \n",
    "    or try the load figure factory from pickle:\n",
    "    \n",
    "        $ dashapp --try-pickles dashboard.yaml\n",
    "        \n",
    "    \n",
    "    You can also store and run a DashComponent, by saving it to yaml:\n",
    "    \n",
    "    \\b\n",
    "        dashboard_component = CovidDashboard(plot_factory)\n",
    "        dashboard_component.to_yaml(\"dashboard_component.yaml\")\n",
    "    \n",
    "    And running it:\n",
    "    \n",
    "        $ dashapp dashboard_component.yaml\n",
    "    \n",
    "    To include the bootstrap css and store parameters in url querystring:\n",
    "    \n",
    "        $ dashapp dashboard_component.yaml --querystrings --bootstrap    \n",
    "    \n",
    "    If you follow the naming convention of storing the yaml to `dashboard.yaml`, \n",
    "    or `dashboard_component.yaml`, you can omit the argument and simply run:\n",
    "    \n",
    "        $ dashapp\n",
    "    \"\"\"\n",
    "    if dashboard_yaml is None:\n",
    "        if (Path().cwd() / \"dashboard.yaml\").exists():\n",
    "            dashboard_yaml = Path().cwd() / \"dashboard.yaml\"\n",
    "        elif (Path().cwd() / \"dashboard_component.yaml\").exists():\n",
    "            dashboard_yaml = Path().cwd() / \"dashboard_component.yaml\"\n",
    "        else:\n",
    "            click.echo(\"No argument given and could find neither a \"\n",
    "                    \"default filename dashboard.yaml or dashboard_component.yaml.\"\n",
    "                    \"Try `dashapp --help` for options. Aborting.\")\n",
    "            return\n",
    "\n",
    "    if not str(dashboard_yaml).endswith(\".yaml\"):\n",
    "        click.echo(\"you need to pass a .yaml file to start a dashboard! Aborting.\")\n",
    "        return \n",
    "    \n",
    "    kwargs = {}\n",
    "    if try_pickles: kwargs[\"try_pickles\"] = True\n",
    "    if force_pickles: kwargs[\"force_pickles\"] = True\n",
    "        \n",
    "    dashboard_component = DashComponentBase.from_yaml(dashboard_yaml, **kwargs)\n",
    "    if isinstance(dashboard_component, DashApp):\n",
    "        db = dashboard_component\n",
    "    elif isinstance(dashboard_component, DashComponent):\n",
    "        db_kwargs = {}\n",
    "        if querystrings: db_kwargs[\"querystrings\"] = True\n",
    "        if bootstrap: db_kwargs[\"bootstrap\"] = True\n",
    "            \n",
    "        db = DashApp(dashboard_component, **db_kwargs)\n",
    "\n",
    "    if port is None: \n",
    "        port =  db.port\n",
    "        if port is None:\n",
    "            port = 8050\n",
    "\n",
    "    import socket\n",
    "    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)\n",
    "    sock.settimeout(2) \n",
    "    result = sock.connect_ex(('127.0.0.1',port))\n",
    "    if result == 0:\n",
    "        click.echo(f\"dashapp ===> Port {port} already in use! Please override with e.g. --port {port+1}\")\n",
    "        return\n",
    "            \n",
    "    if not no_browser and not os.environ.get(\"WERKZEUG_RUN_MAIN\"):\n",
    "        click.echo(f\"explainerdashboard ===> launching browser at {f'http://localhost:{port}/'}\")\n",
    "        webbrowser.open_new(f\"http://localhost:{port}/\")\n",
    "    \n",
    "    click.echo(f\"dashapp ===> Starting dashboard:\")\n",
    "\n",
    "    db.run(port)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}