lets-plot 4.8.1rc1__cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

lets_plot/export/ggsave_.py

@@ -0,0 +1,172 @@
+#  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 os.path import join
+from typing import Union, Optional
+
+from ..plot.core import PlotSpec
+from ..plot.core import _to_svg, _to_html, _to_mvg, _export_as_raster
+from ..plot.plot import GGBunch
+from ..plot.subplots import SupPlotsSpec
+
+__all__ = ['ggsave']
+
+_DEF_EXPORT_DIR = "lets-plot-images"
+
+
+def ggsave(plot: Union[PlotSpec, SupPlotsSpec, GGBunch], filename: str, *, path: str = None, iframe: bool = True,
+           scale: float = None, w: Optional[float] = None, h: Optional[float] = None, unit: Optional[str] = None,
+           dpi: Optional[int] = None) -> str:
+    """
+    Export plot to a file.
+    Supported formats: PNG, SVG, PDF, HTML.
+
+    The exported file is created in the directory ${user.dir}/lets-plot-images
+    if not specified otherwise (see the ``path`` parameter).
+
+    Parameters
+    ----------
+    plot : ``PlotSpec``
+        Plot specification to export.
+    filename : str
+        Name of the file. It must end with a file extension corresponding
+        to one of the supported formats: SVG, HTML (or HTM), PNG, PDF (requires the pillow library).
+    path : str
+        Path to a directory to save image files in.
+        By default, it is ${user.dir}/lets-plot-images.
+    iframe : bool, default=True
+        Whether to wrap the HTML page into an iFrame.
+        Only applicable when exporting to HTML.
+        Some browsers may not display some UTF-8 characters correctly when setting iframe=True
+    scale : float, default=2.0
+        Scaling factor for raster output.
+        Only applicable when exporting to PNG or PDF.
+    w : float, default=None
+        Width of the output image in units.
+        Only applicable when exporting to SVG, PNG, or PDF.
+    h : float, default=None
+        Height of the output image in units.
+        Only applicable when exporting to SVG, PNG, or PDF.
+    unit : {'in', 'cm', 'mm', 'px'}, default='in'
+        Unit of the output image. One of: 'in', 'cm', 'mm' or 'px'.
+        Only applicable when exporting to SVG, PNG, or PDF.
+    dpi : int, default=300
+        Resolution in dots per inch.
+        Only applicable when exporting to PNG or PDF.
+        The default value depends on the unit:
+
+        - for 'px' it is 96 (output image will have the same pixel size as ``w``, and ``h`` values)
+        - for physical units ('in', 'cm', 'mm') it is 300.
+
+    Returns
+    -------
+    str
+        Absolute pathname of the created file.
+
+    Notes
+    -----
+    Large plot dimensions without units require explicit unit specification.
+    When ``w`` or ``h`` value exceeds 20 without specifying units (e.g., ``ggsave(p, 300, 400)``),
+    we ask to specify units explicitly:
+    ``ggsave(p, 300, 400, unit='px')`` or ``ggsave(p, 3, 4, unit='in')``.
+
+    ----
+
+    The output format is inferred from the filename extension.
+
+    For PNG, and PDF formats:
+
+    - If ``w``, ``h``, ``unit``, and ``dpi`` are all specified:
+
+      - The plot's pixel size (default or set by `ggsize() <https://lets-plot.org/python/pages/api/lets_plot.ggsize.html>`__) is ignored.
+      - The output size is calculated using the specified ``w``, ``h``, ``unit`` and ``dpi``.
+
+        - The plot is resized to fit the specified ``w`` x ``h`` area, which may affect the layout, tick labels, and other elements.
+
+    - If only ``dpi`` is specified:
+
+      - The plot's pixel size (default or set by `ggsize() <https://lets-plot.org/python/pages/api/lets_plot.ggsize.html>`__) is converted to inches using the standard display PPI of 96.
+      - The output size is then calculated based on the specified DPI.
+
+        - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+        - Useful for printing - the plot will appear nearly the same size as on screen.
+
+    - If ``w``, ``h`` are not specified:
+
+      - The ``scale`` parameter is used to determine the output size.
+
+        - The plot maintains its aspect ratio, preserving layout, tick labels, and other visual elements.
+        - Useful for generating high-resolution images suitable for publication.
+
+    For SVG format:
+
+    - If ``w``, ``h``, and ``unit`` are specified:
+
+      - The plot's pixel size (default or set by `ggsize() <https://lets-plot.org/python/pages/api/lets_plot.ggsize.html>`__) is ignored.
+      - The output size is calculated using the specified ``w``, ``h``, and ``unit``.
+
+    ----
+
+    Plots with ``geom_livemap()`` can be saved to HTML only.
+
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 6
+
+        from IPython.display import Image
+        from lets_plot import *
+        LetsPlot.setup_html()
+        filename = 'plot.png'
+        plot = ggplot() + geom_point(x=0, y=0) + ggtitle(filename)
+        fullpath = ggsave(plot, filename, w=4, h=3)
+        Image(filename=fullpath, width=600, height=450)
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 6
+
+        from IPython.display import HTML
+        from lets_plot import *
+        LetsPlot.setup_html()
+        filename = 'plot.html'
+        plot = ggplot() + geom_point(x=0, y=0) + ggtitle(filename)
+        fullpath = ggsave(plot, filename, iframe=False)
+        HTML(filename=fullpath)
+
+    """
+
+    if not (isinstance(plot, PlotSpec) or isinstance(plot, SupPlotsSpec) or isinstance(plot, GGBunch)):
+        raise ValueError("PlotSpec, SupPlotsSpec or GGBunch expected but was: {}".format(type(plot)))
+
+    filename = filename.strip()
+    name, ext = os.path.splitext(filename)
+
+    if not name:
+        raise ValueError("Malformed filename: '{}'.".format(filename))
+    if not ext:
+        raise ValueError("Missing file extension: '{}'.".format(filename))
+
+    if not path:
+        path = join(os.getcwd(), _DEF_EXPORT_DIR)
+
+    pathname = join(path, filename)
+
+    ext = ext[1:].lower()
+    if ext == 'svg':
+        return _to_svg(plot, pathname, w=w, h=h, unit=unit)
+    elif ext in ['html', 'htm']:
+        return _to_html(plot, pathname, iframe=iframe)
+    elif ext in ['png', 'pdf']:
+        return _export_as_raster(plot, pathname, scale, export_format=ext, w=w, h=h, unit=unit, dpi=dpi)
+    elif ext == 'mvg':
+        return _to_mvg(plot, pathname, scale, w=w, h=h, unit=unit, dpi=dpi)
+    else:
+        raise ValueError(
+            "Unsupported file extension: '{}'\nPlease use one of: 'png', 'svg', 'pdf', 'html', 'htm'".format(ext)
+        )

