Merge branch 'docs-update-next-release' of https://github.com/plotly/plotly.py into docs-update-next-release

Author: LiamConnors

CHANGELOG.md

@@ -2,6 +2,14 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unreleased
+
+### 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.
+
+### 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)]
+
 ## [6.2.0] - 2025-06-26
 
 ### Added

commands.py

@@ -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()

doc/python/choropleth-maps.md

@@ -214,7 +214,7 @@ In **Plotly.py 6.3 and later**, the built-in countries geometry is created from
 - [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, and land layers.
 - Natural Earth data for oceans, lakes, rivers, and subunit layers.
 
-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 defacto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
+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).
 

doc/python/figurewidget.md

@@ -22,7 +22,7 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.6.5
   plotly:
-    description: Introduction to the new Plotly FigureWidget
+    description: Introduction to the Plotly FigureWidget
     display_as: chart_events
     language: python
     layout: base
@@ -34,6 +34,12 @@ jupyter:
     redirect_from: /python/ipython-widgets/
 ---
 
+The Plotly FigureWidget allows you to add Plotly charts as interactive widgets in Jupyter and other compatible notebooks. To use the FigureWidget, you'll need to install `anywidget`: 
+
+```bash
+pip install anywidget
+```
+
 #### Create a Simple FigureWidget
 Create an empty FigureWidget and then view it.
 

doc/python/line-and-scatter.md

