various cleanup and docs to allow no install in Module

Author: rmorshea

Diff for: idom/__main__.py

@@ -56,11 +56,11 @@ def run(args: argparse.Namespace) -> None:
             )
 
     if args.command == "install":
-        install(args.dependencies or [], args.exports or [])
+        install(args.dependencies or [], args.exports or [], show_spinner=True)
     elif args.command == "uninstall":
         delete_web_modules(args.dependencies)
     elif args.command == "restore":
-        restore()
+        restore(show_spinner=True)
     else:
         print("Installed:")
         for name in installed():

Diff for: idom/client/__init__.py

@@ -4,7 +4,6 @@
     delete_web_modules,
     register_web_module,
     web_module_exists,
-    web_module_path,
     install,
     installed,
     restore,

Diff for: idom/client/manage.py

@@ -27,10 +27,6 @@ def find_path(url_path: str) -> Optional[Path]:
     return STATIC_SHIMS.get(url_path)
 
 
-def web_module_path(name: str) -> Optional[Path]:
-    return find_path(f"web_modules/{name}.js")
-
-
 def web_module_url(name: str) -> str:
     path = f"../{WEB_MODULES_DIR.name}/{name}.js"
     if not web_module_exists(name):
@@ -94,7 +90,9 @@ def installed() -> List[str]:
     return list(sorted(names))
 
 
-def install(packages: Sequence[str], exports: Sequence[str] = ()) -> None:
+def install(
+    packages: Sequence[str], exports: Sequence[str] = (), show_spinner: bool = False
+) -> None:
     with TemporaryDirectory() as tempdir:
         tempdir_path = Path(tempdir)
         temp_static_dir = tempdir_path / "static"
@@ -115,7 +113,7 @@ def install(packages: Sequence[str], exports: Sequence[str] = ()) -> None:
         with (temp_static_dir / "package.json").open("w+") as f:
             json.dump(package_json, f)
 
-        with Spinner(f"Installing: {', '.join(packages)}"):
+        with Spinner(f"Installing: {', '.join(packages)}", show=show_spinner):
             _run_subprocess(["npm", "install"], temp_static_dir)
             _run_subprocess(["npm", "install"] + cache.package_list, temp_static_dir)
             _run_subprocess(["npm", "run", "build"], temp_static_dir)
@@ -128,8 +126,8 @@ def install(packages: Sequence[str], exports: Sequence[str] = ()) -> None:
         shutil.copytree(temp_build_dir, BUILD_DIR, symlinks=True)
 
 
-def restore() -> None:
-    with Spinner("Restoring"):
+def restore(show_spinner: bool = False) -> None:
+    with Spinner("Restoring", show=show_spinner):
         _delete_os_paths(BUILD_DIR)
         _run_subprocess(["npm", "install"], APP_DIR)
         _run_subprocess(["npm", "run", "build"], APP_DIR)

Diff for: idom/client/utils.py

@@ -25,7 +25,8 @@ def __init__(
         failure_frame: str = "✖",
         success_frame: str = "✔",
         rate: float = 0.1,
-        display: Optional[Callable[[Optional[str], str], None]] = None,
+        show: bool = True,
+        display_function: Optional[Callable[[Optional[str], str], None]] = None,
     ) -> None:
         self.text = text
         self.frames = frames