lets_plot/frontend_context/__init__.py

@@ -0,0 +1,8 @@
+#
+# 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 ._configuration import *
+
+__all__ = _configuration.__all__

lets_plot/frontend_context/_configuration.py

@@ -0,0 +1,140 @@
+#
+# 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, _create_wb_html_frontend_context
+from ._json_contexts import _create_json_frontend_context, _is_Intellij_Python_Lets_Plot_Plugin
+from ._mime_types import TEXT_HTML, LETS_PLOT_JSON
+from ._static_svg_ctx import StaticSvgImageContext
+from ._webbr_html_page_ctx import WebBrHtmlPageContext
+from .._version import __version__
+from ..plot.core import PlotSpec
+from ..plot.plot import GGBunch
+from ..plot.subplots import SupPlotsSpec
+
+__all__ = []
+
+_frontend_contexts: Dict[str, FrontendContext] = {}
+
+_default_mimetype = TEXT_HTML
+if _is_Intellij_Python_Lets_Plot_Plugin():
+    _default_mimetype = LETS_PLOT_JSON
+    _frontend_contexts[LETS_PLOT_JSON] = _create_json_frontend_context()
+
+
+def _setup_html_context(*,
+                        isolated_frame: bool = None,
+                        offline: bool,
+                        no_js: bool,
+                        show_status: bool,
+                        dev_options: Dict = None) -> None:
+    """
+    Configures Lets-Plot HTML output.
+    See the docstring in `setup_html()` for details on parameters.
+    """
+    global _default_mimetype
+    if _default_mimetype == LETS_PLOT_JSON:
+        # Plots will be rendered by Lets-Plot IntelliJ plugin.
+        # But still create HTML context in case it's necessary.
+        if show_status:
+            print(
+                'Lets-Plot v{}: output mimetype {} configured by default. No need for HTML output.'.format(__version__,
+                                                                                                           LETS_PLOT_JSON))
+
+    if no_js:
+        ctx = StaticSvgImageContext()
+    else:
+        ctx = _create_html_frontend_context(isolated_frame, offline=offline, dev_options=dev_options)
+
+    ctx.configure(verbose=show_status)
+    _frontend_contexts[TEXT_HTML] = ctx
+
+
+def _setup_wb_html_context(*,
+                           exec: str,
+                           new: bool) -> None:
+    """
+    Configures Lets-Plot HTML output for showing in a browser.
+
+    Parameters
+    ----------
+    exec : str, optional
+        Command to execute to open the plot in a web browser.
+        If not specified, the default browser will be used.
+    new : bool, default=False
+        If True, the URL is opened in a new window of the web browser.
+        If False, the URL is opened in the already opened web browser window.
+    """
+    ctx = _create_wb_html_frontend_context(exec, new)
+    _frontend_contexts[TEXT_HTML] = ctx
+
+
+def _display_plot(spec: Any):
+    """
+    Draw plot or `bunch` of plots in the current frontend context
+    :param spec: PlotSpec or GGBunch object
+    """
+    if not (isinstance(spec, PlotSpec) or isinstance(spec, SupPlotsSpec) or isinstance(spec, GGBunch)):
+        raise ValueError("PlotSpec or SupPlotsSpec expected but was: {}".format(type(spec)))
+
+    if _default_mimetype == TEXT_HTML:
+        ctx = _frontend_contexts.get(TEXT_HTML)
+
+        if ctx is not None and isinstance(ctx, WebBrHtmlPageContext):
+            ctx.show(spec.as_dict())
+            return
+
+        # If ctx is None, _as_html() will try to initialize the context lazily
+        plot_html = _as_html(spec.as_dict())
+        try:
+            from IPython.display import display_html
+            display_html(plot_html, raw=True)
+            return
+        except ImportError:
+            pass
+
+        print(spec.as_dict())
+        return
+
+    if _default_mimetype == LETS_PLOT_JSON:
+        _frontend_contexts[LETS_PLOT_JSON].show(spec.as_dict())
+        return
+
+    # fallback to plain text.
+    print(spec.as_dict())
+
+
+def _as_html(plot_spec: Dict) -> str:
+    """
+    Creates plot HTML using 'html' frontend context.
+
+    :param plot_spec: dict
+    """
+    ctx = _frontend_contexts.get(TEXT_HTML)
+
+    if ctx is None:
+        # Set up HTML context lazily
+        _setup_html_context(isolated_frame=None,
+                            offline=False,
+                            no_js=False,
+                            show_status=False)
+
+        ctx = _frontend_contexts[TEXT_HTML]
+
+        # Check if this context allows lazy set-up.
+        requires_configure = getattr(ctx, 'requires_configure', False)
+        if requires_configure:
+            # Clear the context and return an error message
+            _frontend_contexts[TEXT_HTML] = None
+            return """\
+            <div style="color:darkred;">
+                Lets-plot `html` is not configured.<br>
+                Try to use `LetsPlot.setup_html()` before first occurrence of plot.
+            </div>
+            """
+
+    # Generate "display" HTML
+    return ctx.as_str(plot_spec)

