Merge branch 'doc-prod' into patch-2

Author: LiamConnors

.circleci/config.yml

@@ -52,3 +52,6 @@ doc/check-or-enforce-order.py
 packages/javascript/jupyterlab-plotly/lib/
 packages/python/plotly/jupyterlab_plotly/labextension/
 packages/python/plotly/jupyterlab_plotly/nbextension/index.js*
+
+test/percy/*.html
+test/percy/pandas2/*.html

.gitignore

@@ -2,6 +2,41 @@
 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 2.24.1 to version 2.24.2. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2242----2023-06-09) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module.
+- `px` methods now accept data-frame-like objects that support a [dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), such as polars, vaex, modin etc. This protocol has priority on `to_pandas` call, but will only be used if pandas>=2.0.2 is installed in the environment.
+
+## [5.15.0] - 2023-06-08
+
+### Updated
+  - Updated Plotly.js from version 2.20.0 to version 2.24.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2241----2023-06-07) for more information. Notable changes include:
+    - Add pattern to pie, funnelarea, sunburst, icicle and treemap traces [[#6601](https://github.com/plotly/plotly.js/pull/6601), [#6619](https://github.com/plotly/plotly.js/pull/6619), [#6622](https://github.com/plotly/plotly.js/pull/6622), [#6626](https://github.com/plotly/plotly.js/pull/6626), [#6627](https://github.com/plotly/plotly.js/pull/6627), [#6628](https://github.com/plotly/plotly.js/pull/6628), [#6629](https://github.com/plotly/plotly.js/pull/6629)], with thanks to @thierryVergult for the contribution!
+    - Add `texttemplate` to shape.label for parametric shapes i.e. line, rect and circle [[#6527](https://github.com/plotly/plotly.js/pull/6527)],
+   with thanks to the [Volkswagen](https://www.volkswagenag.com) Center of Excellence for Battery Systems for sponsoring development!
+    - Add strict option to custom bundle command [[#6557](https://github.com/plotly/plotly.js/pull/6557)],
+   with thanks to @CallumNZ for the contribution!
+    - Add `legend` references to traces and `legend2`, `legend3`, etc. to layout,
+   also add `visible` to legend i.e. to allow positioning multiple legends on a graph [[#6535](https://github.com/plotly/plotly.js/pull/6535)],
+   this feature was anonymously sponsored: thank you to our sponsor!
+    - Add `legend.xref` and `legend.yref` to enable container-referenced positioning of legends [[#6589](https://github.com/plotly/plotly.js/pull/6589)], with thanks to [Gamma Technologies](https://www.gtisoft.com/) for sponsoring the related development.
+    - Add `colorbar.xref` and `colorbar.yref` to enable container-referenced positioning of colorbars [[#6593](https://github.com/plotly/plotly.js/pull/6593)], with thanks to [Gamma Technologies](https://www.gtisoft.com/) for sponsoring the related development.
+  - `px` methods now accept data-frame-like objects that support a `to_pandas()` method, such as polars, cudf, vaex etc
+
+### Fixed
+  - Fixed another compatibility issue with Pandas 2.0, just affecting `px.*(line_close=True)` [[#4190](https://github.com/plotly/plotly.py/pull/4190)]
+  - Empty pandas dataframe with facet row/column set no longer fails [[#4038](https://github.com/plotly/plotly.py/pull/4038)]
+  - Added some rounding to the `make_subplots` function to handle situations where the user-input specs cause the domain to exceed 1 by small amounts [[#4153](https://github.com/plotly/plotly.py/pull/4153)]
+  - Sanitize JSON output to prevent an XSS vector when graphs are inserted directly into HTML [[#4196](https://github.com/plotly/plotly.py/pull/4196)]
+  - Fixed issue with shapes and annotations plotting on the wrong y axis when supplied with a specific axis in the `yref` parameter [[#4177](https://github.com/plotly/plotly.py/pull/4177)]
+  - Remove `use_2to3` setuptools arg, which is invalid in the latest Python and setuptools versions [[#4206](https://github.com/plotly/plotly.py/pull/4206)]
+  - Fix [#4066](https://github.com/plotly/plotly.py/issues/4066) JupyterLab v4 giving tiny default graph height [[#4227](https://github.com/plotly/plotly.py/pull/4227)]
+  - Fixed issue with `colors.n_colors` where generated RGB color values were not being constrained to stay between 0 and 255 [[#4110](https://github.com/plotly/plotly.py/pull/4110)]
+  - Fix streamline figure factory with recent versions of Numpy
+  - Fix issue with shapes and annotations not drawing on correct axis [[#4177](https://github.com/plotly/plotly.py/pull/4177)]
+
 ## [5.14.1] - 2023-04-05
 
 ### Fixed
@@ -10,7 +45,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ## [5.14.0] - 2023-03-29
 
 ### Updated
-  - Updated Plotly.js to from version 2.18.2 to version 2.20.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2200----2023-03-15) for more information. Notable changes include:
+  - Updated Plotly.js from version 2.18.2 to version 2.20.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#2200----2023-03-15) for more information. Notable changes include:
     - Add `title.automargin` to enable automatic top and bottom margining for both container and paper referenced titles [[#6428](https://github.com/plotly/plotly.js/pull/6428)],
    with thanks to [Gamma Technologies](https://www.gtisoft.com/) for sponsoring the related development.
     - Add `label` attribute to shapes [[#6454](https://github.com/plotly/plotly.js/pull/6454)], with thanks to the [Volkswagen](https://www.volkswagenag.com) Center of Excellence for Battery Systems for sponsoring development!

CHANGELOG.md

@@ -33,7 +33,7 @@
 
 ## Quickstart
 
-`pip install plotly==5.14.1`
+`pip install plotly==5.15.0`
 
 Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):
 
@@ -78,13 +78,13 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
 plotly.py may be installed using pip...
 
 ```
-pip install plotly==5.14.1
+pip install plotly==5.15.0
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=5.14.1
+conda install -c plotly plotly=5.15.0
 ```
 
 ### JupyterLab Support
@@ -106,7 +106,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
 
 ```
 # JupyterLab 2.x renderer support
-jupyter labextension install jupyterlab-plotly@5.14.1 @jupyter-widgets/jupyterlab-manager
+jupyter labextension install jupyterlab-plotly@5.15.0 @jupyter-widgets/jupyterlab-manager
 ```
 
 Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.

README.md

@@ -1,5 +1,5 @@
 jupytext
-plotly==5.14.1
+plotly==5.15.0
 jupyter
 notebook
 pandas==1.0.3

binder/requirements.txt

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

doc/apidoc/conf.py

@@ -70,6 +70,7 @@ fig = px.scatter_3d(df, x='sepal_length', y='sepal_width', z='petal_width',
 
 # tight layout
 fig.update_layout(margin=dict(l=0, r=0, b=0, t=0))
+fig.show()
 ```
 
 #### 3d scatter plots in Dash

doc/python/3d-scatter-plots.md

@@ -33,7 +33,7 @@ jupyter:
     thumbnail: thumbnail/axes.png
 ---
 
-This tutorial explain how to set the properties of [2-dimensional Cartesian axes](/python/figure-structure/#2d-cartesian-trace-types-and-subplots), namely [`go.layout.XAxis`](/python/reference/layout/xaxis/) and [`go.layout.YAxis`](python/reference/layout/xaxis/).
+This tutorial explain how to set the properties of [2-dimensional Cartesian axes](/python/figure-structure/#2d-cartesian-trace-types-and-subplots), namely [`go.layout.XAxis`](/python/reference/layout/xaxis/) and [`go.layout.YAxis`](/python/reference/layout/xaxis/).
 
 Other kinds of subplots and axes are described in other tutorials:
 
@@ -154,7 +154,7 @@ fig.update_yaxes(ticklabelposition="inside top", title=None)
 fig.show()
 ```
 
-#### Specifying Label Aliases 
+#### Specifying Label Aliases
 
 *New in 5.14*
 

doc/python/axes.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.3'
-      jupytext_version: 1.14.5
+      jupytext_version: 1.14.6
   kernelspec:
     display_name: Python 3 (ipykernel)
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.10.9
+    version: 3.10.8
   plotly:
     description: How to set, create and control continuous color scales and color
       bars in scatter, bar, map and heatmap figures.
@@ -307,11 +307,11 @@ Using `labelalias` you can replace some labels on the `colorbar` with alternativ
 ```python
 import plotly.graph_objects as go
 
-import urllib
+import urllib.request as request
 import json
 
 # Load heatmap data
-response = urllib.request.urlopen(
+response = request.urlopen(
     "https://raw.githubusercontent.com/plotly/datasets/master/custom_heatmap_colorscale.json")
 dataset = json.load(response)
 
@@ -632,6 +632,36 @@ fig = go.Figure(go.Heatmap(
 fig.show()
 ```
 
+### Positioning Colorbars
+
+Colorbars can be positioned by specifying x and y coordinates. By default, the x and y values are "paper" coordinates, which refer to the plot area. You can also use coordinates based on the "container" by setting `xref="container"` or `yref="container"`. The following example uses a container reference for the x position.
+
+See the positioning section of [the figure data structure page](/python/figure-structure/#positioning-with-paper-container-coordinates-or-axis-domain-coordinates) for more details on "paper" vs "container" coordinates.
+
+```python
+import plotly.graph_objects as go
+
+import urllib
+import json
+
+# Load heatmap data
+response = urllib.request.urlopen(
+    "https://raw.githubusercontent.com/plotly/datasets/master/custom_heatmap_colorscale.json")
+dataset = json.load(response)
+
+# Create and show figure
+fig = go.Figure(go.Heatmap(
+    z=dataset["z"],
+    colorbar=dict(
+        x=0.2,
+        xref="container",
+        title="Surface Heat"
+    )
+))
+
+fig.show()
+```
+
 ### Reference
 
 See https://plotly.com/python/reference/ for more information and chart attribute options!

doc/python/colorscales.md

@@ -53,7 +53,7 @@ import plotly.graph_objects as go
 
 fig = go.Figure()
 
-config = dict({'scrollZoom': True})
+config = {'scrollZoom': True}
 
 fig.add_trace(
     go.Scatter(
@@ -244,6 +244,8 @@ fig.add_trace(
         y=[1, 3, 1]))
 
 fig.update_layout(modebar_remove=['zoom', 'pan'])
+
+fig.show()
 ```
 
 ### Add optional shape-drawing buttons to modebar
@@ -253,16 +255,19 @@ fig.update_layout(modebar_remove=['zoom', 'pan'])
 Some modebar buttons of Cartesian plots are optional and have to be added explicitly, using the `modeBarButtonsToAdd` config attribute. These buttons are used for drawing or erasing shapes. See [the tutorial on shapes and shape drawing](python/shapes#drawing-shapes-on-cartesian-plots) for more details.
 
 ```python
-import plotly.graph_objects as go
 import plotly.express as px
+
 df = px.data.iris()
+
 fig = px.scatter(df, x='petal_width', y='sepal_length', color='species')
+
 fig.update_layout(
     dragmode='drawopenpath',
     newshape_line_color='cyan',
     title_text='Draw a path to separate versicolor and virginica'
 )
-fig.show(config={'modeBarButtonsToAdd':['drawline',
+
+fig.show(config={'modeBarButtonsToAdd': ['drawline',
                                         'drawopenpath',
                                         'drawclosedpath',
                                         'drawcircle',
@@ -276,10 +281,12 @@ fig.show(config={'modeBarButtonsToAdd':['drawline',
 The `layout.modebar.add` attribute can be used instead of the approach used above:
 
 ```python
-import plotly.graph_objects as go
 import plotly.express as px
+
 df = px.data.iris()
+
 fig = px.scatter(df, x='petal_width', y='sepal_length', color='species')
+
 fig.update_layout(
     dragmode='drawopenpath',
     newshape_line_color='cyan',
@@ -292,6 +299,8 @@ fig.update_layout(
         'eraseshape'
        ]
 )
+
+fig.show()
 ```
 
 ### Double-Click Delay
@@ -304,12 +313,12 @@ import plotly.graph_objects as go
 config = {'doubleClickDelay': 1000}
 
 fig = go.Figure(go.Bar(
-    y = [3, 5, 3, 2],
-    x = ["2019-09-02", "2019-10-10", "2019-11-12", "2019-12-22"],
-    texttemplate = "%{label}",
-    textposition = "inside"))
+    y=[3, 5, 3, 2],
+    x=["2019-09-02", "2019-10-10", "2019-11-12", "2019-12-22"],
+    texttemplate="%{label}",
+    textposition="inside"))
 
-fig.update_layout(xaxis = {'type': 'date'})
+fig.update_layout(xaxis={'type': 'date'})
 
 fig.show(config=config)
 ```
@@ -320,4 +329,4 @@ The same configuration dictionary that you pass to the `config` parameter of the
 
 #### Reference
 
-See config options at https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js#L6
+See config options at https://github.com/plotly/plotly.js/blob/master/src/plot_api/plot_config.js

doc/python/configuration-options.md

@@ -61,7 +61,7 @@ Y, X = np.meshgrid(x, y)
 u = -1 - X**2 + Y
 v = 1 + X - Y**2
 
-fig2 = ff.create_streamline(x, y, u, v, arrow_scale=.1, name='Steamline')
+fig2 = ff.create_streamline(x, y, u, v, arrow_scale=.1, name='Streamline')
 ```
 
 Edit the figures' x and y axes attributes to create subplots:

doc/python/figure-factory-subplots.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.3.0
+      format_version: '1.3'
+      jupytext_version: 1.14.6
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   plotly:
@@ -200,6 +200,28 @@ fig.update_layout(
 fig.show()
 ```
 
+### Pattern Fills
+
+*New in 5.15*
+
+Funnel area charts support [patterns](/python/pattern-hatching-texture/) (also known as hatching or texture) in addition to color. In this example, we add a pattern to the second stage of the funnel.
+
+```python
+from plotly import graph_objects as go
+
+colors = ["gold", "gold", "lightgreen", "lavender"]
+
+fig = go.Figure(
+    go.Funnelarea(
+        labels=["Interview 1", "Interview 2", "Test", "Final Stage"],
+        values=[100, 70, 40, 20],
+        textfont_size=20,
+        marker=dict(colors=colors, pattern=dict(shape=["", "/", "", ""])),
+    )
+)
+fig.show()
+```
+
 #### Reference
 
 See [function reference for `px.(funnel)`](https://plotly.com/python-api-reference/generated/plotly.express.funnel) or https://plotly.com/python/reference/funnel/ and https://plotly.com/python/reference/funnelarea/ for more information and chart attribute options!

doc/python/funnel-charts.md

@@ -58,13 +58,13 @@ We also encourage you to join the [Plotly Community Forum](http://community.plot
 `plotly` may be installed using `pip`:
 
 ```
-$ pip install plotly==5.14.1
+$ pip install plotly==5.15.0
 ```
 
 or `conda`:
 
 ```
-$ conda install -c plotly plotly=5.14.1
+$ conda install -c plotly plotly=5.15.0
 ```
 This package contains everything you need to write figures to standalone HTML files.
 
@@ -152,7 +152,7 @@ The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**,
 
 ```
 # JupyterLab 2.x renderer support
-jupyter labextension install jupyterlab-plotly@5.14.1 @jupyter-widgets/jupyterlab-manager
+jupyter labextension install jupyterlab-plotly@5.15.0 @jupyter-widgets/jupyterlab-manager
 ```
 
 Please check out our [Troubleshooting guide](/python/troubleshooting/) if you run into any problems with JupyterLab, particularly if you are using multiple python environments inside Jupyter.