Merge branch 'main' into marthacryan-patch-1

Author: marthacryan

CHANGELOG.md

@@ -2,6 +2,19 @@
 All notable changes to this project will be documented in this file.
 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.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"
+

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

@@ -244,27 +244,10 @@ def update_plotlyjs(plotly_js_version, outdir):
 
 
 # FIXME: switch to argparse
-def update_schema_bundle_from_master():
+def update_schema_bundle_from_master(args):
     """Update the plotly.js schema and bundle from master."""
-
-    if "--devrepo" in sys.argv:
-        devrepo = sys.argv[sys.argv.index("--devrepo") + 1]
-    else:
-        devrepo = "plotly/plotly.js"
-
-    if "--devbranch" in sys.argv:
-        devbranch = sys.argv[sys.argv.index("--devbranch") + 1]
-    else:
-        devbranch = "master"
-
-    if "--local" in sys.argv:
-        local = sys.argv[sys.argv.index("--local") + 1]
-    else:
-        local = None
-
-    if local is None:
-        build_info = get_latest_publish_build_info(devrepo, devbranch)
-
+    if args.local is None:
+        build_info = get_latest_publish_build_info(args.devrepo, args.devbranch)
         archive_url, bundle_url, schema_url = get_bundle_schema_urls(
             build_info["build_num"]
         )
@@ -275,14 +258,14 @@ def update_schema_bundle_from_master():
         # Update schema in package data
         overwrite_schema(schema_url)
     else:
-        # this info could be more informative but
-        # it doesn't seem as useful in a local context
-        # and requires dependencies and programming.
+        # this info could be more informative but it doesn't seem as
+        # useful in a local context and requires dependencies and
+        # programming.
         build_info = {"vcs_revision": "local", "committer_date": str(time.time())}
-        devrepo = local
-        devbranch = ""
+        args.devrepo = args.local
+        args.devbranch = ""
 
-        archive_uri, bundle_uri, schema_uri = get_bundle_schema_local(local)
+        archive_uri, bundle_uri, schema_uri = get_bundle_schema_local(args.local)
         overwrite_bundle_local(bundle_uri)
         overwrite_schema_local(schema_uri)
 
@@ -293,23 +276,23 @@ def update_schema_bundle_from_master():
 
     # Replace version with bundle url
     package_json["dependencies"]["plotly.js"] = (
-        archive_url if local is None else archive_uri
+        archive_url if args.local is None else archive_uri
     )
     with open(package_json_path, "w") as f:
         json.dump(package_json, f, indent=2)
 
     # update plotly.js version in _plotlyjs_version
     rev = build_info["vcs_revision"]
     date = str(build_info["committer_date"])
-    version = "_".join([devrepo, devbranch, date[:10], rev[:8]])
+    version = "_".join([args.devrepo, args.devbranch, date[:10], rev[:8]])
     overwrite_plotlyjs_version_file(version)
-    install_js_deps(local)
+    install_js_deps(args.local)
 
 
-def update_plotlyjs_dev(outdir):
+def update_plotlyjs_dev(args, outdir):
     """Update project to a new development version of plotly.js."""
 
-    update_schema_bundle_from_master()
+    update_schema_bundle_from_master(args)
     perform_codegen(outdir)
 
 
@@ -328,7 +311,14 @@ def parse_args():
 
     subparsers.add_parser("format", help="reformat code")
 
-    subparsers.add_parser("updateplotlyjsdev", help="update plotly.js for development")
+    p_update_dev = subparsers.add_parser(
+        "updateplotlyjsdev", help="update plotly.js for development"
+    )
+    p_update_dev.add_argument(
+        "--devrepo", default="plotly/plotly.js", help="repository"
+    )
+    p_update_dev.add_argument("--devbranch", default="master", help="branch")
+    p_update_dev.add_argument("--local", default=None, help="local path")
 
     subparsers.add_parser("updateplotlyjs", help="update plotly.js")
 
@@ -353,7 +343,7 @@ def main():
         lint_code(outdir)
 
     elif args.cmd == "updateplotlyjsdev":
-        update_plotlyjs_dev(outdir)
+        update_plotlyjs_dev(args, outdir)
 
     elif args.cmd == "updateplotlyjs":
         version = plotly_js_version()

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.

doc/python/axes.md

@@ -448,6 +448,7 @@ fig.show()
 
 ```python
 import plotly.graph_objects as go
+import numpy as np
 
 x_data = ['Carmelo Anthony', 'Dwyane Wade',
           'Deron Williams', 'Brook Lopez',

doc/python/box-plots.md

@@ -208,15 +208,16 @@ fig.show()
 Plotly comes with two built-in geometries which do not require an external GeoJSON file:
 
 1. USA States
-2. Countries as defined in the Natural Earth dataset.
+2. Countries
 
-**Note and disclaimer:** cultural (as opposed to physical) features are by definition subject to change, debate and dispute. Plotly includes data from Natural Earth "as-is" and defers to the [Natural Earth policy regarding disputed borders](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/) which read:
+In **Plotly.py 6.3 and later**, the built-in countries geometry is created from the following sources:
+- [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, land, and ocean layers.
+- Natural Earth data for lakes, rivers, and subunits layers.
 
-> Natural Earth Vector draws boundaries of countries according to defacto status. We show who actually controls the situation on the ground.
+In **earlier versions of Plotly.py**, the built-in countries geometry is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to de facto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
 
 To use the built-in countries geometry, provide `locations` as [three-letter ISO country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
 
-
 ```python
 import plotly.express as px