lets_plot/frontend_context/_dynamic_configure_html.py

@@ -0,0 +1,115 @@
+#
+# Copyright (c) 2025. 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
+import pkgutil
+import random
+import string
+
+from .._global_settings import get_js_cdn_url
+
+# Data-attributes used to store extra information about the meaning of 'script' elements
+_ATT_SCRIPT_KIND = 'data-lets-plot-script'
+_SCRIPT_KIND_LIB_LOADING = 'library'
+
+
+def generate_dynamic_configure_html(offline: bool, verbose: bool) -> str:
+    """
+    Generate HTML for dynamic loading of lets-plot.js library.
+
+    Parameters
+    ----------
+    offline : bool
+        If True, embeds the JS library directly. If False, loads from CDN.
+    verbose : bool
+        If True, shows success/error messages to the user.
+
+    Returns
+    -------
+    str
+        HTML string that loads the lets-plot.js library and sets up the dynamic loading mechanism.
+    """
+    if offline:
+        return _configure_embedded_script(verbose)
+    else:
+        return _configure_connected_script(verbose)
+
+
+def _configure_connected_script(verbose: bool) -> str:
+    """Generate HTML that loads lets-plot.js from CDN."""
+    url = get_js_cdn_url()
+    output_id = _rand_string()
+    success_message = """
+        var div = document.createElement("div");
+        div.style.color = 'darkblue';
+        div.textContent = 'Lets-Plot JS successfully loaded.';
+        document.getElementById("{id}").appendChild(div);
+    """.format(id=output_id) if verbose else ""
+
+    return """
+        <div id="{id}"></div>
+        <script type="text/javascript" {data_attr}="{script_kind}">
+            if(!window.letsPlotCallQueue) {{
+                window.letsPlotCallQueue = [];
+            }};
+            window.letsPlotCall = function(f) {{
+                window.letsPlotCallQueue.push(f);
+            }};
+            (function() {{
+                var script = document.createElement("script");
+                script.type = "text/javascript";
+                script.src = "{url}";
+                script.onload = function() {{
+                    window.letsPlotCall = function(f) {{f();}};
+                    window.letsPlotCallQueue.forEach(function(f) {{f();}});
+                    window.letsPlotCallQueue = [];
+                    {success_message}
+                }};
+                script.onerror = function(event) {{
+                    window.letsPlotCall = function(f) {{}};    // noop
+                    window.letsPlotCallQueue = [];
+                    var div = document.createElement("div");
+                    div.style.color = 'darkred';
+                    div.textContent = 'Error loading Lets-Plot JS';
+                    document.getElementById("{id}").appendChild(div);
+                }};
+                var e = document.getElementById("{id}");
+                e.appendChild(script);
+            }})()
+        </script>
+        """.format(
+        data_attr=_ATT_SCRIPT_KIND,
+        script_kind=_SCRIPT_KIND_LIB_LOADING,
+        id=output_id,
+        url=url,
+        success_message=success_message)
+
+
+def _configure_embedded_script(verbose: bool) -> str:
+    """Generate HTML that embeds lets-plot.js directly."""
+    js_name = "lets-plot.min.js"
+    path = os.path.join("package_data", js_name)
+    js_code = pkgutil.get_data("lets_plot", path).decode("utf-8")
+    success_message = '<div style="color:darkblue;">Lets-Plot JS is embedded.</div>' if verbose else ""
+
+    return """
+        <script type="text/javascript" {data_attr}="{script_kind}">
+            window.letsPlotCall = function(f) {{f();}};
+            console.log('Embedding: {js_name}');
+            {js_code}
+        </script>
+        {success_message}
+        """.format(
+        data_attr=_ATT_SCRIPT_KIND,
+        script_kind=_SCRIPT_KIND_LIB_LOADING,
+        js_code=js_code,
+        js_name=js_name,
+        success_message=success_message)
+
+
+def _rand_string(size=6) -> str:
+    """Generate a random string for unique element IDs."""
+    alphabet = string.ascii_letters + string.digits
+    # noinspection PyShadowingBuiltins
+    return ''.join([random.choice(alphabet) for _ in range(size)])

