Datalore/Colab: deprecate load_lets_plot_js(), replace it with LetsPlot.setup_html()

- support simple html page output.
- make LetsPlot.setup_html() mandatory.

Author: alshan

python-package/lets_plot/__init__.py

@@ -14,4 +14,21 @@
 
 __all__ = (plot.__all__ +
            frontend_context.__all__ +
-           ['LetsPlotSettings'])
+           ['LetsPlotSettings', 'LetsPlot'])
+
+from .frontend_context import _configuration as cfg
+
+class LetsPlot:
+    @classmethod
+    def setup_html(cls, isolated_frame: bool = None, offline: bool = None) -> None:
+        """
+        Configure HTML frontend context
+        :param settings:
+        :return:
+        """
+        if not (isinstance(isolated_frame, bool) or isolated_frame is None):
+            raise ValueError("'isolated' argument is not boolean: {}".format(type(isolated_frame)))
+        if not (isinstance(offline, bool) or offline is None):
+            raise ValueError("'offline' argument is not boolean: {}".format(type(offline)))
+
+        cfg._setup_html_context(isolated_frame, offline)

python-package/lets_plot/_global_settings.py

@@ -22,15 +22,6 @@ class LetsPlotSettings:
     def apply(cls, settings: Dict):
         _settings.update(settings)
 
-    # @classmethod
-    # def init_frontend(cls, settings=None):
-    #     if settings is None:
-    #         settings = {}
-    #
-    #     LetsPlotSettings.apply(settings)
-    #     # ToDo: inject js to the notebook
-    #     raise NotImplementedError
-
 
 def _is_production() -> bool:
     return 'dev' not in __version__

python-package/lets_plot/frontend_context/__init__.py

@@ -3,6 +3,6 @@
 # Use of this source code is governed by the MIT license that can be found in the LICENSE file.
 #
 
-from .frontend_context import *
+from ._configuration import *
 
-__all__ = frontend_context.__all__
+__all__ = _configuration.__all__

python-package/lets_plot/frontend_context/_configuration.py

@@ -0,0 +1,97 @@
+#
+# Copyright (c) 2019. JetBrains s.r.o.
+# Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from typing import Dict, Any
+
+from ._frontend_ctx import FrontendContext
+from ._html_contexts import _create_html_frontend_context
+from .._global_settings import _get_global_bool
+from ..plot.core import PlotSpec
+from ..plot.plot import GGBunch
+
+__all__ = [
+    'load_lets_plot_js'  # deprecated
+]
+
+_frontend_contexts: Dict[str, FrontendContext] = {}
+_default_mimetype = "text/html"  # Just HTML as yet
+
+
+def _setup_html_context(isolated_frame: bool = None, offline: bool = None) -> None:
+    """
+
+    :param isolated_frame:
+    :param embed:
+    :return:
+    """
+    embed = offline if offline is not None else _get_global_bool('offline')
+    ctx = _create_html_frontend_context(isolated_frame, embed)
+    ctx.configure(verbose=True)
+    _frontend_contexts['html'] = ctx
+
+
+def load_lets_plot_js(embed: bool = None):
+    """
+    Deprecated since v.1.3: instead use LetsPlot.setup_html()
+
+    Loads Lets-Plot javascript library into current frontend context.
+
+    Parameters
+    ----------
+    embed : bool, optional
+        True - embed JS which is bundled with Lets-Plot PyPI package. This is useful for off-line notebooks.
+        False - load JS from CDN.
+        default - load JS from CDN.
+    """
+    try:
+        from IPython.display import display_html
+        display_html("""\
+            <div style="color:darkred;">
+                Method `load_lets_plot_js()` is deprecated since v.1.3 and will be removed soon.<br> 
+                Try to use `LetsPlot.setup_html()` instead.
+            </div>    
+        """, raw=True)
+    except ImportError:
+        pass
+
+    _setup_html_context(None, embed)
+
+
+def _display_plot(plot_spec: Any):
+    """
+    Draw plot or `bunch` of plots in the current frontend context
+    :param plot_spec: PlotSpec or GGBunch object
+    """
+    if not (isinstance(plot_spec, PlotSpec) or isinstance(plot_spec, GGBunch)):
+        raise ValueError("PlotSpec or GGBunch expected but was: {}".format(type(plot_spec)))
+
+    if _default_mimetype == "text/html":
+        plot_html = _as_html(plot_spec.as_dict())
+        try:
+            from IPython.display import display_html
+            display_html(plot_html, raw=True)
+            return
+        except ImportError:
+            pass
+
+        # ToDo: show HTML is brawser window
+        return
+
+    # fallback plain text
+    print(plot_spec.as_dict())
+
+
+def _as_html(plot_spec: Dict) -> str:
+    """
+    :param plot_spec: dict
+    """
+    if 'html' not in _frontend_contexts:
+        return """\
+            <div style="color:darkred;">
+                Lets-plot `html` is not configured.<br> 
+                Try to use `LetsPlot.setup_html()` before first occurrence of plot.
+            </div>    
+            """
+
+    return _frontend_contexts['html'].as_str(plot_spec)

python-package/lets_plot/frontend_context/_frontend_ctx.py

@@ -0,0 +1,13 @@
+#
+# Copyright (c) 2019. JetBrains s.r.o.
+# Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from typing import Dict
+
+
+class FrontendContext:
+    def configure(self, verbose: bool):
+        pass
+
+    def as_str(self, plot_spec: Dict) -> str:
+        pass

