Merge branch 'main' into kaleido-docs-updates

Author: LiamConnors

.circleci/config.yml

@@ -58,9 +58,6 @@ commands:
             source .venv/bin/activate
             uv pip install .
             uv pip install -r ./test_requirements/requirements_optional.txt
-            cd js
-            npm ci
-            npm run build
       
       - when:
           condition: 
@@ -129,7 +126,7 @@ jobs:
           command: |
             python -m venv venv
             . venv/bin/activate
-            pip install black==22.3.0
+            pip install black==25.1.0
       - run:
           name: Check formatting with black
           command: |
@@ -269,22 +266,18 @@ jobs:
 
     steps:
       - checkout
-
       - run:
-          name: initial NPM Build
+          name: PyPI Build
           command: |
-            python -m venv venv
-            . venv/bin/activate
+            curl -LsSf https://astral.sh/uv/install.sh | sh
+            uv venv
+            source .venv/bin/activate
+            uv pip install build
+            uv pip install jupyter
             cd js
             npm ci
             npm run build
-            git status
-
-      - run:
-          name: PyPI Build
-          command: |
-            . venv/bin/activate
-            pip install build
+            cd ..
             python -m build --sdist --wheel -o dist
             cp -R dist output
             git status
@@ -310,7 +303,6 @@ jobs:
       - checkout
       - browser-tools/install-chrome
       - browser-tools/install-chromedriver
-
       - run:
           name: Install dependencies
           command: |
@@ -319,16 +311,11 @@ jobs:
             uv venv
             source .venv/bin/activate
             uv pip install -r requirements.txt
+            cd ..
             if [ "${CIRCLE_BRANCH}" != "doc-prod" ]; then
               uv pip uninstall plotly
-              cd ..
               uv pip install -e .
-              cd js
-              npm ci
-              npm run build
-              cd ../doc
             fi
-            cd ..
 
       - run:
           name: make html
@@ -420,7 +407,7 @@ workflows:
   release_build:
     jobs:
       - full_build
-
+  
   build:
     jobs:
       - test_core_py:
@@ -449,4 +436,4 @@ workflows:
           pandas_version: "1.2.4"
           numpy_version: "1.26.4"
       - python_311_percy
-      - build-doc
+      - build-doc

.github/workflows/check-js-build.yml

@@ -0,0 +1,66 @@
+on: push
+
+jobs:
+  check-js-build:
+    name: Check JS build artifacts
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.x"
+        
+    - name: Install Node
+      uses: actions/setup-node@v2
+      with:
+        node-version: '22'
+
+    - name: Copy current files to a temporary directory
+      run: |
+        cp -R plotly/labextension/ plotly/labextension-tmp/
+
+    - name: Install dependencies and build
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        uv venv
+        source .venv/bin/activate
+        uv pip install jupyter
+        cd js
+        npm ci
+        npm run build
+    - name: Check JupyterLab build artifacts
+      run: |
+        # 1. Hash contents of all static files, sort by content hash
+        find plotly/labextension/static -type f -exec sha256sum {} \; | awk '{print $1}' | sort > new_hashes.txt
+        find plotly/labextension-tmp/static -type f -exec sha256sum {} \; | awk '{print $1}' | sort > old_hashes.txt
+
+        # 2. Compare the sorted content hashes
+        diff old_hashes.txt new_hashes.txt > content_diff.txt
+
+        # Remove the "load" line from both package.json files before comparing
+        grep -v '"load": "static/' plotly/labextension/package.json > pkg1.json
+        grep -v '"load": "static/' plotly/labextension-tmp/package.json > pkg2.json
+
+        # Compare stripped versions
+        diff pkg1.json pkg2.json > package_json_diff.txt
+
+        # 5. Final check
+        if [ -s content_diff.txt ] || [ -s package_json_diff.txt ]; then
+        echo "❌ Build artifacts differ:"
+        echo "--- Unexpected diffs ---"
+        cat content_diff.txt
+        echo "--- Unexpected package.json diffs ---"
+        cat package_json_diff.txt
+        echo "Please replace the 'plotly/labextension' directory with the artifacts of this CI run."
+        exit 1
+        else
+        echo "✅ Build artifacts match expected output (ignoring known 'load' hash in package.json)."
+        fi
+
+    - name: Store the build artifacts from plotly/labextension
+      uses: actions/upload-artifact@v4
+      if: failure()
+      with:
+        name: labextension
+        path: plotly/labextension

