settings_example.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interactive Configuration Class\n",
    "\n",
    "This notebook introduces a Python `Settings` class for holding generic configuration data. The structure of the configuration data is specified using a [JSON Schema](http://json-schema.org) file, against which any input or change is validated. The `Settings` class is also capable of creating a GUI to manipulate the configuration within a Jupyter notebook.\n",
    "\n",
    "To illustrate the use of this class, we will create a fictional configuration for a thermostat with a minimum and maximum temperature, a location string, and a (unspecified) alert function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "schema_json = \"\"\"\n",
    "{\n",
    "  \"title\": \"Thermostat Configuration\",\n",
    "  \"type\": \"object\",\n",
    "  \"properties\": {\n",
    "    \"min_temp\": {\n",
    "      \"description\": \"Minimum temperature\",\n",
    "      \"type\": \"number\",\n",
    "      \"minimum\": -30.0,\n",
    "      \"maximum\": 150.0,\n",
    "      \"default\": 62.0\n",
    "    },\n",
    "    \"max_temp\": {\n",
    "      \"description\": \"Maximum temperature\",\n",
    "      \"type\": \"number\",\n",
    "      \"minimum\": -30.0,\n",
    "      \"maximum\": 150.0,\n",
    "      \"default\": 75.0\n",
    "    },\n",
    "    \"loc\": {\n",
    "      \"description\": \"Location\",\n",
    "      \"type\": \"string\"\n",
    "    },\n",
    "    \"alert\": {\n",
    "      \"description\": \"Activate alert function\",\n",
    "      \"type\": \"boolean\"\n",
    "    }\n",
    "  }\n",
    "}\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can create an empty settings object from this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from ipysettings import Settings\n",
    "import json\n",
    "\n",
    "cfg = Settings(json.loads(schema_json))\n",
    "cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also show a GUI with the default values (defaults are specified in the schema - if the schema does not provide defaults, reasonable values (i.e. 0, False, or empty strings) are assumed). Note that there should be only one active `gui` object at any time (though you can have multiple views of it)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "gui = cfg.interact()\n",
    "display(gui)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's load a configuration from another JSON file (note that the GUI updates automatically):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "config_json = \"\"\"\n",
    "{\n",
    "        \"min_temp\": 42.0,\n",
    "        \"max_temp\": 69.0,\n",
    "        \"loc\": \"Building 1\",\n",
    "        \"alert\": true\n",
    "}\n",
    "\"\"\"\n",
    "cfg.from_json(config_json)\n",
    "cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The configuration elements are accessible like any other collection, and can be used like a dictionary in the application logic to be configured:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg['max_temp']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg['min_temp'] = 33.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "They are also validated according to the underlying JSON schema:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg['min_temp'] = -99.0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Nested settings objects / tabbing\n",
    "\n",
    "The `Settings` class also supports recursive nesting. Let's define a schema for a production line consisting of a thermostat and a flow controller:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "schema_json = \"\"\"\n",
    "{\n",
    "  \"title\": \"Line Configuration\",\n",
    "  \"type\": \"object\",\n",
    "  \"properties\": {\n",
    "    \"Temperature\": {\n",
    "      \"type\": \"object\",\n",
    "      \"properties\": {\n",
    "        \"min_temp\": {\n",
    "          \"description\": \"Minimum temperature\",\n",
    "          \"type\": \"number\",\n",
    "          \"minimum\": -30.0,\n",
    "          \"maximum\": 150.0,\n",
    "          \"default\": 62.0\n",
    "        },\n",
    "        \"max_temp\": {\n",
    "          \"description\": \"Maximum temperature\",\n",
    "          \"type\": \"number\",\n",
    "          \"minimum\": -30.0,\n",
    "          \"maximum\": 150.0,\n",
    "          \"default\": 75.0\n",
    "        },\n",
    "        \"alert\": {\n",
    "          \"description\": \"Activate alert function\",\n",
    "          \"type\": \"boolean\"\n",
    "        }\n",
    "      }\n",
    "    },\n",
    "    \"Flow\": {\n",
    "      \"type\": \"object\",\n",
    "      \"properties\": {\n",
    "        \"min_flow\": {\n",
    "          \"description\": \"Minimum Flow\",\n",
    "          \"type\": \"integer\",\n",
    "          \"minimum\": -42,\n",
    "          \"maximum\": 69,\n",
    "          \"default\": 23\n",
    "        },\n",
    "        \"max_flow\": {\n",
    "          \"description\": \"Maximum Flow\",\n",
    "          \"type\": \"integer\",\n",
    "          \"minimum\": 0,\n",
    "          \"maximum\": 100,\n",
    "          \"default\": 42\n",
    "        }\n",
    "      }\n",
    "    },\n",
    "    \"loc\": {\n",
    "      \"description\": \"Location\",\n",
    "      \"type\": \"string\"\n",
    "    }\n",
    "  }\n",
    "}\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we again create a settings object from the schema:           "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg = Settings(json.loads(schema_json))\n",
    "cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will also have to modify our initialization data to reflect the hierarchy:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "config_json = \"\"\"\n",
    "{\n",
    "    \"Temperature\": {\n",
    "        \"min_temp\": 42.0,\n",
    "        \"max_temp\": 69.0,\n",
    "        \"alert\": true\n",
    "    },\n",
    "    \"Flow\": {\n",
    "        \"min_flow\": 10,\n",
    "        \"max_flow\": 88\n",
    "    },\n",
    "    \"loc\": \"Area 52\"\n",
    "}\"\"\"\n",
    "cfg.from_json(config_json)\n",
    "cfg"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that there are multiple levels of nesting present. This will create a child settings object for every property declared as an `object`. Every object's widgets will be rendered in a separate tab:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg.interact()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can access the individual values like a multi-level dict:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cfg['Temperature']['max_temp'] = 33.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, alternatively, we can get the child configuration and modify it directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp_cfg = cfg['Temperature']\n",
    "temp_cfg.interact()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "temp_cfg['min_temp'] = -3.5"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## TODO\n",
    "\n",
    "- Populate new Settings objects with defaults from schema\n",
    "- ~~Support hierarchy of configuration groups (tabs?)~~ - **done**\n",
    "- Add more special functions to emulate collections completely\n",
    "- Fix broken defaults parsing for booleans from schema\n",
    "- ~~Add docstrings!~~ - **done**\n",
    "- ~~Cache GUI / generate GUI in constructor~~ - **done**\n",
    "- Read 'Fluent Python' and apply to class"
   ]
  },
  {
   "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.7.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}