diff --git a/CHANGELOG.md b/CHANGELOG.md index 267487cd12..b14a7d6802 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). +## Unreleased + +- Add deprecation warnings when using Kaleido v0 or deprecated image export features [[#5177](https://github.com/plotly/plotly.py/pull/5236)] + ## [6.1.2] - 2025-05-27 ### Fixed diff --git a/plotly/basedatatypes.py b/plotly/basedatatypes.py index 1a18c3262e..72f4cd25ca 100644 --- a/plotly/basedatatypes.py +++ b/plotly/basedatatypes.py @@ -3724,11 +3724,11 @@ def to_image(self, *args, **kwargs): - 'webp' - 'svg' - 'pdf' - - 'eps' (Kaleido v0.* only) (Requires the poppler library to be installed) + - 'eps' (deprecated) (Requires the poppler library to be installed) If not specified, will default to: - - `plotly.io.defaults.default_format` or `plotly.io.kaleido.scope.default_format` if engine is "kaleido" - - `plotly.io.orca.config.default_format` if engine is "orca" + - `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` @@ -3736,8 +3736,8 @@ def to_image(self, *args, **kwargs): in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_width` or `plotly.io.kaleido.scope.default_width` if engine is "kaleido" - - `plotly.io.orca.config.default_width` if engine is "orca" + - `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` @@ -3745,8 +3745,8 @@ def to_image(self, *args, **kwargs): in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_height` or `plotly.io.kaleido.scope.default_height` if engine is "kaleido" - - `plotly.io.orca.config.default_height` if engine is "orca" + - `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 @@ -3755,14 +3755,14 @@ def to_image(self, *args, **kwargs): less than 1.0 will decrease the image resolution. If not specified, will default to: - - `plotly.io.defaults.default_scale` or `plotly.io.kaleido.scope.default_scale` if engine is "kaliedo" - - `plotly.io.orca.config.default_scale` if engine is "orca" + - `plotly.io.defaults.default_scale` if engine is "kaliedo" + - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated) validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine: str + 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 @@ -3818,13 +3818,13 @@ def write_image(self, *args, **kwargs): - 'webp' - 'svg' - 'pdf' - - 'eps' (Kaleido v0.* only) (Requires the poppler library to be installed) + - '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` or `plotly.io.kaleido.scope.default_format` if engine is "kaleido" - - `plotly.io.orca.config.default_format` if engine is "orca" + - `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` @@ -3832,8 +3832,8 @@ def write_image(self, *args, **kwargs): in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_width` or `plotly.io.kaleido.scope.default_width` if engine is "kaleido" - - `plotly.io.orca.config.default_width` if engine is "orca" + - `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` @@ -3841,8 +3841,8 @@ def write_image(self, *args, **kwargs): in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_height` or `plotly.io.kaleido.scope.default_height` if engine is "kaleido" - - `plotly.io.orca.config.default_height` if engine is "orca" + - `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 @@ -3851,14 +3851,14 @@ def write_image(self, *args, **kwargs): less than 1.0 will decrease the image resolution. If not specified, will default to: - - `plotly.io.defaults.default_scale` or `plotly.io.kaleido.scope.default_scale` if engine is "kaleido" - - `plotly.io.orca.config.default_scale` if engine is "orca" + - `plotly.io.defaults.default_scale` if engine is "kaleido" + - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated) validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine: str + 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 diff --git a/plotly/io/_kaleido.py b/plotly/io/_kaleido.py index 22477a8171..6775c333f1 100644 --- a/plotly/io/_kaleido.py +++ b/plotly/io/_kaleido.py @@ -11,7 +11,7 @@ from plotly.io._defaults import defaults ENGINE_SUPPORT_TIMELINE = "September 2025" -ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS = False +ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS = True PLOTLY_GET_CHROME_ERROR_MSG = """ @@ -247,11 +247,11 @@ def to_image( - 'webp' - 'svg' - 'pdf' - - 'eps' (Kaleido v0.* only) (Requires the poppler library to be installed and on the PATH) + - 'eps' (deprecated) (Requires the poppler library to be installed and on the PATH) If not specified, will default to: - - `plotly.io.defaults.default_format` or `plotly.io.kaleido.scope.default_format` if engine is "kaleido" - - `plotly.io.orca.config.default_format` if engine is "orca" + - `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` @@ -259,8 +259,8 @@ def to_image( in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_width` or `plotly.io.kaleido.scope.default_width` if engine is "kaleido" - - `plotly.io.orca.config.default_width` if engine is "orca" + - `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` @@ -268,8 +268,8 @@ def to_image( in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_height` or `plotly.io.kaleido.scope.default_height` if engine is "kaleido" - - `plotly.io.orca.config.default_height` if engine is "orca" + - `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 @@ -278,14 +278,14 @@ def to_image( less than 1.0 will decrease the image resolution. If not specified, will default to: - - `plotly.io.defaults.default_scale` or `plotly.io.kaleido.scope.default_scale` if engine is "kaleido" - - `plotly.io.orca.config.default_scale` if engine is "orca" + - `plotly.io.defaults.default_scale` if engine is "kaleido" + - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated) validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine: str + 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 @@ -433,13 +433,13 @@ def write_image( - 'webp' - 'svg' - 'pdf' - - 'eps' (Kaleido v0.* only) (Requires the poppler library to be installed and on the PATH) + - 'eps' (deprecated) (Requires the poppler library to be installed and on the PATH) 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` or `plotly.io.kaleido.scope.default_format` if engine is "kaleido" - - `plotly.io.orca.config.default_format` if engine is "orca" + - `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` @@ -447,8 +447,8 @@ def write_image( in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_width` or `plotly.io.kaleido.scope.default_width` if engine is "kaleido" - - `plotly.io.orca.config.default_width` if engine is "orca" + - `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` @@ -456,8 +456,8 @@ def write_image( in physical pixels. If not specified, will default to: - - `plotly.io.defaults.default_height` or `plotly.io.kaleido.scope.default_height` if engine is "kaleido" - - `plotly.io.orca.config.default_height` if engine is "orca" + - `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 @@ -466,14 +466,14 @@ def write_image( less than 1.0 will decrease the image resolution. If not specified, will default to: - - `plotly.io.defaults.default_scale` or `plotly.io.kaleido.scope.default_scale` if engine is "kaleido" - - `plotly.io.orca.config.default_scale` if engine is "orca" + - `plotly.io.defaults.default_scale` if engine is "kaleido" + - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated) validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine: str + 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 @@ -582,8 +582,7 @@ def write_images( provided to the `fig` argument. Specify format as a `str` to apply the same format to all exported images. If not specified, and the corresponding `file` argument has a file extension, then `format` will default to the - file extension. Otherwise, will default to `plotly.io.defaults.default_format` - or `plotly.io.kaleido.scope.default_format`. + file extension. Otherwise, will default to `plotly.io.defaults.default_format`. width: int, None, or list of (int or None) The width of the exported image in layout pixels. If the `scale` @@ -593,8 +592,7 @@ def write_images( Use a list to specify widths for each figure or dict in the list provided to the `fig` argument. Specify width as an `int` to apply the same width to all exported images. - If not specified, will default to `plotly.io.defaults.default_width` - or `plotly.io.kaleido.scope.default_width`. + If not specified, will default to `plotly.io.defaults.default_width`. height: int, None, or list of (int or None) The height of the exported image in layout pixels. If the `scale` @@ -604,8 +602,7 @@ def write_images( Use a list to specify heights for each figure or dict in the list provided to the `fig` argument. Specify height as an `int` to apply the same height to all exported images. - If not specified, will default to `plotly.io.defaults.default_height` - or `plotly.io.kaleido.scope.default_height`. + If not specified, will default to `plotly.io.defaults.default_height`. scale: int, float, None, or list of (int, float, or None) The scale factor to use when exporting the figure. A scale factor @@ -616,8 +613,7 @@ def write_images( Use a list to specify scale for each figure or dict in the list provided to the `fig` argument. Specify scale as an `int` or `float` to apply the same scale to all exported images. - If not specified, will default to `plotly.io.defaults.default_scale` - or `plotly.io.kaleido.scope.default_scale`. + If not specified, will default to `plotly.io.defaults.default_scale`. validate: bool or list of bool True if the figure should be validated before being converted to diff --git a/pyproject.toml b/pyproject.toml index 4df6c544ed..cfd15eb1ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -40,7 +40,7 @@ dependencies = [ [project.optional-dependencies] express = ["numpy"] -kaleido = ["kaleido==1.0.0rc15"] +kaleido = ["kaleido>=1.0.0"] dev_core = [ "pytest", "requests", diff --git a/uv.lock b/uv.lock index 61749f1337..0f3318f370 100644 --- a/uv.lock +++ b/uv.lock @@ -2554,17 +2554,18 @@ wheels = [ [[package]] name = "kaleido" -version = "1.0.0rc15" +version = "1.0.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "choreographer" }, { name = "logistro" }, { name = "orjson", version = "3.10.15", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.9'" }, { name = "orjson", version = "3.10.18", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.9'" }, + { name = "packaging" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/ad/2b/9c418cd10d8019594510bd8803f4c478557b90eea292ad1347fd4ef1a346/kaleido-1.0.0rc15.tar.gz", hash = "sha256:b05e883ea2e45f98c276a9dcfb173ecdd579f7654055bb4c5828de413a833248", size = 48657, upload-time = "2025-06-03T22:21:47.301Z" } +sdist = { url = "https://files.pythonhosted.org/packages/15/dc/fd2d955884f45f852152d44f5ecf79de3cb58da0f995b6f6f9acfc80dd94/kaleido-1.0.0.tar.gz", hash = "sha256:502d8ba64737924efaf5e94c2736745bcc7c926e6cc535838be36c0fc06330bd", size = 49400, upload-time = "2025-06-19T15:50:39.357Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/a0/a4/dadcf07730568aca043afbd7dd27cf5af987cb403cf3be290f96f086e9fc/kaleido-1.0.0rc15-py3-none-any.whl", hash = "sha256:f432dbef249c4db20568dfd88de0f16b4ccb7037cc2088318d9338f1c56e175a", size = 50689, upload-time = "2025-06-03T22:21:45.791Z" }, + { url = "https://files.pythonhosted.org/packages/28/0e/853df00cac4823eaa8f35114d0d0ad1e2ec6b8243ce4acf5f8ac5235c517/kaleido-1.0.0-py3-none-any.whl", hash = "sha256:a7e8bd95648378d2746f6c86084d419d15f95b1ec7bb0ec810289b7feb25b18d", size = 51479, upload-time = "2025-06-19T15:50:37.884Z" }, ] [[package]] @@ -4414,7 +4415,7 @@ requires-dist = [ { name = "geopandas", marker = "extra == 'dev-optional'" }, { name = "inflect", marker = "extra == 'dev-optional'" }, { name = "jupyter", marker = "extra == 'dev-build'" }, - { name = "kaleido", marker = "extra == 'kaleido'", specifier = "==1.0.0rc15" }, + { name = "kaleido", marker = "extra == 'kaleido'", specifier = ">=1.0.0" }, { name = "narwhals", specifier = ">=1.15.1" }, { name = "numpy", marker = "extra == 'dev-optional'" }, { name = "numpy", marker = "extra == 'express'" },