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.

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")
 

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

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
     # ----------------------------

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
 # =====================

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
     # -------

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):

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)