Merge branch 'main' into doc-prod-to-main-merge

Author: LiamConnors

.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,10 +4,23 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+## [6.3.1] - 2025-10-02
+
+### Updated
+- Update Plotly.js from version 3.1.0 to version 3.1.1. See the Plotly.js [release notes](https://github.com/plotly/plotly.js/releases) for more information. [[#5357](https://github.com/plotly/plotly.py/pull/5357)]. Notable changes include:
+  - Fix issue preventing Scattergl plots with text elements from rendering [[plotly.js#7563](https://github.com/plotly/plotly.js/pull/7563)]
+- Use native legends when converting from matplotlib [[#5312](https://github.com/plotly/plotly.py/pull/5312)], with thanks to @robertoffmoura to the contribution!
+- Allow `shared_yaxes` to work with secondary axes [[#5180](https://github.com/plotly/plotly.py/pull/5180)], with thanks to @gmjw for the contribution!
+
+### Fixed
+- Fix issue where width/height in plot layout were not respected during Kaleido image export [[#5325](https://github.com/plotly/plotly.py/pull/5325)]
+- Fix typo in default argument to `_ternary_contour.py` [[#5315](https://github.com/plotly/plotly.py/pull/5315)], with thanks to @Lexachoc for the contribution!
+- Fix incorrect `fig.show()` behavior when `ipython` is installed [[#5258](https://github.com/plotly/plotly.py/pull/5258)]
+
 ## [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)]
+- 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)]

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.1
 doi: 10.5281/zenodo.14503524
-date-released: 2024-09-12
+date-released: 2025-10-02
 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

RELEASE.md

@@ -3,7 +3,7 @@
 
 ## Release process - full release of `plotly` package
 
-This is the release process for releasing `plotly.py` version `X.Y.Z`, including changelogs, Github release and forum announcement.
+This is the release process for releasing plotly.py version `X.Y.Z`, including changelogs, GitHub release and forum announcement.
 
 ### Finalize changelog
 
@@ -18,54 +18,99 @@ been updated, include this as the first `Updated` entry. Call out any
 notable changes as sub-bullets (new trace types in particular), and provide
 a link to the plotly.js CHANGELOG.
 
-### Finalize versions
+### Update version numbers
+
+**Create a release branch `git checkout -b release-X.Y.Z` _from the tip of `origin/main`_.**
+
+- Manually update the versions to `X.Y.Z` in the files specified below:
+  - `pyproject.toml`
+    - update version
+  - `CHANGELOG.md`
+    - update version and release date
+    - finalize changelog entries according to instructions above
+  - `CITATION.cff`
+    - update version and release date
+- Run `uv lock` to update the version number in the `uv.lock` file (do not update manually)
+- Commit and push your changes to the release branch:
+    ```sh
+    $ git add -u
+    $ git commit -m "version changes for vX.Y.Z"
+    $ git push
+    ```
+- Create a GitHub pull request from `release-X.Y.Z` to `main` and wait for CI to be green
+- On the release branch, create and push a tag for the release:
+    ```sh
+    $ git tag vX.Y.Z
+    $ git push origin vX.Y.Z
+    ```
+
+### Manual QA in Jupyter
+
+We don't currently have automated tests for Jupyter, so we do this QA step manually.
+
+The `full_build` job in the `release_build` workflow in CircleCI produces a tarball of artifacts `output.tgz` 
+which you should download and decompress, which will give you a directory called `output`. The filenames within 
+will contain version numbers; make sure the version numbers are correct.
+
+Set up an environment with Jupyter, AnyWidget, and Pandas installed (`pip install jupyter anywidget pandas`). Then:
+
+- unzip downloaded `output.tgz`
+- `pip uninstall plotly`
+- `pip install path/to/output/dist/plotly-X.Y.Z-py3-none-any.whl`
+
+You'll want to check, in both JupyterLab (launch with `jupyter lab`) and Jupyter Notebook (launch with `jupyter notebook`), 
+that `go.Figure()` and `go.FigureWidget()` work as expected. 
 
-**Create a branch `git checkout -b release-X.Y.Z` *from the tip of `origin/main`*.**
+Notes:
+- **Start by creating a brand new notebook each time** so that there is no caching of previous results
+- **Do not run the Jupyter commands from the root `plotly.py/` directory on your machine** because Jupyter may be confused 
+by metadata from previous plotly.py builds
 
-Manually update the versions to `X.Y.Z` in the files specified below.
+Code for testing `go.Figure()`:
+```python
+import plotly
+import plotly.graph_objects as go
 
- - `pyproject.toml`
-   + update version
- - `CHANGELOG.md`
-   + update the release date
- - Commit your changes on the branch:
-   + `git commit -a -m "version changes for vX.Y.Z"`
- - Create a tag for Github release
-   + `git tag vX.Y.Z`
-   + `git push --atomic origin release-X.Y.Z vX.Y.Z`
- - Create a Github pull request from `release-X.Y.Z` to `main` and wait for CI to be green
+print(plotly.__version__)  # Make sure version is correct
+fig = go.Figure(data=go.Scatter(x=[1, 2, 3, 4], y=[1, 3, 2, 4]))
+fig.show()  # Figure should render in notebook
+```
 
-### Download and QA CI Artifacts
+Code for testing `go.FigureWidget()`:
+```python
+import plotly
+import plotly.graph_objects as go
 
-The `full_build` job in the `release_build` workflow in CircleCI produces a tarball of artifacts `output.tgz` which you should download and decompress, which will give you a directory called `output`. The filenames contained within will contain version numbers.
+print(plotly.__version__)  # Make sure version is correct
+fig = go.Figure(data=go.Scatter(x=[1, 2, 3, 4], y=[1, 3, 2, 4]))
+figure_widget = go.FigureWidget(fig)
+figure_widget  # Figure should render in notebook
+```
 
-To locally install the PyPI dist, make sure you have an environment with JupyterLab installed (maybe one created with `conda create -n condatest python=3.10 jupyter anywidget pandas`):
+Once these are verified working, you can move on to publishing the release.
 
-- `tar xzf output.tgz`
-- `pip uninstall plotly`
-- `conda uninstall plotly` (just in case!)
-- `pip install path/to/output/dist/plotly-X.Y.X-py3-none-any.whl`
+### Merge the release PR and make a GitHub release
 
-You'll want to check, in both Lab and Notebook, **in a brand new notebook in each** so that there is no caching of previous results, that `go.Figure()` and `go.FigureWidget()` work without error.
+- Merge the pull request you created above into `main`
+- Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
+- Enter the `vX.Y.Z` tag you created already above and make "Release title" the same string as the tag.
+- Copy the changelog section for this version into "Describe this release"
+- Upload the build artifacts downloaded in the previous step (`.tar` and `.whl`)
 
-### Publishing
+### Publishing to PyPI
 
-Once you're satisfied that things render in Lab and Notebook in Widget and regular mode,
-you can publish the artifacts. **You will need special credentials from Plotly leadership to do this.**.
+The final step is to publish the release to PyPI. **You will need special permissions from Plotly leadership to do this.**.
 
+You must install first install [Twine](https://pypi.org/project/twine/) (`pip install twine`) if not already installed.
 
 Publishing to PyPI:
 ```bash
 (plotly_dev) $ cd path/to/output
 (plotly_dev) $ twine upload plotly-X.Y.Z*
 ```
 
-### Merge the PR and make a Release
-
-1. Merge the pull request you created above into `main`
-2. Go to https://github.com/plotly/plotly.py/releases and "Draft a new release"
-3. Enter the `vX.Y.Z` tag you created already above and make "Release title" the same string as the tag.
-4. Copy the changelog section for this version as the "Describe this release"
+You will be prompted to enter an API token; this can be generated in your PyPI account settings. 
+Your account must have permissions to publish to the `plotly` project on PyPI.
 
 ### Update documentation site
 
@@ -76,18 +121,18 @@ Publishing to PyPI:
 start by doing it first if not. Then merge `main` into `doc-prod` to deploy the doc related
 to features in the release.
 3. in a clone of the [`graphing-library-docs` repo](https://github.com/plotly/graphing-library-docs):
-    1. bump the version of Plotly.py in  `_data/pyversion.json`
-    2. bump the version of Plotly.js with `cd _data && python get_plotschema.py <PLOTLY.JS VERSION>` fixing any errors that come up.
-      - If Plotly.js contains any new traces or trace or layout attributes, you'll get a warning `“missing key in attributes: <attribute-name>`. To resolve, add the attribute to the relevant section in `/_data/orderings.json` in the position you want it to appear in the reference docs.
+    1. bump the version of plotly.py in  `_data/pyversion.json`
+    2. bump the version of plotly.js with `cd _data && python get_plotschema.py <PLOTLY.JS VERSION>` fixing any errors that come up.
+      - If plotly.js contains any new traces or trace or layout attributes, you'll get a warning `“missing key in attributes: <attribute-name>`. To resolve, add the attribute to the relevant section in `/_data/orderings.json` in the position you want it to appear in the reference docs.
     3. rebuild the Algolia `schema` index with `ALGOLIA_API_KEY=<key> make update_ref_search`
     4. Rebuild the Algolia `python` index with `ALGOLIA_API_KEY=<key> make update_python_search`
     5. Commit and push the changes to `master` in that repo
 
 ### Notify Stakeholders
 
-* Post an announcement to the Plotly Python forum, with links to the README installation instructions and to the CHANGELOG.
+* Post an announcement to the [Plotly Python forum](https://community.plotly.com/c/plotly-python/5), with links to the README installation instructions and to the CHANGELOG.
 * Update the previous announcement to point to this one
-* Update the Github Release entry and CHANGELOG entry to have the nice title and a link to the announcement
+* Update the GitHub Release entry and CHANGELOG entry to have the nice title and a link to the announcement
 * Follow up on issues resolved in this release or forum posts with better answers as of this release
 
 ## Release process - Release *Candidate* of `plotly` package

codegen/resources/plot-schema.json

@@ -4008,7 +4008,7 @@
         "valType": "string"
        },
        "type": {
-        "description": "Sets the layer type, that is the how the layer data set in `source` will be rendered With `sourcetype` set to *geojson*, the following values are allowed: *circle*, *line*, *fill* and *symbol*. but note that *line* and *fill* are not compatible with Point GeoJSON geometries. With `sourcetype` set to *vector*, the following values are allowed:  *circle*, *line*, *fill* and *symbol*. With `sourcetype` set to *raster* or `*image*`, only the *raster* value is allowed.",
+        "description": "Sets the layer type, that is the how the layer data set in `source` will be rendered With `sourcetype` set to *geojson*, the following values are allowed: *circle*, *line*, *fill* and *symbol*. but note that *line* and *fill* are not compatible with Point GeoJSON geometries. With `sourcetype` set to *vector*, the following values are allowed:  *circle*, *line*, *fill* and *symbol*. With `sourcetype` set to *raster* or *image*, only the *raster* value is allowed.",
         "dflt": "circle",
         "editType": "plot",
         "valType": "enumerated",
@@ -4414,7 +4414,7 @@
         "valType": "string"
        },
        "type": {
-        "description": "Sets the layer type, that is the how the layer data set in `source` will be rendered With `sourcetype` set to *geojson*, the following values are allowed: *circle*, *line*, *fill* and *symbol*. but note that *line* and *fill* are not compatible with Point GeoJSON geometries. With `sourcetype` set to *vector*, the following values are allowed:  *circle*, *line*, *fill* and *symbol*. With `sourcetype` set to *raster* or `*image*`, only the *raster* value is allowed.",
+        "description": "Sets the layer type, that is the how the layer data set in `source` will be rendered With `sourcetype` set to *geojson*, the following values are allowed: *circle*, *line*, *fill* and *symbol*. but note that *line* and *fill* are not compatible with Point GeoJSON geometries. With `sourcetype` set to *vector*, the following values are allowed:  *circle*, *line*, *fill* and *symbol*. With `sourcetype` set to *raster* or *image*, only the *raster* value is allowed.",
         "dflt": "circle",
         "editType": "plot",
         "valType": "enumerated",
@@ -47932,7 +47932,7 @@
      "valType": "number"
     },
     "source": {
-     "description": "Specifies the data URI of the image to be visualized. The URI consists of \"data:image/[<media subtype>][;base64],<data>\"",
+     "description": "Specifies the data URI of the image to be visualized. The URI consists of \"data:image/[<media subtype\\\\>][;base64\\\\],<data\\\\>\"",
      "editType": "calc",
      "valType": "string"
     },
@@ -53288,7 +53288,7 @@
      ]
     },
     "hovertemplate": {
-     "description": "Template string used for rendering the information that appear on hover box. Note that this will override `hoverinfo`. Variables are inserted using %{variable}, for example \"y: %{y}\" as well as %{xother}, {%_xother}, {%_xother_}, {%xother_}. When showing info for several points, *xother* will be added to those with different x positions from the first point. An underscore before or after *(x|y)other* will add a space on that side, only when this field is shown. Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example \"Price: %{y:$.2f}\". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example \"Day: %{2019-01-01|%A}\". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax. The variables available in `hovertemplate` are the ones emitted as event data described at this link https://plotly.com/javascript/plotlyjs-events/#event-data. Additionally, every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.  This value here applies when hovering over dimensions. Note that `*categorycount`, *colorcount* and *bandcolorcount* are only available when `hoveron` contains the *color* flagFinally, the template string has access to variables `count`, `probability`, `category`, `categorycount`, `colorcount` and `bandcolorcount`. Anything contained in tag `<extra>` is displayed in the secondary box, for example `<extra>%{fullData.name}</extra>`. To hide the secondary box completely, use an empty tag `<extra></extra>`.",
+     "description": "Template string used for rendering the information that appear on hover box. Note that this will override `hoverinfo`. Variables are inserted using %{variable}, for example \"y: %{y}\" as well as %{xother}, {%_xother}, {%_xother_}, {%xother_}. When showing info for several points, *xother* will be added to those with different x positions from the first point. An underscore before or after *(x|y)other* will add a space on that side, only when this field is shown. Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example \"Price: %{y:$.2f}\". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example \"Day: %{2019-01-01|%A}\". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax. The variables available in `hovertemplate` are the ones emitted as event data described at this link https://plotly.com/javascript/plotlyjs-events/#event-data. Additionally, every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.  This value here applies when hovering over dimensions. Note that *categorycount*, *colorcount* and *bandcolorcount* are only available when `hoveron` contains the *color* flag. Finally, the template string has access to variables `count`, `probability`, `category`, `categorycount`, `colorcount` and `bandcolorcount`. Anything contained in tag `<extra>` is displayed in the secondary box, for example `<extra>%{fullData.name}</extra>`. To hide the secondary box completely, use an empty tag `<extra></extra>`.",
      "dflt": "",
      "editType": "plot",
      "valType": "string"

commands.py

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

doc/apidoc/plotly.figure_factory.rst

@@ -18,7 +18,7 @@
    create_distplot
    create_facet_grid
    create_gantt
-   create_hexbin_mapbox
+   create_hexbin_map
    create_ohlc
    create_quiver
    create_scatterplotmatrix