@@ -34,8 +35,11 @@ def __init__(
         self.rate = rate
         self._stop = Event()
         self._stopped = Event()
-        if display is not None:
-            self.display = display
+        if not show:
+            # do nothing on display
+            self.display = lambda *a, **kw: None
+        elif display_function is not None:
+            self.display = display_function
         else:
             self.display = (
                 self._display_notebook

Diff for: idom/widgets/module.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 from typing import Any, Optional, Union
+from urllib.parse import urlparse
 
 from idom import client
 from idom.core.vdom import VdomDict, ImportSourceDict, make_vdom_constructor
@@ -9,49 +10,72 @@ class Module:
     """A Javascript module
 
     Parameters:
-        name:
-            If the module is installed, or ``source`` is not None, then this is the name
-            the the module to import from (omit the ``.js`` file extension). Otherwise
-            this is the URl (relative or absolute) to import from.
-        source:
-            Create a module of the given name using the given source code.
-        replace:
-            Overwrite a module defined from ``source`` if one of the same ``name``
-            already exists, otherwise raise a ``ValueError`` complaining of name
-            conflict.
-
-    Returns:
-        An :class:`Import` element for the newly defined module.
+        path:
+            The URL to an ECMAScript module which exports React components
+            (*with* a ``.js`` file extension) or name of a module installed in the
+            built-in client application (*without* a ``.js`` file extension).
+        source_file:
+            Only applicable if running on the built-in client app. Dynamically install
+            the code in the give file as a single-file module. The built-in client will
+            inject this module adjacent to other installed modules which means they can
+            be imported via a relative path (e.g. ``./some-other-installed-module.js``).
+
+    .. warning::
+
+        Do not use the ``source_file`` parameter if not running with the client app
+        distributed with ``idom``.
+
+    Examples:
+        .. testcode::
+
+            import idom
+
     """
 
     __slots__ = "_module", "_installed"
 
     def __init__(
         self,
-        name: str,
-        source: Optional[Union[str, Path]] = None,
-        replace: bool = False,
+        path: str,
+        source_file: Optional[Union[str, Path]] = None,
     ) -> None:
         self._installed = False
-        if source is not None:
-            if replace:
-                client.delete_web_modules([name], skip_missing=True)
-            self._module = client.register_web_module(name, source)
+        if source_file is not None:
+            self._module = client.register_web_module(path, source_file)
             self._installed = True
-        elif client.web_module_exists(name):
-            self._module = client.web_module_url(name)
+        elif client.web_module_exists(path):
+            self._module = client.web_module_url(path)
+            self._installed = True
+        elif not _is_url(path):
+            raise ValueError(
+                f"{path!r} is not installed - "
+                "only installed modules can omit a file extension."
+            )
         else:
-            self._module = name
+            self._module = path
 
     @property
     def installed(self) -> bool:
+        """Whether or not this module has been installed into the built-in client app."""
         return self._installed
 
     @property
     def url(self) -> str:
+        """The path this module will be imported from"""
         return self._module
 
     def Import(self, name: str, *args: Any, **kwargs: Any) -> "Import":
+        """Return  an :class:`Import` for the given :class:`Module` and ``name``
+
+        This roughly translates to the javascript statement
+
+        .. code-block:: javascript
+
+            import { name } from "module"
+
+        Where ``name`` is the given name, and ``module`` is the :attr:`Module.url` of
+        this :class:`Module` instance.
+        """
         return Import(self._module, name, *args, **kwargs)
 
     def __repr__(self) -> str:  # pragma: no cover
@@ -95,3 +119,11 @@ def __call__(
     def __repr__(self) -> str:  # pragma: no cover
         items = ", ".join(f"{k}={v!r}" for k, v in self._import_source.items())
         return f"{type(self).__name__}({items})"
+
+
+def _is_url(string: str) -> bool:
+    if string.startswith("/") or string.startswith("./") or string.startswith("../"):
+        return True
+    else:
+        parsed = urlparse(string)
+        return parsed.scheme and parsed.netloc

Diff for: tests/test_client/test_manage.py

@@ -33,6 +33,11 @@ def test_install_namespace_package():
     assert client.web_module_url("@material-ui/core") == expected
 
 
+def test_error_on_delete_not_exists():
+    with pytest.raises(ValueError, match=r"Module .*? does not exist"):
+        client.delete_web_modules("module/that/does/not/exist")
+
+
 def test_raise_on_missing_import_path():
     with pytest.raises(ValueError, match="does not exist"):
         client.web_module_url("module/that/does/not/exist")

Diff for: tests/test_client/test_utils.py

@@ -19,7 +19,7 @@ def save_display(frame, text):
         success_frame="success",
         failure_frame="failure",
         rate=0,  # go as fast as we can
-        display=save_display,
+        display_function=save_display,
     )
 
     seen_frames = set()
@@ -50,6 +50,7 @@ def save_display(frame, text):
                 if frame in seen_frames:
                     raise ValueError("we raised this on purpose")
                 seen_frames.add(frame)
+
     # grab the failure frame
     while not displayed_frames.empty():
         seen_frames.add(displayed_frames.get())

Diff for: tests/test_widgets/my_chart.js renamed to tests/test_widgets/my-chart.js

@@ -9,18 +9,25 @@
 HERE = Path(__file__).parent
 
 
-def test_module_cannot_have_source_and_install():
-    with pytest.raises(ValueError, match=r"Both .* were given."):
-        idom.Module("something", install="something", source=HERE / "something.js")
-
-
 @pytest.fixture
 def victory():
     if "victory" not in client.installed():
         client.install(["victory"], [])
     return Module("victory")
 
 
+def test_non_url_must_be_installed():
+    with pytest.raises(ValueError, match="not installed"):
+        Module("module/not/installed")
+
+
+def test_any_relative_or_abolute_url_allowed():
+    Module("/absolute/url/module")
+    Module("./relative/url/module")
+    Module("../relative/url/module")
+    Module("http://someurl.com/module")
+
+
 @pytest.mark.slow
 def test_installed_module(driver, display, victory):
     assert victory.installed
@@ -35,7 +42,7 @@ def test_reference_pre_installed_module(victory):
 
 @pytest.mark.slow
 def test_custom_module(driver, display, victory):
-    my_chart = Module("my/chart", source=HERE / "my_chart.js")
+    my_chart = Module("my/chart", source_file=HERE / "my-chart.js")
 
     assert client.web_module_exists("my/chart")
     assert client.web_module_url("my/chart") == "../web_modules/my/chart.js"
@@ -44,8 +51,7 @@ def test_custom_module(driver, display, victory):
 
     driver.find_element_by_class_name("VictoryContainer")
 
-    my_chart.delete()
-
+    client.delete_web_modules("my/chart")
     assert not client.web_module_exists("my/chart")