From fd256ea07423a818c9a38dceab46554d2c81014b Mon Sep 17 00:00:00 2001
From: Corran Webster <corran.webster@gmail.com>
Date: Thu, 18 Apr 2024 09:46:26 +0100
Subject: [PATCH] Update interact documentation to discuss type annotations.

---
 docs/source/examples/Using Interact.ipynb | 115 +++++++++++++++++++++-
 1 file changed, 111 insertions(+), 4 deletions(-)

diff --git a/docs/source/examples/Using Interact.ipynb b/docs/source/examples/Using Interact.ipynb
index db26232faf..9f58f28174 100644
--- a/docs/source/examples/Using Interact.ipynb	
+++ b/docs/source/examples/Using Interact.ipynb	
@@ -18,7 +18,9 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
-    "tags": ["remove-cell"]
+    "tags": [
+     "remove-cell"
+    ]
    },
    "outputs": [],
    "source": [
@@ -353,6 +355,111 @@
     "interact(f, x=widgets.Combobox(options=[\"Chicago\", \"New York\", \"Washington\"], value=\"Chicago\"));"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Type Annotations"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If the function that you are using with interact uses type annotations, `interact` may be able to use those to determine what UI components to use in the auto-generated UI.  For example, given a function with an argument annotated with type `float`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def f(x: float):\n",
+    "    return x"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "then `interact` will create a UI with a `FloatText` component without needing to be passed any values or abbreviations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "interact(f);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The following table gives an overview of different annotation types, and how they map to interactive controls:\n",
+    "\n",
+    "<table class=\"table table-condensed table-bordered\">\n",
+    "  <tr><td><strong>Type Annotation</strong></td><td><strong>Widget</strong></td></tr>  \n",
+    "  <tr><td>`bool`</td><td>Checkbox</td></tr>  \n",
+    "  <tr><td>`str`</td><td>Text</td></tr>\n",
+    "  <tr><td>`int`</td><td>IntText</td></tr>\n",
+    "  <tr><td>`float`</td><td>FloatText</td></tr>\n",
+    "  <tr><td>`Enum` subclasses</td><td>Dropdown</td></tr>\n",
+    "</table>\n",
+    "\n",
+    "Other type annotations are ignored."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If values or abbreviations are passed to the `interact` function, those will override any type annotations when determining what widgets to create."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Parameters which are annotationed with an `Enum` subclass will have a dropdown created whose labels are the names of the enumeration and which pass the corresponding values to the function parameter."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from enum import Enum\n",
+    "\n",
+    "class Color(Enum):\n",
+    "    red = 0\n",
+    "    green = 1\n",
+    "    blue = 2\n",
+    "\n",
+    "def h(color: Color):\n",
+    "    return color"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When `interact` is used with the function `h`, the Dropdown widget it creates will have options `\"red\"`, `\"green\"` and `\"blue\"` and the values passed to the function will be, correspondingly, `Color.red`, `Color.green` and `Color.blue`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "interact(h);"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -715,7 +822,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -762,9 +869,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.5"
+   "version": "3.12.2"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }