More fixes and tweaks

jtpio · Oct 27, 2024 · 91597bd · 91597bd
1 parent 3362dcd
commit 91597bd
Show file tree

Hide file tree

Showing 23 changed files with 806 additions and 467 deletions.
diff --git a/examples/commands.ipynb b/examples/commands.ipynb
diff --git a/examples/dialogs.ipynb b/examples/dialogs.ipynb
@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**To use this notebook:** Run one line at a time waiting for each cell to return before running the next cell."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,

diff --git a/examples/generic.ipynb b/examples/generic.ipynb
@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**To use this notebook:** Run one line at a time waiting for each cell to return before running the next cell."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -13,23 +20,61 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Generic methods\n",
+    "# Ipylab\n",
+    "\n",
+    "`Ipylab` is the primary class that provides functionality for scheduling and awaiting operations between Python objects and the corresponding model in the frontend. Each operation is run as a Task which is assigned a UUID and sent as a custom message. \n",
     "\n",
-    "`Ipylab` is the Python class that provides a set of methods that are associated with a `base` object in the Frontend. The `base` is specified on the object registered by its `cid`. The following methods are provided to interact with the `base`: \n",
+    "`IpylabModel` has a `base` object that is set prior to being *ready*. The base object is specified by the Python class and located by the frontend model with the `ipylabInit` method (customised by other subclasses). \n",
+    "\n",
+    "## Operations\n",
+    "\n",
+    "The `operation` method is the workhorse through which all asynchronous messaging is done. It will always return a task. Each operation much be implement in the frontend model. \n",
+    "\n",
+    "\n",
+    "## Generic methods\n",
+    "\n",
+    " `Ipylab` implements the following generic methods interact with objects in the fronted: \n",
     "\n",
     "* execute_method\n",
     "* get_property\n",
     "* set_property\n",
     "* update_property\n",
     "* list_properties\n",
     "\n",
-    "# Connection\n",
+    "These methods pass an object to utility functions reducing the need to write corresponding code in the frontend. \n",
+    "\n",
+    "By default the methods the `base`. A different base object can be specified `obj=Obj.###` to specify a different path.\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Connection\n",
+    "\n",
+    "A `Connection` is subclassed from `Ipylab` providing a connection to an object in the Frontend. \n",
+    "\n",
+    "Each connection has a unique `cid` (stands for connection id).  The `cid` consists of the class prefix `ipylab-<CLASS NAME>|` followed by one or more parts joined with a pipe. The class prefix part of the cid determines the type of class that is created when creating a new instance.\n",
+    "\n",
+    "In the kernel there is only one instance of a Connection object per `cid`. For example: calling `Connection('ipylab-Connection|my cid')` multiple times will get the same object inside the same kernel.\n",
+    "\n",
+    "The object in the frontend is stored as an ObservableDisposable and once it has be set, it cannot be replaced with another object, unless it has been disposed.\n",
+    "\n",
+    "Calling the close method in Python will by default dispose of the object in the frontend. This can behavior can be changed by using `dispose=False`, or previously setting the 'auto_dispose` trait to False.\n",
+    "\n",
+    "\n",
+    "### Subclasses\n",
+    "\n",
+    "Subclasses of `Connection` are identified by its *prefix* `.\n",
+    "\n",
+    "### Connection models\n",
     "\n",
-    "A disposable connection is subclassed from `Ipylab` and is associated to a disposable object in the Frontend. Disposable connections are created when the transform is specified as `Transform.connection`. The generic methods apply directly to the disposable object. \n",
+    "There are two models for connections, `ConnectionModel` and `ShellConnectionModel`. `ShellConnectionModel` is specific for widgets that are loaded in the shell.\n",
     "\n",
-    "Subclasses of `Connection` add additional features specific to the disposable. For example, `CommandConnection` is provided for commands. \n",
+    "### Making a connection\n",
     "\n",
-    "## Making a connection\n",
+    "Many of the builtin methods return connections.\n",
     "\n",
     "The easiest way to create a connection is to specify the `transform` as a `Transform.connection`. Examples:\n",
     "\n",
@@ -145,7 +190,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.15"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