@@ -284,6 +284,144 @@ fig.update_traces(textposition="bottom right")
 fig.show()
 ```
 
+### Swarm (or Beeswarm) Plots 
+
+Swarm plots show the distribution of values in a column by giving each entry one dot and adjusting the y-value so that dots do not overlap and appear symmetrically around the y=0 line. They complement [histograms](https://plotly.com/python/histograms/), [box plots](https://plotly.com/python/box-plots/), and [violin plots](https://plotly.com/python/violin/). This example could be generalized to implement a swarm plot for multiple categories by adjusting the y-coordinate for each category.
+
+```python
+import pandas as pd
+import plotly.express as px
+import collections
+
+
+def negative_1_if_count_is_odd(count):
+    # if this is an odd numbered entry in its bin, make its y coordinate negative
+    # the y coordinate of the first entry is 0, so entries 3, 5, and 7 get 
+    # negative y coordinates
+    if count % 2 == 1:
+        return -1
+    else:
+        return 1
+
+
+def swarm(
+    X_series,
+    fig_title,
+    point_size=16,
+    fig_width=800,
+    gap_multiplier=1.2,
+    bin_fraction=0.95,  # slightly undersizes the bins to avoid collisions
+):
+    # sorting will align columns in attractive c-shaped arcs rather than having 
+    # columns that vary unpredictably in the x-dimension.
+    # We also exploit the fact that sorting means we see bins sequentially when 
+    # we add collision prevention offsets.
+    X_series = X_series.copy().sort_values()
+
+    # we need to reason in terms of the marker size that is measured in px
+    # so we need to think about each x-coordinate as being a fraction of the way from the
+    # minimum X value to the maximum X value
+    min_x = min(X_series)
+    max_x = max(X_series)
+
+    list_of_rows = []
+    # we will count the number of points in each "bin" / vertical strip of the graph
+    # to be able to assign a y-coordinate that avoids overlapping
+    bin_counter = collections.Counter()
+
+    for x_val in X_series:
+        # assign this x_value to bin number
+        # each bin is a vertical strip slightly narrower than one marker
+        bin = (((fig_width*bin_fraction*(x_val-min_x))/(max_x-min_x)) // point_size)
+
+        # update the count of dots in that strip
+        bin_counter.update([bin])
+
+        # remember the "y-slot" which tells us the number of points in this bin and is sufficient to compute the y coordinate unless there's a collision with the point to its left
+        list_of_rows.append(
+            {"x": x_val, "y_slot": bin_counter[bin], "bin": bin})
+
+    # iterate through the points and "offset" any that are colliding with a 
+    # point to their left apply the offsets to all subsequent points in the same bin.
+    # this arranges points in an attractive swarm c-curve where the points 
+    # toward the edges are (weakly) further right.
+    bin = 0
+    offset = 0
+    for row in list_of_rows:
+        if bin != row["bin"]:
+            # we have moved to a new bin, so we need to reset the offset
+            bin = row["bin"]
+            offset = 0
+        # see if we need to "look left" to avoid a possible collision
+        for other_row in list_of_rows:
+            if (other_row["bin"] == bin-1):
+                # "bubble" the entry up until we find a slot that avoids a collision
+                while ((other_row["y_slot"] == row["y_slot"]+offset)
+                       and (((fig_width*(row["x"]-other_row["x"]))/(max_x-min_x)
+                              // point_size) < 1)):
+                    offset += 1
+                    # update the bin count so we know whether the number of 
+                    # *used* slots is even or odd
+                    bin_counter.update([bin])
+
+        row["y_slot"] += offset
+        # The collision free y coordinate gives the items in a vertical bin
+        # y-coordinates to evenly spread their locations above and below the 
+        # y-axis (we'll make a correction below to deal with even numbers of 
+        # entries).  For now, we'll assign 0, 1, -1, 2, -2, 3, -3 ... and so on.
+        # We scale this by the point_size*gap_multiplier to get a y coordinate 
+        # in px.
+        row["y"] = (row["y_slot"]//2) * \
+            negative_1_if_count_is_odd(row["y_slot"])*point_size*gap_multiplier
+
+    # if the number of points is even, move y-coordinates down to put an equal 
+    # number of entries above and below the axis
+    for row in list_of_rows:
+        if bin_counter[row["bin"]] % 2 == 0:
+            row["y"] -= point_size*gap_multiplier/2
+
+    df = pd.DataFrame(list_of_rows)
+    # One way to make this code more flexible to e.g. handle multiple categories
+    # would be to return a list of "swarmified" y coordinates here and then plot
+    # outside the function.
+    # That generalization would let you "swarmify" y coordinates for each 
+    # category and add category specific offsets to put the each category in its 
+    # own row
+
+    fig = px.scatter(
+        df,
+        x="x",
+        y="y",
+        title=fig_title,
+    )
+    # we want to suppress the y coordinate in the hover value because the 
+    # y-coordinate is irrelevant/misleading
+    fig.update_traces(
+        marker_size=point_size,
+        # suppress the y coordinate because the y-coordinate is irrelevant
+        hovertemplate="<b>value</b>: %{x}",
+    )
+    # we have to set the width and height because we aim to avoid icon collisions
+    # and we specify the icon size in the same units as the width and height
+    fig.update_layout(width=fig_width, height=(
+        point_size*max(bin_counter.values())+200))
+    fig.update_yaxes(
+        showticklabels=False,  # Turn off y-axis labels
+        ticks='',               # Remove the ticks
+        title=""
+    )
+    return fig
+
+
+df = px.data.iris()  # iris is a pandas DataFrame
+fig = swarm(df["sepal_length"], "Sepal length distribution from 150 iris samples")
+# The iris data set entries are rounded so there are no collisions.
+# a more interesting test case for collision avoidance is:
+# fig = swarm(pd.Series([1, 1.5, 1.78, 1.79, 1.85, 2,
+#            2, 2, 2, 3, 3, 2.05, 2.1, 2.2, 2.5, 12]))
+fig.show()
+```
+
 ## Scatter and line plots with go.Scatter
 
 If Plotly Express does not provide a good starting point, it is possible to use [the more generic `go.Scatter` class from `plotly.graph_objects`](/python/graph-objects/). Whereas `plotly.express` has two functions `scatter` and `line`, `go.Scatter` can be used both for plotting points (makers) or lines, depending on the value of `mode`. The different options of `go.Scatter` are documented in its [reference page](https://plotly.com/python/reference/scatter/).

doc/python/map-configuration.md

@@ -51,13 +51,13 @@ Geo maps are outline-based maps. If your figure is created with a `px.scatter_ge
 
 ### Physical Base Maps
 
-Plotly Geo maps have a built-in base map layer composed of "physical" and "cultural" (i.e. administrative border) data.
+Plotly Geo maps have a built-in base map layer composed of *physical* and *cultural* (i.e. administrative border) data.
 
 In **Plotly.py 6.3 and later**, the base map layer is created from the following sources:
 - [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, coastlines, and land layers.
 - Natural Earth data for oceans, lakes, rivers, and subunit layers.
 
-In **earlier versions of Plotly.py**, the base map layer is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to defacto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
+In **earlier versions of Plotly.py**, the base map layer 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/).
 
 Various lines and area fills can be shown or hidden, and their color and line-widths specified. In the [default `plotly` template](/python/templates/), a map frame and physical features such as a coastal outline and filled land areas are shown, at a small-scale 1:110m resolution:
 
@@ -112,7 +112,7 @@ In addition to physical base map features, a "cultural" base map is included whi
 
 In **Plotly.py 6.3 and later**, this base map is created from [UN data](https://geoportal.un.org/arcgis/sharing/rest/content/items/d7caaff3ef4b4f7c82689b7c4694ad92/data) for country borders, and Natural Earth data for sub-country borders.
 
-In **earlier versions of Plotly.py**, this base map is based only on Natural Earth data. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to defacto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
+In **earlier versions of Plotly.py**, this base map is based on Natural Earth data only. Plotly includes data from Natural Earth "as-is". This dataset draws boundaries of countries according to defacto status. See the [Natural Earth page for more details](https://www.naturalearthdata.com/downloads/50m-cultural-vectors/50m-admin-0-countries-2/).
 
 **To create a map with your own cultural features** please refer to our [choropleth documentation](/python/choropleth-maps/).
 

doc/python/static-image-export.md

@@ -64,12 +64,12 @@ Plotly also provides a CLI for installing Chrome from the command line.
 
 Run `plotly_get_chrome` to install Chrome.
 
-You can also install Chrome from within Python using `plotly.io.install_chrome()`
+You can also install Chrome from Python using `plotly.io.get_chrome()`
 
 ```python
 import plotly.io as pio
 
-pio.install_chrome()
+pio.get_chrome()
 ```
 
 See the **Additional Information on Browsers with Kaleido** section below for more details on browser compatibility for Kaleido.
@@ -273,6 +273,8 @@ The following settings are available.
 
 `mathjax`: Location of the MathJax bundle needed to render LaTeX characters. Defaults to a CDN location. If fully offline export is required, set this to a local MathJax bundle.
 
+`plotlyjs`: Location of the Plotly.js bundle to use. Can be a local file path or URL. By default, Kaleido uses the Plotly.js bundle included with Plotly.py.
+
 `topojson`: Location of the topojson files needed to render choropleth traces. Defaults to a CDN location. If fully offline export is required, set this to a local directory containing the Plotly.js topojson files.
 
 `mapbox_access_token`: The default Mapbox access token (Kaleido v0 only). Mapbox traces are deprecated. See the [MapLibre Migration](https://plotly.com/python/mapbox-to-maplibre/) page for more details.

doc/python/text-and-annotations.md

@@ -789,6 +789,11 @@ This example shows how to add a note about the data source or interpretation at
 ```python
 import plotly.express as px
 df = px.data.iris()
+
+fig = px.scatter(df, x="sepal_width", y="sepal_length", color="species",
+                 size='petal_length', hover_data=['petal_width'])
+
+
 fig.update_layout(
         title=dict(text="Note: this is the Plotly title element.",
                  # keeping this title string short avoids getting the text cut off in small windows

doc/python/tile-county-choropleth.md

@@ -22,7 +22,7 @@ jupyter:
     pygments_lexer: ipython3
     version: 3.10.0
   plotly:
-    description: How to make a choropleth map of US counties in Python with Plotly.
+    description: How to make tile choropleth maps in Python with Plotly.
     display_as: maps
     language: python
     layout: base
@@ -254,4 +254,4 @@ fig.show()
 
 See [function reference for `px.choropleth_map`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth_map) or https://plotly.com/python/reference/choroplethmap/ for more information about the attributes available.
 
-For Mapbox-based tile maps, see [function reference for `px.choropleth_mapbox`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth_mapbox) or https://plotly.com/python/reference/choroplethmapbox/.
+For (deprecated) Mapbox-based tile maps, see [function reference for `px.choropleth_mapbox`](https://plotly.com/python-api-reference/generated/plotly.express.choropleth_mapbox) or https://plotly.com/python/reference/choroplethmapbox/.