python-package/lets_plot/frontend_context/_html_contexts.py

@@ -0,0 +1,71 @@
+#  Copyright (c) 2020. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+import os
+
+from ._frontend_ctx import FrontendContext
+from ._static_html_page_ctx import StaticHtmlPageContext
+from ._jupyter_notebook_ctx import JupyterNotebookContext
+
+
+def _create_html_frontend_context(isolated_frame: bool = None, offline: bool = None) -> FrontendContext:
+    """
+
+    :param isolated_frame:
+    :param offline:
+    :return:
+    """
+    if isolated_frame is None:
+        # ToDo: check env var first
+
+        isolated_frame = _detect_isolated_frame()
+
+    if isolated_frame:
+        return StaticHtmlPageContext(offline)
+    else:
+        return JupyterNotebookContext(offline)
+
+
+def _detect_isolated_frame() -> bool:
+    if not _is_IPython_display():
+        return True  # isolated HTML page to show somehow
+
+    # Most online notebook platforms are showing cell output in iframe and require
+    # a self-contained HTML which includes both:
+    # - the script loading JS library and
+    # - the script that uses this JS lib to create plot.
+
+    # Try to detect the platform.
+    try:
+        import google.colab
+        return True  # Colab -> iframe
+    except ImportError:
+        pass
+
+    if os.path.exists("/kaggle/input"):
+        return True  # Kaggle -> iframe
+
+    # Check if we're running in an Azure Notebook
+    if "AZURE_NOTEBOOKS_HOST" in os.environ:
+        return True  # Azure Notebook -> iframe
+
+    # ToDo: other platforms: vscode, nteract, cocalc
+
+    try:
+        shell = get_ipython().__class__.__name__
+        if shell == 'ZMQInteractiveShell':
+            return False  # Jupyter notebook or qtconsole  -> load JS librarty once per notebook
+        elif shell == 'TerminalInteractiveShell':
+            return True  # Terminal running IPython  -> an isolated HTML page to show somehow
+        else:
+            return True  # Other type (?)
+    except NameError:
+        return True  # some other env (even standard Python interpreter) ->  an isolated HTML page to show somehow
+
+
+def _is_IPython_display() -> bool:
+    try:
+        from IPython.display import display_html
+        return True
+    except ImportError:
+        return False

python-package/lets_plot/frontend_context/jupyter_notebook.py renamed to python-package/lets_plot/frontend_context/_jupyter_notebook_ctx.py

@@ -11,23 +11,17 @@
 # noinspection PyPackageRequirements
 from IPython.display import display_html
 
-from .frontend_context import FrontendContext
-from .._global_settings import _get_global_str, _has_global_value, _is_production
+from ._frontend_ctx import FrontendContext
 from .. import _kbridge as kbr
+from .._global_settings import _get_global_str, _has_global_value, _is_production
 from .._version import __version__
 
 
 class JupyterNotebookContext(FrontendContext):
 
-    def __init__(self, connected: bool) -> None:
+    def __init__(self, offline: bool) -> None:
         super().__init__()
-        self.connected = connected
-
-    def as_str(self, plot_spec: Dict) -> str:
-        return kbr._generate_dynamic_display_html(plot_spec)
-
-    def _undef_modules_script(self) -> str:
-        pass
+        self.connected = not offline
 
     def configure(self, verbose: bool):
         if self.connected:
@@ -37,6 +31,9 @@ def configure(self, verbose: bool):
             # noinspection PyTypeChecker
             display_html(self._configure_embedded_script(verbose), raw=True)
 
+    def as_str(self, plot_spec: Dict) -> str:
+        return kbr._generate_dynamic_display_html(plot_spec)
+
     @staticmethod
     def _configure_connected_script(verbose: bool) -> str:
         base_url = _get_global_str("js_base_url")

python-package/lets_plot/frontend_context/_static_html_page_ctx.py

@@ -0,0 +1,31 @@
+#
+# Copyright (c) 2019. JetBrains s.r.o.
+# Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from typing import Dict
+
+from ._frontend_ctx import FrontendContext
+from .. import _kbridge as kbr
+from .._global_settings import _is_production
+from .._version import __version__
+
+
+# noinspection PyPackageRequirements
+
+
+class StaticHtmlPageContext(FrontendContext):
+
+    def __init__(self, offline: bool) -> None:
+        super().__init__()
+        self.connected = not offline
+
+    def configure(self, verbose: bool):
+        # Nothing here because the entire html page is created per each cell output.
+        if not self.connected:
+            print("WARN: Embedding Lets-Plot JS library for offline usage is not supported.")
+
+    def as_str(self, plot_spec: Dict) -> str:
+        # embedding js is not supported (yet) in this context,
+        # replace `dev` version with the `latest`.
+        version = __version__ if _is_production() else "latest"
+        return kbr._generate_static_html_page(plot_spec, version, iframe=False)

python-package/lets_plot/frontend_context/frontend_context.py

@@ -237,14 +237,14 @@ def _repr_html_(self):
         """
         Special method discovered and invoked by IPython.display.display
         """
-        from ..frontend_context.frontend_context import _as_html
+        from ..frontend_context._configuration import _as_html
         return _as_html(self.as_dict())
 
     def show(self):
         """
         Draw plot
         """
-        from ..frontend_context.frontend_context import _display_plot
+        from ..frontend_context._configuration import _display_plot
         _display_plot(self)