add new API for setting image generation defaults

Author: emilykl

plotly/io/__init__.py

@@ -17,6 +17,7 @@
     from ._html import to_html, write_html
     from ._renderers import renderers, show
     from . import base_renderers
+    from ._defaults import defaults
 
     __all__ = [
         "to_image",
@@ -37,6 +38,7 @@
         "show",
         "base_renderers",
         "full_figure_for_development",
+        "defaults",
     ]
 else:
     __all__, __getattr__, __dir__ = relative_import(
@@ -58,6 +60,7 @@
             "._html.write_html",
             "._renderers.renderers",
             "._renderers.show",
+            "._defaults.defaults",
         ],
     )
 

plotly/io/_defaults.py

@@ -0,0 +1,18 @@
+# Default settings for image generation
+
+
+class _Defaults(object):
+    """
+    Class to store default settings for image generation.
+    """
+    def __init__(self):
+        self.default_format = "png"
+        self.default_width = 700
+        self.default_height = 500
+        self.default_scale = 1
+
+defaults = _Defaults()
+
+
+
+

plotly/io/_kaleido.py

@@ -7,9 +7,32 @@
 
 import plotly
 from plotly.io._utils import validate_coerce_fig_to_dict, as_individual_args
+from plotly.io import defaults
 
 ENGINE_SUPPORT_TIMELINE = "September 2025"
 
+kaleido_scope_default_getwarning = (
+    lambda x: f"""
+Accessing plotly.io.kaleido.scope.{x} is deprecated and will be removed after {ENGINE_SUPPORT_TIMELINE}.
+Please use plotly.io.defaults.{x} instead.
+"""
+)
+
+kaleido_scope_default_setwarning = (
+    lambda x: f"""
+Setting plotly.io.kaleido.scope.{x} is deprecated and will be removed after {ENGINE_SUPPORT_TIMELINE}. "
+Please set plotly.io.defaults.{x} instead.
+"""
+)
+
+bad_attribute_error = (
+    lambda x: f"""
+Attribute plotly.io.defaults.{x} is not valid.
+Also, plotly.io.kaleido.scope.* is deprecated and will be removed after {ENGINE_SUPPORT_TIMELINE}. Please use plotly.io.defaults.* instead.
+"""
+)
+
+
 try:
     import kaleido
 
@@ -20,7 +43,28 @@
         # Kaleido v0
         from kaleido.scopes.plotly import PlotlyScope
 
-        scope = PlotlyScope()
+        # Show a deprecation warning if the old method of setting defaults is used
+        class PlotlyScopeWithDeprecationWarnings(PlotlyScope):
+            def __setattr__(self, name, value):
+                if name in defaults.__dict__:
+                    warnings.warn(
+                        kaleido_scope_default_setwarning(name),
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
+                    setattr(defaults, name, value)
+                super(PlotlyScopeWithDeprecationWarnings, self).__setattr__(name, value)
+
+            def __getattr__(self, name):
+                if name in defaults.__dict__:
+                    warnings.warn(
+                        kaleido_scope_default_getwarning(name),
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
+                return super(PlotlyScopeWithDeprecationWarnings, self).__getattr__(name)
+
+        scope = PlotlyScopeWithDeprecationWarnings()
         # Compute absolute path to the 'plotly/package_data/' directory
         root_dir = os.path.dirname(os.path.abspath(plotly.__file__))
         package_dir = os.path.join(root_dir, "package_data")
@@ -29,6 +73,34 @@
             scope.mathjax = (
                 "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js"
             )
+    else:
+        # Kaleido v1
+
+        # Show a deprecation warning if the old method of setting defaults is used
+        class DefaultsDeprecationWarning:
+            def __getattr__(self, name):
+                if name in defaults.__dict__:
+                    warnings.warn(
+                        kaleido_scope_default_getwarning(name),
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
+                    return getattr(defaults, name)
+                else:
+                    raise AttributeError(bad_attribute_error(name))
+
+            def __setattr__(self, name, value):
+                if name in defaults.__dict__:
+                    warnings.warn(
+                        kaleido_scope_default_setwarning(name),
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
+                    setattr(defaults, name, value)
+                else:
+                    raise AttributeError(bad_attribute_error(name))
+
+        scope = DefaultsDeprecationWarning()
 
 except ImportError as e:
     kaleido_available = False
@@ -64,29 +136,37 @@ def to_image(
             - 'pdf'
             - 'eps' (Requires the poppler library to be installed and on the PATH)
 
-        If not specified, will default to `plotly.io.kaleido.scope.default_format`
+        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.kaleido.scope.default_width`
+        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.kaleido.scope.default_height`
+        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.kaleido.scope.default_scale`
+        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)
 
     validate: bool
         True if the figure should be validated before being converted to
@@ -174,8 +254,8 @@ def to_image(
         if format == "eps":
             raise ValueError(
                 f"""
-EPS export is not supported with Kaleido v1. Please use SVG or PDF instead.
-You can also downgrade to Kaleido v0, but support for v0 will be removed after {ENGINE_SUPPORT_TIMELINE}.
+EPS export is not supported by Kaleido v1. Please use SVG or PDF instead.
+You can also downgrade to Kaleido v0, but support for Kaleido v0 will be removed after {ENGINE_SUPPORT_TIMELINE}.
 To downgrade to Kaleido v0, run:
     $ pip install kaleido<1.0.0
 """
@@ -187,10 +267,10 @@ def to_image(
             img_bytes = kaleido.calc_fig_sync(
                 fig_dict,
                 opts=dict(
-                    format=format,
-                    width=width,
-                    height=height,
-                    scale=scale,
+                    format=format or defaults.default_format,
+                    width=width or defaults.default_width,
+                    height=height or defaults.default_height,
+                    scale=scale or defaults.default_scale,
                 ),
             )
         except choreographer.errors.ChromeNotFoundError:
@@ -252,30 +332,36 @@ def write_image(
         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.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`
         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.kaleido.scope.default_width`
+        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.kaleido.scope.default_height`
+        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.kaleido.scope.default_scale`
+        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)
 
     validate: bool
         True if the figure should be validated before being converted to

plotly/io/kaleido.py

@@ -1 +1 @@
-from ._kaleido import write_image, to_image
+from ._kaleido import to_image, write_image, scope

tests/test_optional/test_kaleido/test_kaleido.py

@@ -251,3 +251,16 @@ def test_write_images_multiple(mock_write_image):
     ]
     mock_write_image.assert_has_calls(expected_calls, any_order=False)
     assert mock_write_image.call_count == 2
+
+
+def test_defaults():
+    """Test that image output defaults can be set using pio.defaults.*"""
+    try:
+        assert pio.defaults.default_format == "png"
+        pio.defaults.default_format = "svg"
+        assert pio.defaults.default_format == "svg"
+        result = pio.to_image(fig, format="svg", validate=False)
+        assert result.startswith(b"<svg")
+    finally:
+        pio.defaults.default_format = "png"
+        assert pio.defaults.default_format == "png"