diff --git a/plotly/basedatatypes.py b/plotly/basedatatypes.py index 1f4fd384c8e..12b14c1ca85 100644 --- a/plotly/basedatatypes.py +++ b/plotly/basedatatypes.py @@ -3740,11 +3740,11 @@ def to_image(self, *args, **kwargs): - 'webp' - 'svg' - 'pdf' - - 'eps' (deprecated) (Requires the poppler library to be installed) + - 'eps' (Kaleido v0.* only) (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) + - `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" width: int or None The width of the exported image in layout pixels. If the `scale` @@ -3752,8 +3752,8 @@ def to_image(self, *args, **kwargs): 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) + - `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" height: int or None The height of the exported image in layout pixels. If the `scale` @@ -3761,8 +3761,8 @@ def to_image(self, *args, **kwargs): 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) + - `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" scale: int or float or None The scale factor to use when exporting the figure. A scale factor @@ -3771,14 +3771,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` if engine is "kaliedo" - - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated) + - `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" validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine (deprecated): str + engine: 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 @@ -3794,23 +3794,25 @@ def to_image(self, *args, **kwargs): 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 ( - 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 - ) + 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.to_image(self, *args, **kwargs) @@ -3832,13 +3834,13 @@ def write_image(self, *args, **kwargs): - 'webp' - 'svg' - 'pdf' - - 'eps' (deprecated) (Requires the poppler library to be installed) + - 'eps' (Kaleido v0.* only) (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) + - `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" width: int or None The width of the exported image in layout pixels. If the `scale` @@ -3846,8 +3848,8 @@ def write_image(self, *args, **kwargs): 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) + - `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" height: int or None The height of the exported image in layout pixels. If the `scale` @@ -3855,8 +3857,8 @@ def write_image(self, *args, **kwargs): 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) + - `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" scale: int or float or None The scale factor to use when exporting the figure. A scale factor @@ -3865,14 +3867,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` if engine is "kaleido" - - `plotly.io.orca.config.default_scale` if engine is "orca" (deprecated) + - `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" validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine (deprecated): str + engine: 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 @@ -3887,24 +3889,26 @@ def write_image(self, *args, **kwargs): 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 ( - 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) + 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 # -------------- diff --git a/plotly/io/_kaleido.py b/plotly/io/_kaleido.py index faab2e666ba..fe997a29920 100644 --- a/plotly/io/_kaleido.py +++ b/plotly/io/_kaleido.py @@ -11,6 +11,7 @@ from plotly.io._defaults import defaults ENGINE_SUPPORT_TIMELINE = "September 2025" +ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS = False PLOTLY_GET_CHROME_ERROR_MSG = """ @@ -23,8 +24,6 @@ """ - -# TODO: Remove --pre flag once Kaleido v1 full release is available KALEIDO_DEPRECATION_MSG = f""" Support for Kaleido versions less than 1.0.0 is deprecated and will be removed after {ENGINE_SUPPORT_TIMELINE}. Please upgrade Kaleido to version 1.0.0 or greater (`pip install 'kaleido>=1.0.0'` or `pip install 'plotly[kaleido]'`). @@ -95,23 +94,25 @@ def kaleido_major() -> int: from kaleido.scopes.plotly import PlotlyScope # Show a deprecation warning if the old method of setting defaults is used - class PlotlyScopeWithDeprecationWarnings(PlotlyScope): + class PlotlyScopeWrapper(PlotlyScope): def __setattr__(self, name, value): if name in defaults.__dict__: - warnings.warn( - kaleido_scope_default_warning_func(name), - DeprecationWarning, - stacklevel=2, - ) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn( + kaleido_scope_default_warning_func(name), + DeprecationWarning, + stacklevel=2, + ) super().__setattr__(name, value) def __getattr__(self, name): if hasattr(defaults, name): - warnings.warn( - kaleido_scope_default_warning_func(name), - DeprecationWarning, - stacklevel=2, - ) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn( + kaleido_scope_default_warning_func(name), + DeprecationWarning, + stacklevel=2, + ) return super().__getattr__(name) # Ensure the new method of setting defaults is backwards compatible with Kaleido v0 @@ -131,7 +132,7 @@ def __setattr__(self, name, value): setattr(self._scope, name, value) super().__setattr__(name, value) - scope = PlotlyScopeWithDeprecationWarnings() + scope = PlotlyScopeWrapper() defaults = DefaultsBackwardsCompatible(scope) # Compute absolute path to the 'plotly/package_data/' directory root_dir = os.path.dirname(os.path.abspath(plotly.__file__)) @@ -150,30 +151,32 @@ def __setattr__(self, name, value): import kaleido # Show a deprecation warning if the old method of setting defaults is used - class DefaultsDeprecationWarning: + class DefaultsWrapper: def __getattr__(self, name): if hasattr(defaults, name): - warnings.warn( - kaleido_scope_default_warning_func(name), - DeprecationWarning, - stacklevel=2, - ) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn( + kaleido_scope_default_warning_func(name), + DeprecationWarning, + stacklevel=2, + ) return getattr(defaults, name) else: raise AttributeError(bad_attribute_error_msg_func(name)) def __setattr__(self, name, value): if hasattr(defaults, name): - warnings.warn( - kaleido_scope_default_warning_func(name), - DeprecationWarning, - stacklevel=2, - ) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn( + kaleido_scope_default_warning_func(name), + DeprecationWarning, + stacklevel=2, + ) setattr(defaults, name, value) else: raise AttributeError(bad_attribute_error_msg_func(name)) - scope = DefaultsDeprecationWarning() + scope = DefaultsWrapper() except ImportError as e: PlotlyScope = None @@ -243,11 +246,11 @@ def to_image( - 'webp' - 'svg' - 'pdf' - - 'eps' (deprecated) (Requires the poppler library to be installed and on the PATH) + - 'eps' (Kaleido v0.* only) (Requires the poppler library to be installed and on the PATH) 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) + - `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" width: int or None The width of the exported image in layout pixels. If the `scale` @@ -255,8 +258,8 @@ def to_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) + - `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" height: int or None The height of the exported image in layout pixels. If the `scale` @@ -264,8 +267,8 @@ def to_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) + - `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" scale: int or float or None The scale factor to use when exporting the figure. A scale factor @@ -274,14 +277,14 @@ def to_image( 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) + - `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" validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine (deprecated): str + engine: 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 @@ -296,7 +299,10 @@ def to_image( # Handle engine if engine is not None: - warnings.warn(ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn( + ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2 + ) else: engine = "auto" @@ -317,7 +323,8 @@ def to_image( engine = "kaleido" if engine == "orca": - warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) # Fall back to legacy orca image export path from ._orca import to_image as to_image_orca @@ -385,7 +392,8 @@ def to_image( else: # Kaleido v0 - warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) img_bytes = scope.transform( fig_dict, format=format, width=width, height=height, scale=scale ) @@ -424,13 +432,13 @@ def write_image( - 'webp' - 'svg' - 'pdf' - - 'eps' (deprecated) (Requires the poppler library to be installed and on the PATH) + - 'eps' (Kaleido v0.* only) (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` if engine is "kaleido" - - `plotly.io.orca.config.default_format` if engine is "orca" (deprecated) + - `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" width: int or None The width of the exported image in layout pixels. If the `scale` @@ -438,8 +446,8 @@ def write_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) + - `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" height: int or None The height of the exported image in layout pixels. If the `scale` @@ -447,8 +455,8 @@ def write_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) + - `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" scale: int or float or None The scale factor to use when exporting the figure. A scale factor @@ -457,14 +465,14 @@ def write_image( 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) + - `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" validate: bool True if the figure should be validated before being converted to an image, False otherwise. - engine (deprecated): str + engine: 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 @@ -476,16 +484,19 @@ def write_image( None """ # Show Kaleido deprecation warning if needed - if ( - engine in {None, "auto", "kaleido"} - and kaleido_available() - and kaleido_major() < 1 - ): - warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) - if engine == "orca": - warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) - if engine not in {None, "auto"}: - warnings.warn(ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + if ( + engine in {None, "auto", "kaleido"} + and kaleido_available() + and kaleido_major() < 1 + ): + warnings.warn(KALEIDO_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) + if engine == "orca": + warnings.warn(ORCA_DEPRECATION_MSG, DeprecationWarning, stacklevel=2) + if engine not in {None, "auto"}: + warnings.warn( + ENGINE_PARAM_DEPRECATION_MSG, DeprecationWarning, stacklevel=2 + ) # Try to cast `file` as a pathlib object `path`. path = as_path_object(file) @@ -570,7 +581,8 @@ 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`. + file extension. Otherwise, will default to `plotly.io.defaults.default_format` + or `plotly.io.kaleido.scope.default_format`. width: int, None, or list of (int or None) The width of the exported image in layout pixels. If the `scale` @@ -580,7 +592,8 @@ 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`. + If not specified, will default to `plotly.io.defaults.default_width` + or `plotly.io.kaleido.scope.default_width`. height: int, None, or list of (int or None) The height of the exported image in layout pixels. If the `scale` @@ -590,7 +603,8 @@ 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`. + If not specified, will default to `plotly.io.defaults.default_height` + or `plotly.io.kaleido.scope.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 @@ -601,7 +615,8 @@ 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`. + If not specified, will default to `plotly.io.defaults.default_scale` + or `plotly.io.kaleido.scope.default_scale`. validate: bool or list of bool True if the figure should be validated before being converted to @@ -748,11 +763,12 @@ def full_figure_for_development( fig = json.loads(bytes.decode("utf-8")) else: # Kaleido v0 - warnings.warn( - f"Support for Kaleido versions less than 1.0.0 is deprecated and will be removed after {ENGINE_SUPPORT_TIMELINE}. " - + "Please upgrade Kaleido to version 1.0.0 or greater (`pip install 'kaleido>=1.0.0'`).", - DeprecationWarning, - ) + if ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS: + warnings.warn( + f"Support for Kaleido versions less than 1.0.0 is deprecated and will be removed after {ENGINE_SUPPORT_TIMELINE}. " + + "Please upgrade Kaleido to version 1.0.0 or greater (`pip install 'kaleido>=1.0.0'`).", + DeprecationWarning, + ) fig = json.loads(scope.transform(fig, format="json").decode("utf-8")) if as_dict: diff --git a/plotly/io/kaleido.py b/plotly/io/kaleido.py index e4df9f53c71..f7e2bacecdf 100644 --- a/plotly/io/kaleido.py +++ b/plotly/io/kaleido.py @@ -4,6 +4,7 @@ scope, kaleido_available, kaleido_major, + ENABLE_KALEIDO_V0_DEPRECATION_WARNINGS, KALEIDO_DEPRECATION_MSG, ORCA_DEPRECATION_MSG, ENGINE_PARAM_DEPRECATION_MSG,