feat: incorporating feedback from @emilykl

- Add caveat to the top of every machine-generated file to warn people not to edit them. - Make name of initial value property setter more readable. - Run black formatting with multiple Python versions.
plotly · gvwilson · Apr 17, 2025 · Feb 4, 2025 · Feb 11, 2025 · Feb 11, 2025
commit d69844ff7232be618cf4fc38a2e454c2986d672e
diff --git a/codegen/__init__.py b/codegen/__init__.py
@@ -28,7 +28,7 @@

 # Target Python version for code formatting with Black.
 # Must be one of the values listed in pyproject.toml.
-BLACK_TARGET_VERSION = "py311"
+BLACK_TARGET_VERSIONS = "py38 py39 py310 py311 py312"


 # Import notes
@@ -330,10 +330,12 @@ def __getattr__(import_name):

    # ### Run black code formatter on output directories ###
    if reformat:
-        target_version = f"--target-version={BLACK_TARGET_VERSION}"
-        subprocess.call(["black", target_version, validators_pkgdir])
-        subprocess.call(["black", target_version, graph_objs_pkgdir])
-        subprocess.call(["black", target_version, graph_objects_path])
+        target_version = [
+            f"--target-version={v}" for v in BLACK_TARGET_VERSIONS.split()
+        ]
+        subprocess.call(["black", *target_version, validators_pkgdir])
+        subprocess.call(["black", *target_version, graph_objs_pkgdir])
+        subprocess.call(["black", *target_version, graph_objects_path])
    else:
        print("skipping reformatting")


diff --git a/codegen/datatypes.py b/codegen/datatypes.py
@@ -2,7 +2,7 @@
 import textwrap
 from io import StringIO

