create well defined client implementation layer

now the internals of IDOM use idom.client.protocol.client_implementation
where possible (e.g. idom.Module) in order to allow different client
implementations to be patched in.

Author: rmorshea

idom/__init__.py

@@ -3,17 +3,19 @@
     DistributionNotFound as _DistributionNotFound,
 )
 
+from .utils import Ref, html_to_vdom
+
 from .core.element import element, Element
 from .core.events import event, Events
 from .core.layout import Layout
 from .core.vdom import vdom, VdomDict
 from .core import hooks
 
 from .widgets.html import html
-from .widgets.module import Module, Import
 from .widgets.utils import hotswap, multiview
 
-from .utils import Ref, html_to_vdom
+from .client.module import Module, Import
+from .client.protocol import client_implementation as client
 
 from . import server
 from . import widgets
@@ -59,4 +61,5 @@
     "html_to_vdom",
     "VdomDict",
     "widgets",
+    "client",
 ]

idom/client/__init__.py

@@ -1,22 +1,5 @@
-from .manage import (
-    web_module_url,
-    find_path,
-    delete_web_modules,
-    register_web_module,
-    web_module_exists,
-    install,
-    installed,
-    restore,
-)
+from .protocol import client_implementation
+from .module import Module, Import
 
-__all__ = [
-    "web_module_url",
-    "find_path",
-    "delete_web_modules",
-    "register_web_module",
-    "web_module_exists",
-    "web_module_path",
-    "install",
-    "installed",
-    "restore",
-]
+
+__all__ = ["client_implementation", "Module", "Import"]

idom/widgets/module.py renamed to idom/client/module.py

@@ -2,67 +2,60 @@
 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
 
+from .protocol import client_implementation as client
+
 
 class Module:
     """A Javascript module
 
     Parameters:
-        path:
+        url_or_name:
             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
-
+            Only applicable if running on a client app which supports this feature.
+            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 like
+            ``./some-other-installed-module.js``.
+
+    Attributes:
+        installed:
+            Whether or not this module has been installed into the built-in client app.
+        url:
+            The URL this module will be imported from.
+
+    Notes:
+        To allow for other client implementations, you can set the current client
+        implementation
+        following private methods to support serving dynamically registered source
+        files or loading modules that have been installed by some other means:
     """
 
-    __slots__ = "_module", "_installed"
+    __slots__ = "url", "installed"
 
     def __init__(
         self,
-        path: str,
+        url_or_name: str,
         source_file: Optional[Union[str, Path]] = None,
     ) -> None:
-        self._installed = False
+        self.installed = False
         if source_file is not None:
-            self._module = client.register_web_module(path, source_file)
-            self._installed = True
-        elif client.web_module_exists(path):
-            self._module = client.web_module_url(path)
-            self._installed = True
-        elif not _is_url(path):
+            self.url = client.current.register_web_module(url_or_name, source_file)
+            self.installed = True
+        elif client.current.web_module_exists(url_or_name):
+            self.url = client.current.web_module_url(url_or_name)
+            self.installed = True
+        elif _is_url(url_or_name):
+            self.url = url_or_name
+        else:
             raise ValueError(
-                f"{path!r} is not installed - "
+                f"{url_or_name!r} is not installed - "
                 "only installed modules can omit a file extension."
             )
-        else:
-            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``
@@ -76,10 +69,10 @@ def Import(self, name: str, *args: Any, **kwargs: Any) -> "Import":
         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)
+        return Import(self.url, name, *args, **kwargs)
 
     def __repr__(self) -> str:  # pragma: no cover
-        return f"{type(self).__name__}({self._module!r})"
+        return f"{type(self).__name__}({self.url!r})"
 
 
 class Import:

idom/client/protocol.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+from typing import Union
+
+from typing_extensions import Protocol
+
+from idom import Ref
+
+from . import manage
+
+
+class ClientImplementation(Protocol):
+    """A minimal set of functions required to use :class:`idom.widget.module.Module`"""
+
+    def register_web_module(self, name: str, source: Union[str, Path]) -> None:
+        """Add a module with the given ``name`` to the client using the given ``source``"""
+
+    def web_module_url(self, name: str) -> str:
+        """Return the URL to import the module with the given name."""
+
+    def web_module_exists(self, name: str) -> bool:
+        """Check if a module with the given name is installed"""
+
+
+client_implementation: Ref[ClientImplementation] = Ref(manage)
+"""The current client implementation used by :class:`idom.widgets.module.Module`"""

idom/widgets/__init__.py

@@ -1,14 +1,11 @@
 from .utils import hotswap, multiview
-from .module import Module, Import
 from .html import html, image, Input
 
 __all__ = [
     "node",
     "hotswap",
     "multiview",
     "html",
-    "Module",
-    "Import",
     "image",
     "Input",
 ]

scripts/__init__.py

@@ -5,6 +5,11 @@
 import idom
 from idom.server.sanic import PerClientStateServer
 
