Merge pull request #5677 from plotly/drop-kaleido-v0

Drop support for Kaleido v0.x, and Orca

Author: emilykl

.github/workflows/run-pytest.yml

@@ -135,7 +135,7 @@ jobs:
           python -m pytest -x test_init/test_lazy_imports.py
 
   test-kaleido-v0:
-    name: Optional tests (Kaleido only), Kaleido v0 (Python 3.12, kaleido 0.2.1)
+    name: Kaleido v0 RuntimeError verification (Python 3.12, kaleido 0.2.1)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
@@ -157,7 +157,7 @@ jobs:
           uv pip uninstall kaleido
           uv pip install kaleido==0.2.1
           python --version
-      - name: Test plotly.io image output with Kaleido v0
+      - name: Test that plotly.io raises correct error with Kaleido v0
         run: |
           source .venv/bin/activate
-          python -m pytest tests/test_optional/test_kaleido
+          python -m pytest tests/test_optional/test_kaleido/test_kaleido_v0_error.py

.gitignore

@@ -1,7 +1,6 @@
 0
 0.html
 iframe_figures/
-tests/test_orca/images/linux/failed/
 
 *.egg-info
 
@@ -49,8 +48,6 @@ plotly.egg-info/
 # macOS utility file
 **/.DS_Store
 
-tests/test_orca/images/*/failed
-tests/test_orca/images/*/tmp
 tests/test_core/test_offline/plotly.min.js
 temp-plot.html
 .vscode

CHANGELOG.md