-from codegen.utils import PlotlyNode, write_source_py
+from codegen.utils import CAVEAT, PlotlyNode, write_source_py


 deprecated_mapbox_traces = [
@@ -90,6 +90,7 @@ def build_datatype_py(node):

    # Initialze source code buffer
    buffer = StringIO()
+    buffer.write(CAVEAT)

    # Imports
    buffer.write(
@@ -362,12 +363,12 @@ def __init__(self"""
        # we suppress deprecation warnings for this line only.
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", category=DeprecationWarning)
-            self._init_provided('{name_prop}', arg, {name_prop})"""
+            self._set_property('{name_prop}', arg, {name_prop})"""
            )
        else:
            buffer.write(
                f"""
-        self._init_provided('{name_prop}', arg, {name_prop})"""
+        self._set_property('{name_prop}', arg, {name_prop})"""
            )

    ### Literals

diff --git a/codegen/figure.py b/codegen/figure.py
@@ -6,7 +6,7 @@
    add_constructor_params,
    add_docstring,
 )
-from codegen.utils import write_source_py
+from codegen.utils import CAVEAT, write_source_py

 import inflect
 from plotly.basedatatypes import BaseFigure
@@ -55,6 +55,7 @@ def build_figure_py(
    # Initialize source code buffer
    # -----------------------------
    buffer = StringIO()
+    buffer.write(CAVEAT)

    # Get list of trace type nodes
    # ----------------------------

diff --git a/codegen/utils.py b/codegen/utils.py
@@ -8,6 +8,13 @@
 import re
 import errno

+CAVEAT = """
+
+#                   --- THIS FILE IS AUTO-GENERATED ---
+# Modifications will be overwitten the next time code generation run.
+
+"""
+

 # Source code utilities
 # =====================

diff --git a/codegen/validators.py b/codegen/validators.py
@@ -2,7 +2,7 @@
 from io import StringIO

 import _plotly_utils.basevalidators
-from codegen.utils import PlotlyNode, TraceNode, write_source_py
+from codegen.utils import CAVEAT, PlotlyNode, TraceNode, write_source_py


 def build_validator_py(node: PlotlyNode):
@@ -25,8 +25,9 @@ def build_validator_py(node: PlotlyNode):
    assert node.is_datatype

    # Initialize
-    buffer = StringIO()
    import_alias = "_bv"
+    buffer = StringIO()
+    buffer.write(CAVEAT)

    # Imports
    # -------

diff --git a/plotly/basedatatypes.py b/plotly/basedatatypes.py
@@ -386,7 +386,7 @@ def _generator(i):
        yield x


-def _initialize_provided(obj, name, arg, provided):
+def _set_property_provided_value(obj, name, arg, provided):
    """
    Initialize a property of this object using the provided value
    or a value popped from the arguments dictionary. If neither
@@ -847,13 +847,13 @@ def _ipython_display_(self):
        else:
            print(repr(self))

-    def _init_provided(self, name, arg, provided):
+    def _set_property(self, name, arg, provided):
        """
        Initialize a property of this object using the provided value
        or a value popped from the arguments dictionary. If neither
        is available, do not set the property.
        """
-        _initialize_provided(self, name, arg, provided)
+        _set_property_provided_value(self, name, arg, provided)

    def update(self, dict1=None, overwrite=False, **kwargs):
        """
@@ -4351,13 +4351,13 @@ def _get_validator(self, prop):

        return ValidatorCache.get_validator(self._path_str, prop)

-    def _init_provided(self, name, arg, provided):
+    def _set_property(self, name, arg, provided):
        """
        Initialize a property of this object using the provided value
        or a value popped from the arguments dictionary. If neither
        is available, do not set the property.
        """
-        _initialize_provided(self, name, arg, provided)
+        _set_property_provided_value(self, name, arg, provided)

    @property
    def _validators(self):

diff --git a/plotly/graph_objs/_bar.py b/plotly/graph_objs/_bar.py
@@ -1,3 +1,6 @@
+#                   --- THIS FILE IS AUTO-GENERATED ---
+# Modifications will be overwitten the next time code generation run.
+
 from plotly.basedatatypes import BaseTraceType as _BaseTraceType
 import copy as _copy

@@ -2517,80 +2520,80 @@ def __init__(
        self._skip_invalid = kwargs.pop("skip_invalid", False)
        self._validate = kwargs.pop("_validate", True)

-        self._init_provided("alignmentgroup", arg, alignmentgroup)
-        self._init_provided("base", arg, base)
-        self._init_provided("basesrc", arg, basesrc)
-        self._init_provided("cliponaxis", arg, cliponaxis)
-        self._init_provided("constraintext", arg, constraintext)
-        self._init_provided("customdata", arg, customdata)
-        self._init_provided("customdatasrc", arg, customdatasrc)
-        self._init_provided("dx", arg, dx)
-        self._init_provided("dy", arg, dy)
-        self._init_provided("error_x", arg, error_x)
-        self._init_provided("error_y", arg, error_y)
-        self._init_provided("hoverinfo", arg, hoverinfo)
-        self._init_provided("hoverinfosrc", arg, hoverinfosrc)
-        self._init_provided("hoverlabel", arg, hoverlabel)
-        self._init_provided("hovertemplate", arg, hovertemplate)
-        self._init_provided("hovertemplatesrc", arg, hovertemplatesrc)
-        self._init_provided("hovertext", arg, hovertext)
-        self._init_provided("hovertextsrc", arg, hovertextsrc)
-        self._init_provided("ids", arg, ids)
-        self._init_provided("idssrc", arg, idssrc)
-        self._init_provided("insidetextanchor", arg, insidetextanchor)
-        self._init_provided("insidetextfont", arg, insidetextfont)
-        self._init_provided("legend", arg, legend)
-        self._init_provided("legendgroup", arg, legendgroup)
-        self._init_provided("legendgrouptitle", arg, legendgrouptitle)
-        self._init_provided("legendrank", arg, legendrank)
-        self._init_provided("legendwidth", arg, legendwidth)
-        self._init_provided("marker", arg, marker)
-        self._init_provided("meta", arg, meta)
-        self._init_provided("metasrc", arg, metasrc)
-        self._init_provided("name", arg, name)
-        self._init_provided("offset", arg, offset)
-        self._init_provided("offsetgroup", arg, offsetgroup)
-        self._init_provided("offsetsrc", arg, offsetsrc)
-        self._init_provided("opacity", arg, opacity)
-        self._init_provided("orientation", arg, orientation)
-        self._init_provided("outsidetextfont", arg, outsidetextfont)
-        self._init_provided("selected", arg, selected)
-        self._init_provided("selectedpoints", arg, selectedpoints)
-        self._init_provided("showlegend", arg, showlegend)
-        self._init_provided("stream", arg, stream)
-        self._init_provided("text", arg, text)
-        self._init_provided("textangle", arg, textangle)
-        self._init_provided("textfont", arg, textfont)
-        self._init_provided("textposition", arg, textposition)
-        self._init_provided("textpositionsrc", arg, textpositionsrc)
-        self._init_provided("textsrc", arg, textsrc)
-        self._init_provided("texttemplate", arg, texttemplate)
-        self._init_provided("texttemplatesrc", arg, texttemplatesrc)
-        self._init_provided("uid", arg, uid)
-        self._init_provided("uirevision", arg, uirevision)
-        self._init_provided("unselected", arg, unselected)
-        self._init_provided("visible", arg, visible)
-        self._init_provided("width", arg, width)
-        self._init_provided("widthsrc", arg, widthsrc)
-        self._init_provided("x", arg, x)
-        self._init_provided("x0", arg, x0)
-        self._init_provided("xaxis", arg, xaxis)
-        self._init_provided("xcalendar", arg, xcalendar)
-        self._init_provided("xhoverformat", arg, xhoverformat)
-        self._init_provided("xperiod", arg, xperiod)
-        self._init_provided("xperiod0", arg, xperiod0)
-        self._init_provided("xperiodalignment", arg, xperiodalignment)
-        self._init_provided("xsrc", arg, xsrc)
-        self._init_provided("y", arg, y)
-        self._init_provided("y0", arg, y0)
-        self._init_provided("yaxis", arg, yaxis)
-        self._init_provided("ycalendar", arg, ycalendar)
-        self._init_provided("yhoverformat", arg, yhoverformat)
-        self._init_provided("yperiod", arg, yperiod)
-        self._init_provided("yperiod0", arg, yperiod0)
-        self._init_provided("yperiodalignment", arg, yperiodalignment)
-        self._init_provided("ysrc", arg, ysrc)
-        self._init_provided("zorder", arg, zorder)
+        self._set_property("alignmentgroup", arg, alignmentgroup)
+        self._set_property("base", arg, base)
+        self._set_property("basesrc", arg, basesrc)
+        self._set_property("cliponaxis", arg, cliponaxis)
+        self._set_property("constraintext", arg, constraintext)
+        self._set_property("customdata", arg, customdata)
+        self._set_property("customdatasrc", arg, customdatasrc)
+        self._set_property("dx", arg, dx)
+        self._set_property("dy", arg, dy)
+        self._set_property("error_x", arg, error_x)
+        self._set_property("error_y", arg, error_y)
+        self._set_property("hoverinfo", arg, hoverinfo)
+        self._set_property("hoverinfosrc", arg, hoverinfosrc)
+        self._set_property("hoverlabel", arg, hoverlabel)
+        self._set_property("hovertemplate", arg, hovertemplate)
+        self._set_property("hovertemplatesrc", arg, hovertemplatesrc)
+        self._set_property("hovertext", arg, hovertext)
+        self._set_property("hovertextsrc", arg, hovertextsrc)
+        self._set_property("ids", arg, ids)
+        self._set_property("idssrc", arg, idssrc)
+        self._set_property("insidetextanchor", arg, insidetextanchor)
+        self._set_property("insidetextfont", arg, insidetextfont)
+        self._set_property("legend", arg, legend)
+        self._set_property("legendgroup", arg, legendgroup)
+        self._set_property("legendgrouptitle", arg, legendgrouptitle)
+        self._set_property("legendrank", arg, legendrank)
+        self._set_property("legendwidth", arg, legendwidth)
+        self._set_property("marker", arg, marker)
+        self._set_property("meta", arg, meta)
+        self._set_property("metasrc", arg, metasrc)
+        self._set_property("name", arg, name)
+        self._set_property("offset", arg, offset)
+        self._set_property("offsetgroup", arg, offsetgroup)
+        self._set_property("offsetsrc", arg, offsetsrc)
+        self._set_property("opacity", arg, opacity)
+        self._set_property("orientation", arg, orientation)
+        self._set_property("outsidetextfont", arg, outsidetextfont)
+        self._set_property("selected", arg, selected)
+        self._set_property("selectedpoints", arg, selectedpoints)
+        self._set_property("showlegend", arg, showlegend)
+        self._set_property("stream", arg, stream)
+        self._set_property("text", arg, text)
+        self._set_property("textangle", arg, textangle)
+        self._set_property("textfont", arg, textfont)
+        self._set_property("textposition", arg, textposition)
+        self._set_property("textpositionsrc", arg, textpositionsrc)
+        self._set_property("textsrc", arg, textsrc)
+        self._set_property("texttemplate", arg, texttemplate)
+        self._set_property("texttemplatesrc", arg, texttemplatesrc)
+        self._set_property("uid", arg, uid)
+        self._set_property("uirevision", arg, uirevision)
+        self._set_property("unselected", arg, unselected)
+        self._set_property("visible", arg, visible)
+        self._set_property("width", arg, width)
+        self._set_property("widthsrc", arg, widthsrc)
+        self._set_property("x", arg, x)
+        self._set_property("x0", arg, x0)
+        self._set_property("xaxis", arg, xaxis)
+        self._set_property("xcalendar", arg, xcalendar)
+        self._set_property("xhoverformat", arg, xhoverformat)
+        self._set_property("xperiod", arg, xperiod)
+        self._set_property("xperiod0", arg, xperiod0)
+        self._set_property("xperiodalignment", arg, xperiodalignment)
+        self._set_property("xsrc", arg, xsrc)
+        self._set_property("y", arg, y)
+        self._set_property("y0", arg, y0)
+        self._set_property("yaxis", arg, yaxis)
+        self._set_property("ycalendar", arg, ycalendar)
+        self._set_property("yhoverformat", arg, yhoverformat)
+        self._set_property("yperiod", arg, yperiod)
+        self._set_property("yperiod0", arg, yperiod0)
+        self._set_property("yperiodalignment", arg, yperiodalignment)
+        self._set_property("ysrc", arg, ysrc)
+        self._set_property("zorder", arg, zorder)

        self._props["type"] = "bar"
        arg.pop("type", None)