.github/workflows/test-release.yml

@@ -20,10 +20,14 @@ jobs:
     - name: Install Node
       uses: actions/setup-node@v2
       with:
-        node-version: '18'
+        node-version: '22'
 
     - name: Install npm dependencies
       run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        uv venv
+        source .venv/bin/activate
+        uv pip install jupyter
         cd js
         npm ci --verbose
         npm run build --verbose

.gitignore

@@ -59,7 +59,6 @@ doc/python/.mapbox_token
 doc/.ipynb_checkpoints
 tags
 doc/check-or-enforce-order.py
-plotly/package_data/widgetbundle.js
 
 tests/percy/*.html
 tests/percy/pandas2/*.html

CHANGELOG.md

@@ -1,4 +1,4 @@
-# Change Log
+# Changelog
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 

CONTRIBUTING.md

@@ -169,6 +169,19 @@ and
 [`pip`](https://pip.pypa.io/en/stable/reference/pip_install/#install-editable)
 documentation on _development mode_.
 
+### Updating the `js/` directory
+**This is only necessary if you're making changes to files in the `js/` directory.**
+If you make changes to any files in the `js/` directory, you must run `npm install && npm run build` from the `js/` directory to rebuild the FigureWidget and JupyterLab extension.
+You must then commit the build artifacts produced in `plotly/labextension`. A CI job will verify that this step has been done correctly.
+
+**Notes on the contents of the `js/` directory:**
+The `js/` directory contains Javascript code which helps with using Plotly in Jupyter notebooks.
+
+There are two kinds of Jupyter support included in the `js/` directory:
+1. **Mime Renderer JupyterLab extension**: This is the default renderer for Plotly `Figure()` objects in Jupyter notebooks. The Plotly mime renderer JupyterLab extension is used automatically by JupyterLab / Jupyter Notebook
+when it sees the mimetype `application/vnd.plotly.v1+json` in the notebook output. The mime renderer loads `plotly.js` a single time and references it each time a Plotly figure is used in the notebook. This allows us to avoid embedding `plotly.js` in the notebook output. The JupyterLab extension source code is located at `js/src/mimeExtension.ts` and the compiled extension code is located at `plotly/labextension` in the built Python package. The command `jupyter labextension build` (which is one of the steps called by `npm run build`) compiles the extension and places the build artifacts in `plotly/labextension`. 
+2. **FigureWidget**: This is a more-interactive method for rendering Plotly charts in notebooks. FigureWidget used by creating a `FigureWidget()` object inside the notebook code (in place of a `Figure()`). It allows for communication between the Javascript frontend and Python backend, and requires the installation of an additional Python package (`anywidget`). The FigureWidget source code is located at `js/src/widget.ts`, and is included in the built Python package at `plotly/package_data/widgetbundle.js`. 
+
 ### Configure black code formatting
 
 This repo uses the [Black](https://black.readthedocs.io/en/stable/) code formatter,

_plotly_utils/basevalidators.py

@@ -1328,25 +1328,14 @@ def numbers_allowed(self):
         return self.colorscale_path is not None
 
     def description(self):
-
-        named_clrs_str = "\n".join(
-            textwrap.wrap(
-                ", ".join(self.named_colors),
-                width=79 - 16,
-                initial_indent=" " * 12,
-                subsequent_indent=" " * 12,
-            )
-        )
-
         valid_color_description = """\
     The '{plotly_name}' property is a color and may be specified as:
       - A hex string (e.g. '#ff0000')
       - An rgb/rgba string (e.g. 'rgb(255,0,0)')
       - An hsl/hsla string (e.g. 'hsl(0,100%,50%)')
       - An hsv/hsva string (e.g. 'hsv(0,100%,100%)')
-      - A named CSS color:
-{clrs}""".format(
-            plotly_name=self.plotly_name, clrs=named_clrs_str
+      - A named CSS color: see https://plotly.com/python/css-colors/ for a list""".format(
+            plotly_name=self.plotly_name
         )
 
         if self.colorscale_path:
@@ -2483,15 +2472,11 @@ def description(self):
     that may be specified as:
       - An instance of :class:`{module_str}.{class_str}`
       - A dict of string/value properties that will be passed
-        to the {class_str} constructor
-
-        Supported dict properties:
-            {constructor_params_str}"""
+        to the {class_str} constructor"""
         ).format(
             plotly_name=self.plotly_name,
             class_str=self.data_class_str,
             module_str=self.module_str,
-            constructor_params_str=self.data_docs,
         )
 
         return desc
@@ -2560,15 +2545,11 @@ def description(self):
     {class_str} that may be specified as:
       - A list or tuple of instances of {module_str}.{class_str}
       - A list or tuple of dicts of string/value properties that
-        will be passed to the {class_str} constructor
-
-        Supported dict properties:
-            {constructor_params_str}"""
+        will be passed to the {class_str} constructor"""
         ).format(
             plotly_name=self.plotly_name,
             class_str=self.data_class_str,
             module_str=self.module_str,
-            constructor_params_str=self.data_docs,
         )
 
         return desc

_plotly_utils/colors/__init__.py

@@ -73,6 +73,7 @@
 Be careful! If you have a lot of unique numbers in your color column you will
 end up with a colormap that is massive and may slow down graphing performance.
 """
+
 import decimal
 from numbers import Number
 

codegen/__init__.py

@@ -26,6 +26,10 @@
     get_data_validator_instance,
 )
 
+# Target Python version for code formatting with Black.
+# Must be one of the values listed in pyproject.toml.
+BLACK_TARGET_VERSIONS = "py38 py39 py310 py311 py312"
+
 
 # Import notes
 # ------------
@@ -85,7 +89,7 @@ def preprocess_schema(plotly_schema):
         items["colorscale"] = items.pop("concentrationscales")
 
 
-def perform_codegen():
+def perform_codegen(reformat=True):
     # Set root codegen output directory
     # ---------------------------------
     # (relative to project root)
@@ -267,36 +271,24 @@ def perform_codegen():
         root_datatype_imports.append(f"._deprecations.{dep_clas}")
 
     optional_figure_widget_import = f"""
-if sys.version_info < (3, 7) or TYPE_CHECKING:
-    try:
-        import ipywidgets as _ipywidgets
-        from packaging.version import Version as _Version
-        if _Version(_ipywidgets.__version__) >= _Version("7.0.0"):
-            from ..graph_objs._figurewidget import FigureWidget
-        else:
-            raise ImportError()
-    except Exception:
-        from ..missing_anywidget import FigureWidget
-else:
-    __all__.append("FigureWidget")
-    orig_getattr = __getattr__
-    def __getattr__(import_name):
-        if import_name == "FigureWidget":
-            try:
-                import ipywidgets
-                from packaging.version import Version
-
-                if Version(ipywidgets.__version__) >= Version("7.0.0"):
-                    from ..graph_objs._figurewidget import FigureWidget
-
-                    return FigureWidget
-                else:
-                    raise ImportError()
-            except Exception:
-                from ..missing_anywidget import FigureWidget
+__all__.append("FigureWidget")
+orig_getattr = __getattr__
+def __getattr__(import_name):
+    if import_name == "FigureWidget":
+        try:
+            import ipywidgets
+            from packaging.version import Version
+
+            if Version(ipywidgets.__version__) >= Version("7.0.0"):
+                from ..graph_objs._figurewidget import FigureWidget
                 return FigureWidget
+            else:
+                raise ImportError()
+        except Exception:
+            from ..missing_anywidget import FigureWidget
+            return FigureWidget
 
-        return orig_getattr(import_name)
+    return orig_getattr(import_name)
 """
     # ### __all__ ###
     for path_parts, class_names in alls.items():
@@ -337,9 +329,15 @@ def __getattr__(import_name):
         f.write(graph_objects_init_source)
 
     # ### Run black code formatter on output directories ###
-    subprocess.call(["black", "--target-version=py36", validators_pkgdir])
-    subprocess.call(["black", "--target-version=py36", graph_objs_pkgdir])
-    subprocess.call(["black", "--target-version=py36", graph_objects_path])
+    if reformat:
+        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")
 
 
 if __name__ == "__main__":

codegen/compatibility.py

@@ -89,7 +89,7 @@ def __init__(self, *args, **kwargs):
         {depr_msg}
         \"\"\"
         warnings.warn(\"\"\"{depr_msg}\"\"\", DeprecationWarning)
-        super({class_name}, self).__init__(*args, **kwargs)\n\n\n"""
+        super().__init__(*args, **kwargs)\n\n\n"""
         )
 
     # Return source string