diff --git a/examples/icons.ipynb b/examples/icons.ipynb
@@ -5,21 +5,29 @@
    "id": "0",
    "metadata": {},
    "source": [
-    "# Icons"
+    "**To use this notebook:** Run one line at a time waiting for each cell to return before running the next cell."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "1",
    "metadata": {},
+   "source": [
+    "# Icons"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2",
+   "metadata": {},
    "source": [
     "Icons can be applied to both the `Title` of a `Panel` [widgets](./widgets.ipynb) and [commands](./commands.ipynb), providing more customization than `icon_class`."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "2",
+   "id": "3",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -29,7 +37,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "3",
+   "id": "4",
    "metadata": {
     "tags": []
    },
@@ -45,7 +53,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "4",
+   "id": "5",
    "metadata": {},
    "source": [
     "## SVG\n",
@@ -62,7 +70,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "5",
+   "id": "6",
    "metadata": {
     "tags": []
    },
@@ -76,7 +84,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "6",
+   "id": "7",
    "metadata": {},
    "source": [
     "Icons can be displayed directly, and sized with the `layout` member inherited from `ipywidgets.DOMWidget`."
@@ -85,7 +93,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "7",
+   "id": "8",
    "metadata": {
     "tags": []
    },
@@ -97,7 +105,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "8",
+   "id": "9",
    "metadata": {},
    "source": [
     "### More about `jp-icon` classes\n",
@@ -107,7 +115,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "9",
+   "id": "10",
    "metadata": {
     "tags": []
    },
@@ -128,7 +136,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "10",
+   "id": "11",
    "metadata": {},
    "source": [
     "## Icons on Panel Titles\n",
@@ -139,7 +147,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "11",
+   "id": "12",
    "metadata": {
     "tags": []
    },
@@ -153,7 +161,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "12",
+   "id": "13",
    "metadata": {},
    "source": [
     "### More Title Options\n",
@@ -164,7 +172,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "13",
+   "id": "14",
    "metadata": {
     "tags": []
    },
@@ -196,7 +204,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "14",
+   "id": "15",
    "metadata": {},
    "source": [
     "## Icons on Commands\n",
@@ -207,7 +215,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "15",
+   "id": "16",
    "metadata": {
     "tags": []
    },
@@ -226,7 +234,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "16",
+   "id": "17",
    "metadata": {
     "tags": []
    },
@@ -243,7 +251,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "17",
+   "id": "18",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -252,7 +260,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "18",
+   "id": "19",
    "metadata": {},
    "source": [
     "We can use methods on `cmd` (Connection for the cmd registered in the Frontend) to add it to the command pallet, and create a launcher."
@@ -261,7 +269,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "19",
+   "id": "20",
    "metadata": {
     "tags": []
    },
@@ -273,7 +281,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "20",
+   "id": "21",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -283,16 +291,16 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "21",
+   "id": "22",
    "metadata": {},
    "outputs": [],
    "source": [
-    "assert cmd in panel.app.commands.items  # noqa: S101"
+    "assert cmd in panel.app.commands.connections  # noqa: S101"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "22",
+   "id": "23",
    "metadata": {},
    "source": [
     "Then open the _Command Palette_ (keyboard shortcut is `CTRL + SHIFT + C`).\n",
@@ -303,18 +311,18 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "23",
+   "id": "24",
    "metadata": {
     "tags": []
    },
    "outputs": [],
    "source": [
-    "asyncio.get_running_loop().call_later(1, panel.app.execute_command, \"apputils:activate-command-palette\")"
+    "asyncio.get_running_loop().call_later(1, panel.app.commands.execute, \"apputils:activate-command-palette\")"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "24",
+   "id": "25",
    "metadata": {},
    "source": [
     "And run 'Randomize my icon'"
@@ -323,11 +331,11 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "25",
+   "id": "26",
    "metadata": {},
    "outputs": [],
    "source": [
-    "panel.app.execute_command(cmd, count=1)"
+    "panel.app.commands.execute(cmd, {\"count\": 1})"
    ]
   }
  ],
@@ -347,7 +355,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.14"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,

diff --git a/examples/ipytree.ipynb b/examples/ipytree.ipynb
@@ -301,7 +301,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "When the \"Open\" button is clicked, we call `app.execute_command` with the path to the file to open it in the JupyterLab interface."
+    "When the \"Open\" button is clicked, we call `app.commands.execute` with the path to the file to open it in the JupyterLab interface."
    ]
   },
   {
@@ -314,7 +314,7 @@
     "    for node in file_tree.selected_nodes:\n",
     "        filepath = node.fullpath\n",
     "        if filepath:\n",
-    "            app.execute_command(\"docmanager:open\", path=filepath)\n",
+    "            app.commands.execute(\"docmanager:open\", {\"path\": filepath})\n",
     "\n",
     "\n",
     "open_button.on_click(on_open_clicked)"