lets_plot/frontend_context/_frontend_ctx.py

@@ -0,0 +1,16 @@
+#
+# 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
+
+    def show(self, plot_spec: Dict) -> str:
+        pass

lets_plot/frontend_context/_html_contexts.py

@@ -0,0 +1,223 @@
+#  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 ._isolated_webview_panel_ctx import IsolatedWebviewPanelContext
+from ._jupyter_notebook_ctx import JupyterNotebookContext
+from ._static_html_page_ctx import StaticHtmlPageContext
+from ._webbr_html_page_ctx import WebBrHtmlPageContext
+from .._global_settings import has_global_value, get_global_bool, HTML_ISOLATED_FRAME
+
+
+def _create_html_frontend_context(
+        isolated_frame: bool = None,
+        offline: bool = None,
+        dev_options: dict = None) -> FrontendContext:
+    """
+    Configures Lets-Plot HTML output.
+    See the docstring in `setup_html()` for details on parameters.
+    """
+
+    if dev_options is None:
+        dev_options = {}
+    else:
+        dev_options = dev_options.copy()
+
+    # Extract and remove isolated_webview_panel from dev_options
+    isolated_webview_panel = dev_options.pop('isolated_webview_panel', None)
+
+    if isolated_webview_panel is None:
+        isolated_webview_panel = _is_positron_console()
+
+    if isolated_webview_panel:
+        return IsolatedWebviewPanelContext(offline, **dev_options)
+
+    if isolated_frame is None:
+        isolated_frame = _use_isolated_frame()
+
+    if isolated_frame:
+        return StaticHtmlPageContext(offline, **dev_options)
+    else:
+        return JupyterNotebookContext(offline, **dev_options)
+
+
+def _create_wb_html_frontend_context(exec: str, new: bool) -> FrontendContext:
+    """
+    Configures Lets-Plot HTML output for showing in a web browser.
+
+    Parameters
+    ----------
+    exec : str, optional
+        The name of the web browser to use.
+        If not specified, the default browser will be used.
+    new : bool, default=False
+        If True, the URL is opened in a new window of the web browser.
+        If False, the URL is opened in the already opened web browser window.
+    """
+    return WebBrHtmlPageContext(exec, new)
+
+
+def _use_isolated_frame() -> bool:
+    # check environment
+    if has_global_value(HTML_ISOLATED_FRAME):
+        return get_global_bool(HTML_ISOLATED_FRAME)
+
+    # return _detect_isolated_frame()
+    if not _is_IPython_display():
+        return True  # fallback to a complete HTML page in the output
+
+    # Some notebooks behave like a single HTML page where the JS library is loaded once per notebook.
+    if (_is_jupyter_classic() or
+            _is_kaggle() or
+            _is_positron_notebook()):
+        return False  # no iframes in the output cell
+
+    # Most online notebook platforms are showing cell output in iframe and require
+    # a complete HTML page in the output which includes both:
+    # - the script loading JS library and
+    # - the script that uses this JS lib to create a plot.
+
+    if (_is_google_colab() or
+            _is_azure_notebook() or
+            _is_deepnote() or
+            _is_databricks() or
+            _is_nextjournal()
+    ):
+        return True  # complete HTML page in the output
+
+    # if os.getenv("PLOTLY_RENDERER") == "colab":
+    #     # good enough - something colab-like
+    #     return True  # Colab -> iframe
+
+    # 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
+
+    # Fallback to a complete HTML page in the output
+    return True
+
+
+# def _detect_isolated_frame() -> bool:
+#     if not _is_IPython_display():
+#         return True  # fallback to a complete HTML page in the output
+#
+#     # Some notebooks behave like a single HTML page where the JS library is loaded once per notebook.
+#     if (_is_jupyter_classic() or
+#             _is_kaggle() or
+#             _is_positron_notebook()):
+#         return False  # no iframes in the output cell
+#
+#     # Most online notebook platforms are showing cell output in iframe and require
+#     # a complete HTML page in the output which includes both:
+#     # - the script loading JS library and
+#     # - the script that uses this JS lib to create a plot.
+#
+#     if (_is_google_colab() or
+#             _is_azure_notebook() or
+#             _is_deepnote() or
+#             _is_databricks() or
+#             _is_nextjournal()
+#     ):
+#         return True  # complete HTML page in the output
+#
+#     # if os.getenv("PLOTLY_RENDERER") == "colab":
+#     #     # good enough - something colab-like
+#     #     return True  # Colab -> iframe
+#
+#     # 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
+#
+#     # Fallback to a complete HTML page in the output
+#     return True
+
+
+def _is_IPython_display() -> bool:
+    try:
+        from IPython.display import display_html
+        return True
+    except ImportError:
+        return False
+
+
+def _is_jupyter_classic() -> bool:
+    # This also detects JupyterLab, which uses the same ZMQInteractiveShell
+    # and also qtconsole (allegedly)
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    shell = get_ipython()
+    try:
+        return shell is not None and shell.__class__.__name__ == "ZMQInteractiveShell"
+    except AttributeError:
+        return False
+
+
+def _is_google_colab() -> bool:
+    try:
+        import google.colab
+        return True
+    except ImportError:
+        return False
+
+
+def _is_kaggle() -> bool:
+    return os.path.exists("/kaggle/input")
+
+
+def _is_azure_notebook() -> bool:
+    return "AZURE_NOTEBOOKS_HOST" in os.environ
+
+
+def _is_deepnote() -> bool:
+    return "DEEPNOTE_PROJECT_ID" in os.environ
+
+
+def _is_databricks() -> bool:
+    # As proposed: https://github.com/JetBrains/lets-plot/issues/602
+    return "databricks" in str(os.environ)
+
+
+def _is_nextjournal() -> bool:
+    return "NEXTJOURNAL" in str(os.environ)
+
+
+def _is_positron_console():
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    shell = get_ipython()
+    try:
+        return shell is not None and shell.session_mode == "console"
+    except AttributeError:
+        return False
+
+
+def _is_positron_notebook():
+    try:
+        from IPython import get_ipython
+    except ImportError:
+        return False
+    shell = get_ipython()
+    try:
+        return shell is not None and shell.session_mode == "notebook"
+    except AttributeError:
+        return False