@@ -6,6 +6,9 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Removed
 - Remove the deprecated Figure Factory functions `create_2d_density`, `create_annotated_heatmap`, `create_bullet`, `create_candlestick`, `create_choropleth`, `create_distplot`, `create_facet_grid`, `create_gantt`, `create_hexbin_mapbox`, `create_ohlc`, `create_scatterplotmatrix`, and `create_violin` [[#5627](https://github.com/plotly/plotly.py/pull/5627)]
+- Remove support for Kaleido versions less than v1.0.0 for static image generation [[#5677](https://github.com/plotly/plotly.py/pull/5677)]
+- Remove support for Orca for static image generation [[#5677](https://github.com/plotly/plotly.py/pull/5677)]
+- Remove `engine` argument from functions `fig.write_image()`,`fig.to_image()`, `pio.write_image()`, `pio.write_images()`, `pio.to_image()`, `pio.full_figure_for_development()`, and from renderer constructors [[#5677](https://github.com/plotly/plotly.py/pull/5677)]
 
 ### Fixed
 - Raise a clear `ValueError` when an unsupported marginal plot type is passed to Plotly Express, instead of failing later with a cryptic `'NoneType' object has no attribute 'constructor'` message [[#5625](https://github.com/plotly/plotly.py/pull/5625)], with thanks to @eugen-goebel for the contribution!

README.md

@@ -106,13 +106,10 @@ conda install jupyter anywidget
 ### Static Image Export
 
 plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
-using either the [`kaleido`](https://github.com/plotly/Kaleido)
-package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca)
-command line utility (legacy as of `plotly` version 4.9).
+using the [`kaleido`](https://github.com/plotly/Kaleido)
+package (version 1.0 or greater).
 
-#### Kaleido
-
-The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
+Kaleido has minimal dependencies and can be installed
 using pip
 
 ```
@@ -125,6 +122,12 @@ or conda
 conda install -c conda-forge python-kaleido
 ```
 
+Kaleido requires Chrome or Chromium to generate images. By default, Kaleido will use the Chrome or Chromium version already installed on your system. If you don't have it installed or Kaleido can't find it, you may need to install it by running the command:
+
+`plotly_get_chrome`
+
+on your command line.
+
 ## Copyright and Licenses
 
 Code and documentation copyright 2019 Plotly, Inc.

plotly/basedatatypes.py

@@ -3462,9 +3462,6 @@ def full_figure_for_development(self, warn=True, as_dict=False):
 
         Parameters
         ----------
-        fig:
-            Figure object or dict representing a figure
-
         warn: bool
             If False, suppress warnings about not using this in production.
 
@@ -3717,86 +3714,43 @@ def to_image(self, *args, **kwargs):
 
         Parameters
         ----------
-        format: str or None
-            The desired image format. One of
-              - 'png'
-              - 'jpg' or 'jpeg'
-              - 'webp'
-              - 'svg'
-              - 'pdf'
-              - 'eps' (deprecated) (Requires the poppler library to be installed)
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_format` if engine is "kaleido"
-                - `plotly.io.orca.config.default_format` if engine is "orca" (deprecated)
-
-        width: int or None
-            The width of the exported image in layout pixels. If the `scale`
-            property is 1.0, this will also be the width of the exported image
-            in physical pixels.
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_width` if engine is "kaleido"
-                - `plotly.io.orca.config.default_width` if engine is "orca" (deprecated)
-
-        height: int or None
-            The height of the exported image in layout pixels. If the `scale`
-            property is 1.0, this will also be the height of the exported image
-            in physical pixels.
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_height` if engine is "kaleido"
-                - `plotly.io.orca.config.default_height` if engine is "orca" (deprecated)
-
-        scale: int or float or None
-            The scale factor to use when exporting the figure. A scale factor
-            larger than 1.0 will increase the image resolution with respect
-            to the figure's layout pixel dimensions. Whereas as scale factor of
-            less than 1.0 will decrease the image resolution.
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_scale` if engine is "kaliedo"
-                - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated)
+        format: str
+            (optional) The desired image format. One of:
+                - 'png'
+                - 'jpg' or 'jpeg'
+                - 'webp'
+                - 'svg'
+                - 'pdf'
+            Defaults to `plotly.io.defaults.default_format`.
+
+        width: int
+            (optional) The width of the exported image in layout pixels. If the
+            `scale` property is 1.0, this will also be the width of the exported image
+            in physical pixels. Defaults to `plotly.io.defaults.default_width`.
+
+        height: int
+            (optional) The height of the exported image in layout pixels. If the
+            `scale` property is 1.0, this will also be the height of the exported image
+            in physical pixels. Defaults to `plotly.io.defaults.default_height`.
+
+        scale: int or float
+            (optional) The scale factor to use when exporting the figure. A scale
+            factor larger than 1.0 will increase the image resolution with respect
+            to the figure's layout pixel dimensions, while a scale factor of
+            less than 1.0 will decrease the image resolution. Defaults to
+            `plotly.io.defaults.default_scale`.
 
         validate: bool
-            True if the figure should be validated before being converted to
-            an image, False otherwise.
-
-        engine (deprecated): str
-            Image export engine to use. This parameter is deprecated and Orca engine support will be
-            dropped in the next major Plotly version. Until then, the following values are supported:
-            - "kaleido": Use Kaleido for image export
-            - "orca": Use Orca for image export
-            - "auto" (default): Use Kaleido if installed, otherwise use Orca
+            (optional) True if the figure should be validated before being converted
+            to an image, False otherwise. Defaults to True.
 
         Returns
         -------
         bytes
             The image data
         """
-        import plotly.io as pio
-        from plotly.io.kaleido import (
-            kaleido_available,
-            kaleido_major,
-            ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS,
-            KALEIDO_DEPRECATION_MSG,
-            ORCA_DEPRECATION_MSG,
-            ENGINE_PARAM_DEPRECATION_MSG,
-        )
 
-        if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS:
-            if (
-                kwargs.get("engine", None) in {None, "auto", "kaleido"}
-                and kaleido_available()
-                and kaleido_major() < 1
-            ):
-                warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
-            if kwargs.get("engine", None) == "orca":
-                warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
-            if kwargs.get("engine", None):
-                warnings.warn(
-                    ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2
-                )
+        import plotly.io as pio
 
         return pio.to_image(self, *args, **kwargs)
 
@@ -3811,87 +3765,43 @@ def write_image(self, *args, **kwargs):
             A string representing a local file path or a writeable object
             (e.g. a pathlib.Path object or an open file descriptor)
 
-        format: str or None
-            The desired image format. One of
-              - 'png'
-              - 'jpg' or 'jpeg'
-              - 'webp'
-              - 'svg'
-              - 'pdf'
-              - 'eps' (deprecated) (Requires the poppler library to be installed)
-
-            If not specified and `file` is a string then this will default to the
-            file extension. If not specified and `file` is not a string then this
-            will default to:
-                - `plotly.io.defaults.default_format` if engine is "kaleido"
-                - `plotly.io.orca.config.default_format` if engine is "orca" (deprecated)
-
-        width: int or None
-            The width of the exported image in layout pixels. If the `scale`
-            property is 1.0, this will also be the width of the exported image
-            in physical pixels.
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_width` if engine is "kaleido"
-                - `plotly.io.orca.config.default_width` if engine is "orca" (deprecated)
-
-        height: int or None
-            The height of the exported image in layout pixels. If the `scale`
-            property is 1.0, this will also be the height of the exported image
-            in physical pixels.
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_height` if engine is "kaleido"
-                - `plotly.io.orca.config.default_height` if engine is "orca" (deprecated)
-
-        scale: int or float or None
-            The scale factor to use when exporting the figure. A scale factor
-            larger than 1.0 will increase the image resolution with respect
-            to the figure's layout pixel dimensions. Whereas as scale factor of
-            less than 1.0 will decrease the image resolution.
-
-            If not specified, will default to:
-                - `plotly.io.defaults.default_scale` if engine is "kaleido"
-                - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated)
+        format: str
+            (optional) The desired image format. One of:
+            - 'png'
+            - 'jpg' or 'jpeg'
+            - 'webp'
+            - 'svg'
+            - 'pdf'
+            Defaults to the file extension of `file`, if given; otherwise
+            defaults to `plotly.io.defaults.default_format`.
+
+        width: int
+            (optional) The width of the exported image in layout pixels. If the
+            `scale` property is 1.0, this will also be the width of the exported image
+            in physical pixels. Defaults to `plotly.io.defaults.default_width`.
+
+        height: int
+            (optional) The height of the exported image in layout pixels. If the
+            `scale` property is 1.0, this will also be the height of the exported image
+            in physical pixels. Defaults to `plotly.io.defaults.default_height`.
+
+        scale: int or float
+            (optional) The scale factor to use when exporting the figure. A scale
+            factor larger than 1.0 will increase the image resolution with respect
+            to the figure's layout pixel dimensions, while a scale factor of
+            less than 1.0 will decrease the image resolution. Defaults to
+            `plotly.io.defaults.default_scale`.
 
         validate: bool
-            True if the figure should be validated before being converted to
-            an image, False otherwise.
-
-        engine (deprecated): str
-            Image export engine to use. This parameter is deprecated and Orca engine support will be
-            dropped in the next major Plotly version. Until then, the following values are supported:
-            - "kaleido": Use Kaleido for image export
-            - "orca": Use Orca for image export
-            - "auto" (default): Use Kaleido if installed, otherwise use Orca
+            (optional) True if the figure should be validated before being converted
+            to an image, False otherwise. Defaults to True.
 
         Returns
         -------
         None
         """
         import plotly.io as pio
-        from plotly.io.kaleido import (
-            kaleido_available,
-            kaleido_major,
-            ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS,
-            KALEIDO_DEPRECATION_MSG,
-            ORCA_DEPRECATION_MSG,
-            ENGINE_PARAM_DEPRECATION_MSG,
-        )
 
-        if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS:
-            if (
-                kwargs.get("engine", None) in {None, "auto", "kaleido"}
-                and kaleido_available()
-                and kaleido_major() < 1
-            ):
-                warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
-            if kwargs.get("engine", None) == "orca":
-                warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2)
-            if kwargs.get("engine", None):
-                warnings.warn(
-                    ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2
-                )
         return pio.write_image(self, *args, **kwargs)
 
     # Static helpers

plotly/io/__init__.py

@@ -10,7 +10,6 @@
         write_images,
         full_figure_for_development,
     )
-    from . import orca, kaleido
     from . import json
     from ._json import to_json, from_json, read_json, write_json
     from ._templates import templates, to_templated
@@ -23,7 +22,6 @@
         "to_image",
         "write_image",
         "write_images",
-        "orca",
         "json",
         "to_json",
         "from_json",
@@ -43,7 +41,7 @@
 else:
     __all__, __getattr__, __dir__ = relative_import(
         __name__,
-        [".orca", ".kaleido", ".json", ".base_renderers"],
+        [".kaleido", ".json", ".base_renderers"],
         [
             "._kaleido.to_image",
             "._kaleido.write_image",