+from scripts.install_doc_js_modules import install_doc_js_modules
+
+
+install_doc_js_modules()
+
 here = Path(__file__).parent
 examples_dir = here.parent / "docs" / "source" / "examples"
 sys.path.insert(0, str(examples_dir))

scripts/all_examples.py

@@ -0,0 +1,15 @@
+from idom.client.manage import install, installed
+
+
+def install_doc_js_modules(show_spinner=True):
+    to_install = {
+        "@material-ui/core",
+        "victory",
+        "semantic-ui-react",
+    }.difference(installed())
+    if to_install:
+        install(to_install, [], show_spinner=show_spinner)
+
+
+if __name__ == "__main__":
+    install_doc_js_modules()

scripts/install_doc_js_modules.py

@@ -1,5 +1,6 @@
 set -e
-sphinx-build -b html docs/source docs/build
+python scripts/install_doc_js_modules.py
+sphinx-build -E -b html docs/source docs/build
 cd docs
 python -c "import main; main.local()"
 cd ../

scripts/local-docs.sh

@@ -4,6 +4,11 @@
 from idom.widgets.utils import hotswap
 from idom.server.sanic import PerClientStateServer
 
+from scripts.install_doc_js_modules import install_doc_js_modules
+
+
+install_doc_js_modules()
+
 here = Path(__file__).parent
 examples_dir = here.parent / "docs" / "source" / "examples"
 sys.path.insert(0, str(examples_dir))

scripts/one_example.py

@@ -4,43 +4,50 @@
 
 import pytest
 
-from idom import client
+from idom.client.manage import (
+    install,
+    installed,
+    delete_web_modules,
+    register_web_module,
+    web_module_exists,
+    web_module_url,
+)
 
 
 @pytest.mark.slow
 def test_install():
-    client.delete_web_modules(["jquery"], skip_missing=True)
-    client.install("jquery")
+    delete_web_modules(["jquery"], skip_missing=True)
+    install("jquery")
 
-    assert client.web_module_exists("jquery")
-    assert client.web_module_exists("/jquery")  # works with a leading slash too
-    assert "jquery" in client.installed()
+    assert web_module_exists("jquery")
+    assert web_module_exists("/jquery")  # works with a leading slash too
+    assert "jquery" in installed()
 
     with pytest.raises(ValueError, match="already exists"):
         # can't register a module with the same name
-        client.register_web_module("jquery", Path() / "some-module.js")
+        register_web_module("jquery", Path() / "some-module.js")
 
-    client.delete_web_modules("jquery")
-    assert not client.web_module_exists("jquery")
-    assert "jquery" not in client.installed()
+    delete_web_modules("jquery")
+    assert not web_module_exists("jquery")
+    assert "jquery" not in installed()
 
 
 @pytest.mark.slow
 def test_install_namespace_package():
-    client.install("@material-ui/core")
-    assert client.web_module_exists("@material-ui/core")
+    install("@material-ui/core")
+    assert web_module_exists("@material-ui/core")
     expected = "../web_modules/@material-ui/core.js"
-    assert client.web_module_url("@material-ui/core") == expected
+    assert 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")
+        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")
+        web_module_url("module/that/does/not/exist")
 
 
 called_process_error = CalledProcessError(1, "failing-cmd")
@@ -50,13 +57,13 @@ def test_raise_on_missing_import_path():
 @mock.patch("subprocess.run", side_effect=called_process_error)
 def test_bad_subprocess_call(subprocess_run, caplog):
     with pytest.raises(CalledProcessError):
-        client.install(["victory"])
+        install(["victory"])
     assert "an error occured" in caplog.text
 
 
 def test_cannot_register_module_from_non_existant_source():
     with pytest.raises(ValueError, match="does not exist"):
-        client.register_web_module("my-module", Path() / "a-non-existant-file.js")
+        register_web_module("my-module", Path() / "a-non-existant-file.js")
 
     with pytest.raises(ValueError, match="is not a file"):
-        client.register_web_module("my-module", Path("/"))
+        register_web_module("my-module", Path("/"))

tests/test_client/test_manage.py

@@ -2,8 +2,8 @@
 
 import pytest
 import idom
-from idom import client
-from idom import Module
+from idom.client.manage import install, delete_web_modules
+from idom import Module, client
 
 
 HERE = Path(__file__).parent
@@ -12,7 +12,7 @@
 @pytest.fixture
 def victory():
     if "victory" not in client.installed():
-        client.install(["victory"], [])
+        install(["victory"], [])
     return Module("victory")
 
 
@@ -51,7 +51,7 @@ def test_custom_module(driver, display, victory):
 
     driver.find_element_by_class_name("VictoryContainer")
 
-    client.delete_web_modules("my/chart")
+    delete_web_modules("my/chart")
     assert not client.web_module_exists("my/chart")
 
 
@@ -60,3 +60,7 @@ def test_module_from_url():
     jquery = idom.Module(url)
     assert jquery.url == url
     assert not jquery.installed
+
+
+def test_module_uses_current_client_implementation():
+    assert False