misc updates

- minor doc changes
- vdom function now access children as positional arguments
  the tradeoff here is that attributes must not contain a
  key named `tagName` (which isn't too much to ask).
- updates of elements can now be triggered withing threads
  which means that you can call `self.update()` when
  `run_in_executor=True` was specified.
- enable mypy --strict

Author: rmorshea

.pre-commit-config.yaml

@@ -8,13 +8,13 @@ repos:
     rev: 3.7.9
     hooks:
       - id: flake8
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v0.761
-    hooks:
-      - id: mypy
-        additional_dependencies: [pyalect]
   - repo: https://github.com/kynan/nbstripout
     rev: master
     hooks:
       - id: nbstripout
         files: ".ipynb"
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v0.770
+    hooks:
+      - id: mypy
+        additional_dependencies: [pyalect, sanic<19.12.0]

docs/source/javascript-modules.rst

@@ -3,46 +3,54 @@ Javascript Modules
 
 .. note::
 
-    This is recent feature of IDOM. If you have a problem following this tutorial
+    This is a recent feature of IDOM. If you have a problem following this tutorial
     `post an issue <https://github.com/rmorshea/idom/issues>`__.
 
-While IDOM is a great tool for displaying HTML and respond to browser events with
+While IDOM is a great tool for displaying HTML and responding to browser events with
 pure Python, there are other projects which already allow you to do this inside
 `Jupyter Notebooks <https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Basics.html>`__
 or in
 `webpages <https://blog.jupyter.org/and-voil%C3%A0-f6a2c08a4a93?gi=54b835a2fcce>`__.
 The real power of IDOM comes from its ability to seemlessly leverage the existing
 ecosystem of
 `React components <https://reactjs.org/docs/components-and-props.html>`__.
+
 So long as your library of interest is an
 `ES Module <https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/>`__
 you could install using
 `Snowpack <https://www.snowpack.dev/>`__
-you can use it with IDOM (we're working to support non-standard packages too) [GH-166]_.
+you can use it with IDOM
 You can even define your own Javascript modules which use these third party Javascript
 packages.
 
+.. note::
+
+    We're working to support non-standard packages too [GH166]_.
 
 Installing React Components
 ---------------------------
 
-.. note::
+Before you start:
 
-    - Be sure that you've installed `npm <https://www.npmjs.com/get-npm>`__.
+- Be sure that you've installed `npm <https://www.npmjs.com/get-npm>`__.
 
-    - We're assuming the presence of a :ref:`Display Function` for our examples.
+- We're assuming the presence of a :ref:`Display Function` for our examples.
 
 Once you've done this you can get started right away. In this example we'll be using a
 charting library for React called `Victory <https://formidable.com/open-source/victory/>`__.
 Installing it in IDOM is quite simple. Just create a :class:`~idom.widgets.utils.Module`,
-tell it what to install and specify ``install=True`` (we're working on a CLI for this) [GH-167]_:
+tell it what to install and specify ``install=True``.
 
 .. code-block::
 
     import idom
     # this may take a minute to download and install
     victory = idom.Module(name="victory", install=True)
 
+.. note::
+
+    We're working on a CLI for this [GH167]_
+
 You can install a specific version using ``install="[email protected]`` or any other
 standard javascript dependency specifier. Alternatively, if you need to access a module
 in a subfolder of your desired Javascript package, you can provide ``name="path/to/module"``

docs/source/known-issues.rst

@@ -1,5 +1,5 @@
 Known Issues
 ============
 
-.. [GH-166] https://github.com/rmorshea/idom/issues/166
-.. [GH-167] https://github.com/rmorshea/idom/issues/167
+.. [GH166] https://github.com/rmorshea/idom/issues/166
+.. [GH167] https://github.com/rmorshea/idom/issues/167

examples/introduction.ipynb

@@ -69,11 +69,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from idom.server import multiview_server\n",
+    "from idom.server import multiview_server, find_available_port\n",
     "from idom.server.sanic import PerClientState\n",
     "from example_utils import display_href, example_server_url, pretty_dict_string\n",
     "\n",
-    "host, port = \"127.0.0.1\", 8765\n",
+    "host = \"127.0.0.1\"\n",
+    "port = find_available_port(host)\n",
     "mount, server = multiview_server(PerClientState, host, port, {\"cors\": True}, {\"access_log\": False})\n",
     "server_url = example_server_url(host, port)\n",
     "\n",
@@ -229,7 +230,7 @@
     "    task_input = idom.html.input({\"onKeyDown\": add_new_task})\n",
     "    task_list = TaskList(items)\n",
     "\n",
-    "    return idom.html.div([task_input, task_list])\n",
+    "    return idom.html.div(task_input, task_list)\n",
     "\n",
     "\n",
     "@idom.element\n",
@@ -242,9 +243,9 @@
     "            del items[index]\n",
     "            self.update(items)\n",
     "\n",
-    "        task_text = idom.html.td([idom.html.p([text])])\n",
-    "        delete_button = idom.html.td({\"onClick\": remove}, [idom.html.button([\"x\"])])\n",
-    "        tasks.append(idom.html.tr([task_text, delete_button]))\n",
+    "        task_text = idom.html.td(idom.html.p(text))\n",
+    "        delete_button = idom.html.td({\"onClick\": remove}, idom.html.button(\"x\"))\n",
+    "        tasks.append(idom.html.tr(task_text, delete_button))\n",
     "\n",
     "    return idom.html.table(tasks)\n",
     "\n",
@@ -327,14 +328,18 @@
     "        diff = random.gauss(float(mu_var.get()), float(sigma_var.get()))\n",
     "        y.append(y[-1] + diff)\n",
     "        plot.update(x, y)\n",
-    "    \n",
-    "    style = idom.html.style([\"\"\"\n",
-    "    .linked-inputs {margin-bottom: 20px}\n",
-    "    .linked-inputs input {width: 48%;float: left}\n",
-    "    .linked-inputs input + input {margin-left: 4%}\n",
-    "    \"\"\"])\n",
     "\n",
-    "    return idom.html.div({\"style\": {\"width\": \"60%\"}}, [style, plot, mu_inputs, sigma_inputs])\n",
+    "    style = idom.html.style(\n",
+    "        \"\"\"\n",
+    "        .linked-inputs {margin-bottom: 20px}\n",
+    "        .linked-inputs input {width: 48%;float: left}\n",
+    "        .linked-inputs input + input {margin-left: 4%}\n",
+    "        \"\"\"\n",
+    "    )\n",
+    "\n",
+    "    return idom.html.div(\n",
+    "        {\"style\": {\"width\": \"60%\"}}, style, plot, mu_inputs, sigma_inputs\n",
+    "    )\n",
     "\n",
     "\n",
     "@idom.element(run_in_executor=True)\n",
@@ -362,7 +367,7 @@
     "\n",
     "        inputs.append(inp)\n",
     "\n",
-    "    fs = idom.html.fieldset({\"class\": \"linked-inputs\"}, [idom.html.legend(label)], inputs)\n",
+    "    fs = idom.html.fieldset({\"class\": \"linked-inputs\"}, idom.html.legend(label), inputs)\n",
     "\n",
     "    return var, fs\n",
     "\n",
@@ -404,7 +409,7 @@
    "source": [
     "@idom.element\n",
     "async def DragDropBoxes(self):\n",
-    "    last_owner =idom.Var(None)\n",
+    "    last_owner = idom.Var(None)\n",
     "    last_hover = idom.Var(None)\n",
     "\n",
     "    h1 = Holder(\"filled\", last_owner, last_hover)\n",
@@ -413,44 +418,45 @@
     "\n",
     "    last_owner.set(h1)\n",
     "\n",
-    "    style = idom.html.style([\"\"\"\n",
-    "    .holder {\n",
-    "      height: 150px;\n",
-    "      width: 150px;\n",
-    "      margin: 20px;\n",
-    "      display: inline-block;\n",
-    "    }\n",
-    "    .holder-filled {\n",
-    "      border: solid 10px black;\n",
-    "      background-color: black;\n",
-    "    }\n",
-    "    .holder-hover {\n",
-    "      border: dotted 5px black;\n",
-    "    }\n",
-    "    .holder-empty {\n",
-    "      border: solid 5px black;\n",
-    "      background-color: white;\n",
-    "    }\n",
-    "    \"\"\"])\n",
-    "\n",
-    "    return idom.html.div([style, h1, h2, h3])\n",
+    "    style = idom.html.style(\n",
+    "        \"\"\"\n",
+    "        .holder {\n",
+    "          height: 150px;\n",
+    "          width: 150px;\n",
+    "          margin: 20px;\n",
+    "          display: inline-block;\n",
+    "        }\n",
+    "        .holder-filled {\n",
+    "          border: solid 10px black;\n",
+    "          background-color: black;\n",
+    "        }\n",
+    "        .holder-hover {\n",
+    "          border: dotted 5px black;\n",
+    "        }\n",
+    "        .holder-empty {\n",
+    "          border: solid 5px black;\n",
+    "          background-color: white;\n",
+    "        }\n",
+    "        \"\"\"\n",
+    "    )\n",
+    "\n",
+    "    return idom.html.div(style, h1, h2, h3)\n",
     "\n",
     "\n",
     "@idom.element(state=\"last_owner, last_hover\")\n",
     "async def Holder(self, kind, last_owner, last_hover):\n",
-    "\n",
     "    @idom.event(prevent_default=True, stop_propagation=True)\n",
     "    async def hover(event):\n",
     "        if kind != \"hover\":\n",
     "            self.update(\"hover\")\n",
     "            old = last_hover.set(self)\n",
     "            if old is not None and old is not self:\n",
     "                old.update(\"empty\")\n",
-    "    \n",
+    "\n",
     "    async def start(event):\n",
     "        last_hover.set(self)\n",
     "        self.update(\"hover\")\n",
-    "    \n",
+    "\n",
     "    async def end(event):\n",
     "        last_owner.get().update(\"filled\")\n",
     "\n",
@@ -463,15 +469,17 @@
     "            old.update(\"empty\")\n",
     "        self.update(\"filled\")\n",
     "\n",
-    "    return idom.html.div({\n",
-    "        \"draggable\": (kind == \"filled\"),\n",
-    "        \"onDragStart\": start,\n",
-    "        \"onDragOver\": hover,\n",
-    "        \"onDragEnd\": end,\n",
-    "        \"onDragLeave\": leave,\n",
-    "        \"onDrop\": dropped,\n",
-    "        \"class\": f\"holder-{kind} holder\",\n",
-    "    })\n",
+    "    return idom.html.div(\n",
+    "        {\n",
+    "            \"draggable\": (kind == \"filled\"),\n",
+    "            \"onDragStart\": start,\n",
+    "            \"onDragOver\": hover,\n",
+    "            \"onDragEnd\": end,\n",
+    "            \"onDragLeave\": leave,\n",
+    "            \"onDrop\": dropped,\n",
+    "            \"class\": f\"holder-{kind} holder\",\n",
+    "        }\n",
+    "    )\n",
     "\n",
     "\n",
     "print(\"Click and drag the black box onto the white one! 👆\")\n",
@@ -628,7 +636,7 @@
     "        \n",
     "    )\n",
     "\n",
-    "\n",
+    "first_view_mounted\n",
     "@idom.element(state=\"block_size\")\n",
     "async def Block(self, color, block_size):\n",
     "    return idom.html.div(\n",
@@ -776,9 +784,11 @@
     "from idom.server.sanic import SharedClientState\n",
     "from example_utils import display_href, example_server_url, pretty_dict_string\n",
     "\n",
-    "shared_server_url = example_server_url(\"127.0.0.1\", 5678)\n",
+    "host = \"127.0.0.1\"\n",
+    "port = find_available_port(host)\n",
+    "shared_server_url = example_server_url(host, port)\n",
     "mount_shared, shared_server  = hotswap_server(\n",
-    "    SharedClientState, \"127.0.0.1\", 5678, {\"cors\": True}, {\"access_log\": False}\n",
+    "    SharedClientState, host, port, {\"cors\": True}, {\"access_log\": False}\n",
     ")\n",
     "\n",
     "def display_shared(element, *args, **kwargs):\n",

idom/client/__init__.py

@@ -4,7 +4,7 @@
 from loguru import logger
 from pathlib import Path
 from tempfile import TemporaryDirectory
-from typing import Optional, List, Union, Dict
+from typing import Optional, List, Union, Dict, Any
 
 
 CLIENT_DIR = Path(__file__).parent
@@ -73,7 +73,7 @@ def restore() -> None:
     _run_subprocess(["npm", "run", "snowpack"], CLIENT_DIR)
 
 
-def _package_json():
+def _package_json() -> Dict[str, Any]:
     with (CLIENT_DIR / "package.json").open("r") as f:
         dependencies = json.load(f)["dependencies"]
 
@@ -91,7 +91,7 @@ def _package_json():
     }
 
 
-def _run_subprocess(args: List[str], cwd: Union[str, Path]):
+def _run_subprocess(args: List[str], cwd: Union[str, Path]) -> None:
     try:
         subprocess.run(
             args, cwd=cwd, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE
@@ -100,6 +100,7 @@ def _run_subprocess(args: List[str], cwd: Union[str, Path]):
         if error.stderr is not None:
             logger.error(error.stderr.decode())
         raise
+    return None
 
 
 def _find_module_os_path(path: Path, name: str) -> Optional[Path]:

idom/core/element.py

@@ -86,7 +86,7 @@ class AbstractElement(abc.ABC):
 
     __slots__ = ["_layout"]
 
-    if not hasattr(abc.ABC, "__weakref__"):
+    if not hasattr(abc.ABC, "__weakref__"):  # pragma: no cover
         __slots__.append("__weakref__")
 
     def __init__(self) -> None:
@@ -211,10 +211,8 @@ def setup(function: _ANM) -> _ANM:
 
             async def animation() -> None:
                 while True:
-                    await function(cancel_animation_future)
-                    # we need another await here in order to catch
-                    # a cancellation call (not sure why though)
                     await pacer.wait()
+                    await function(cancel_animation_future)
 
             # we store this future for later so we can cancel it
             future = asyncio.ensure_future(animation())
@@ -240,14 +238,13 @@ async def render(self) -> Any:
         # load update and reset for next render
         state = self._state
 
-        if state is None:
-            raise RuntimeError(f"{self} cannot render - element has no state.")
-
         for name in self._cross_update_parameters:
             if name not in state:
+                # carry state across update calls implicitely
                 if name in self._cross_update_state:
                     state[name] = self._cross_update_state[name]
             else:
+                # cross-update state parameter was set explicitely
                 self._cross_update_state[name] = state[name]
 
         self._state_updated = False
@@ -289,16 +286,16 @@ def _render_in_executor(self, state: Dict[str, Any]) -> Any:
         return result
 
     def __repr__(self) -> str:
-        qualname = getattr(self._function, "__qualname__", None)
-        if qualname is not None:
-            return "%s(%s)" % (qualname, self.id)
-        else:
-            return "%s(%r, %r)" % (type(self).__name__, self._function, self.id)
+        total_state = {**self._cross_update_state, **self._state}
+        state = ", ".join(f"{k}={v!r}" for k, v in total_state.items())
+        return f"{self._function.__qualname__}({self.id}, {state})"
 
 
 class FramePacer:
     """Simple utility for pacing frames in an animation loop."""
 
+    __slots__ = "_rate", "_last"
+
     def __init__(self, rate: float):
         self._rate = rate
         self._last = time.time()