Merge branch 'main' into rm/use-native-legend

Author: emilykl

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

@@ -29,6 +29,7 @@ jobs:
         cd js
         npm ci
         npm run build
+        npm ls
     - name: Check JupyterLab build artifacts
       run: |
         # 1. Hash contents of all static files, sort by content hash

CHANGELOG.md

@@ -4,12 +4,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+## [6.3.0] - 2025-08-12
+
 ### Updated
-- Updated Plotly.js from version 3.0.1 to version 3.0.3. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#303----2025-07-23) for more information.
+- Updated Plotly.js from version 3.0.1 to version 3.1.0. See the plotly.js [release notes](https://github.com/plotly/plotly.js/releases) for more information. [[#5318](https://github.com/plotly/plotly.py/pull/5318)]
 
 ### Added
 - Exposed `plotly.io.get_chrome()` as a function which can be called from within a Python script. [[#5282](https://github.com/plotly/plotly.py/pull/5282)]
 
+### Fixed
+- Resolved issue causing extraneous engine deprecation warnings [[#5287](https://github.com/plotly/plotly.py/pull/5287)], with thanks to @jdbeel for the contribution!
+
 ## [6.2.0] - 2025-06-26
 
 ### Added

CITATION.cff

@@ -9,7 +9,8 @@ authors:
 - family-names: "Parmer"
   given-names: "Chris"
 title: "An interactive, open-source, and browser-based graphing library for Python"
-version: 5.24.1
+version: 6.3.0
 doi: 10.5281/zenodo.14503524
-date-released: 2024-09-12
+date-released: 2025-08-12
 url: "https://github.com/plotly/plotly.py"
+

CONTRIBUTING.md

@@ -120,6 +120,20 @@ you can install all packages with:
 pip install -e '.[dev]'
 ```
 
+If you're testing local changes in Jupyter Lab or Jupyter Notebook, you'll want to run these commands when you're setting up your development environment:
+```bash
+pip install jupyter
+jupyter labextension develop .
+```
+If you don't run that command, your figure will not render in the Jupyter Lab/ Jupyter Notebook editors. 
+
+If you're changing any of the code under the `js/` directory, you'll also want to run these commands:
+```
+cd js/
+npm ci
+npm run build
+```
+
 These commands also create an *editable install* of plotly.py
 so that you can test your changes iteratively without having to rebuild the plotly.py package explicitly;
 for more information please see

codegen/datatypes.py

@@ -10,6 +10,10 @@
     "choroplethmapbox",
     "densitymapbox",
 ]
+locationmode_traces = [
+    "choropleth",
+    "scattergeo",
+]
 
 
 def get_typing_type(plotly_type, array_ok=False):
@@ -100,6 +104,7 @@ def build_datatype_py(node):
 
     if (
         node.name_property in deprecated_mapbox_traces
+        or node.name_property in locationmode_traces
         or node.name_property == "template"
     ):
         buffer.write("import warnings\n")
@@ -341,6 +346,27 @@ def __init__(self"""
 constructor must be a dict or
 an instance of :class:`{class_name}`\"\"\")
 
+        """
+    )
+
+    # Add warning for 'country names' locationmode
+    if node.name_property in locationmode_traces:
+        buffer.write(
+            f"""
+        if locationmode == "country names" and kwargs.get("_validate"):
+            warnings.warn(
+                "The library used by the *country names* `locationmode` option is changing in an upcoming version. "
+                "Country names in existing plots may not work in the new version. "
+                "To ensure consistent behavior, consider setting `locationmode` to *ISO-3*.",
+                DeprecationWarning,
+                stacklevel=5,
+            )
+
+            """
+        )
+
+    buffer.write(
+        f"""
         self._skip_invalid = kwargs.pop("skip_invalid", False)
         self._validate = kwargs.pop("_validate", True)
         """

codegen/resources/plot-schema.json

@@ -296,8 +296,8 @@ def update_plotlyjs_dev(args, outdir):
     perform_codegen(outdir)
 
 
-def parse_args():
-    """Parse command-line arguments."""
+def make_parser():
+    """Make argument parser."""
 
     parser = argparse.ArgumentParser()
     subparsers = parser.add_subparsers(dest="cmd", help="Available subcommands")
@@ -322,6 +322,11 @@ def parse_args():
 
     subparsers.add_parser("updateplotlyjs", help="update plotly.js")
 
+    return parser
+
+
+def parse_args(parser: argparse.ArgumentParser):
+    """Parse command line arguments."""
     return parser.parse_args()
 
 
@@ -331,7 +336,8 @@ def main():
     project_root = os.path.dirname(os.path.realpath(__file__))
     outdir = os.path.join(project_root, "plotly")
 
-    args = parse_args()
+    parser = make_parser()
+    args = parse_args(parser)
 
     if args.cmd == "codegen":
         perform_codegen(outdir, noformat=args.noformat)
@@ -350,6 +356,10 @@ def main():
         print(version)
         update_plotlyjs(version, outdir)
 
+    elif args.cmd is None:
+        parser.print_help()
+        sys.exit(1)
+
     else:
         print(f"unknown command {args.cmd}", file=sys.stderr)
         sys.exit(1)

commands.py

@@ -24,7 +24,7 @@
 # The short X.Y version
 version = ""
 # The full version, including alpha/beta/rc tags
-release = "6.2.0"
+release = "6.3.0"
 
 
 # -- General configuration ---------------------------------------------------

doc/apidoc/conf.py

@@ -154,6 +154,8 @@ Whereas the previous example used the default `intensitymode='vertex'`, we plot
 
 ```python
 import plotly.graph_objects as go
+import numpy as np
+
 fig = go.Figure(data=[
     go.Mesh3d(
         # 8 vertices of a cube

doc/python/3d-mesh.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.16.3
+      jupytext_version: 1.17.2
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.14
+    version: 3.9.0
   plotly:
     description: How to adjust axes properties in Python - axes titles, styling and
       coloring axes and grid lines, ticks, tick labels and more.
@@ -118,7 +118,7 @@ The PX `labels` argument can also be used without a data frame argument:
 
 ```python
 import plotly.express as px
-fig = px.bar(df, x=["Apples", "Oranges"], y=[10,20], color=["Here", "There"],
+fig = px.bar(x=["Apples", "Oranges"], y=[10,20], color=["Here", "There"],
     labels=dict(x="Fruit", y="Amount", color="Place")
 )
 fig.show()
@@ -460,6 +460,7 @@ Here, `ticklabelstandoff=15` moves the labels 15 pixels further away from the x-
 
 ```python
 import plotly.express as px
+import pandas as pd
 
 df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
 
@@ -487,6 +488,7 @@ To draw the label for the minor tick before each major tick, set `ticklabelindex
 
 ```python
 import plotly.express as px
+import pandas as pd
 
 df = pd.read_csv('https://raw.githubusercontent.com/plotly/datasets/master/finance-charts-apple.csv')
 
@@ -619,6 +621,38 @@ fig.update_yaxes(zeroline=True, zerolinewidth=2, zerolinecolor='LightPink')
 fig.show()
 ```
 
+##### Controlling Zero Line Layer
+
+*New in 6.3*
+
+By default, zero lines are displayed below traces. Set `zerolinelayer="above traces"` on an axis to display its zero line above traces:
+
+```python
+import plotly.graph_objects as go
+
+x = ['A', 'B', 'C', 'D', 'A']
+y = [2, 0, 4, -3, 2]
+
+fig = go.Figure(
+    data=[
+        go.Scatter(
+            x=x,
+            y=y,
+            fill='toself',
+            mode='none',
+            fillcolor='lightpink'
+        )
+    ],
+    layout=dict(
+        yaxis=dict(
+            zerolinelayer="above traces"  # Change to "below traces" to see the difference
+        ),
+    )
+)
+
+fig.show()
+```
+
 #### Setting the Range of Axes Manually
 
 The visible x and y axis range can be configured manually by setting the `range` axis property to a list of two values, the lower and upper bound.