Merge branch 'master' into doc-prod

Author: LiamConnors

.circleci/config.yml

@@ -1,7 +1,7 @@
 version: 2.1
 
 orbs:
-  browser-tools: circleci/[email protected].1
+  browser-tools: circleci/[email protected].3
 
 commands:
   test_core:

CHANGELOG.md

@@ -2,6 +2,13 @@
 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

doc/python/plotly-express.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.14.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.10.4
   plotly:
     description: Plotly Express is a terse, consistent, high-level API for creating
       figures.
@@ -42,8 +42,7 @@ Plotly Express provides [more than 30 functions for creating different types of
 
 Here is a talk from the [SciPy 2021 conference](https://www.scipy2021.scipy.org/) that gives a good introduction to Plotly Express and [Dash](https://dash.plotly.com/):
 
-```python hide_code=true
-%%html
+```html hide_code=true
 <div align="center">
 <iframe width="560" height="315"
 src="https://www.youtube.com/embed/FpCgG85g2Hw"
@@ -72,7 +71,7 @@ The Plotly Express API in general offers the following features:
 
 * **A single entry point into `plotly`**: just `import plotly.express as px` and get access to [all the plotting functions](https://plotly.com/python-api-reference/plotly.express.html), plus [built-in demo datasets under `px.data`](https://plotly.com/python-api-reference/generated/plotly.data.html#module-plotly.data) and [built-in color scales and sequences under `px.color`](https://plotly.com/python-api-reference/generated/plotly.colors.html#module-plotly.colors). Every PX function returns a `plotly.graph_objects.Figure` object, so you can edit it using all the same methods like [`update_layout` and `add_trace`](https://plotly.com/python/creating-and-updating-figures/#updating-figures).
 * **Sensible, Overridable Defaults**: PX functions will infer sensible defaults wherever possible, and will always let you override them.
-* **Flexible Input Formats**: PX functions [accept input in a variety of formats](/python/px-arguments/), from `list`s and `dict`s to [long-form or wide-form Pandas `DataFrame`s](/python/wide-form/) to [`numpy` arrays and `xarrays`](/python/imshow/) to [GeoPandas `GeoDataFrames`](/python/maps/).
+* **Flexible Input Formats**: PX functions [accept input in a variety of formats](/python/px-arguments/), from `list`s and `dict`s to [long-form or wide-form `DataFrame`s](/python/wide-form/) to [`numpy` arrays and `xarrays`](/python/imshow/) to [GeoPandas `GeoDataFrames`](/python/maps/).
 * **Automatic Trace and Layout configuration**: PX functions will create one [trace](/python/figure-structure) per animation frame for each unique combination of data values mapped to discrete color, symbol, line-dash, facet-row and/or facet-column. Traces' [`legendgroup` and `showlegend` attributes](https://plotly.com/python/legend/) are set such that only one legend item appears per unique combination of discrete color, symbol and/or line-dash. Traces are automatically linked to a correctly-configured [subplot of the appropriate type](/python/figure-structure).
 * **Automatic Figure Labelling**: PX functions [label axes, legends and colorbars](https://plotly.com/python/figure-labels/) based in the input `DataFrame` or `xarray`, and provide [extra control with the `labels` argument](/python/styling-plotly-express/).
 * **Automatic Hover Labels**: PX functions populate the hover-label using the labels mentioned above, and provide [extra control with the `hover_name` and `hover_data` arguments](/python/hover-text-and-formatting/).

doc/python/px-arguments.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.14.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.10.4
   plotly:
     description: Input data arguments accepted by Plotly Express functions
     display_as: file_settings
@@ -35,9 +35,11 @@ jupyter:
 
 ### Plotly Express works with Column-oriented, Matrix or Geographic Data
 
-[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which [operates on a variety of types of data](/python/px-arguments/) and produces [easy-to-style figures](/python/styling-plotly-express/).
+[Plotly Express](/python/plotly-express/) is the easy-to-use, high-level interface to Plotly, which operates on a variety of types of data and produces [easy-to-style figures](/python/styling-plotly-express/).
 
-Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a Pandas `DataFrame` (in either "long" or "wide" format, see below). [`px.imshow` operates on matrix-like data](/python/imshow/) you might store in a `numpy` or `xarray` array and functions like [`px.choropleth` and `px.choropleth_mapbox` can operate on geographic data](/python/maps/) of the kind you might store in a GeoPandas `GeoDataFrame`. This page details how to provide column-oriented data to most Plotly Express functions.
+Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a `DataFrame` (in either "long" or "wide" format, see below). These functions use Pandas internally to process the data, but also accept other types of DataFrames as arguments. See the **Input Data as Non-Pandas DataFrames** section below for more details.
+
+[`px.imshow` operates on matrix-like data](/python/imshow/) you might store in a `numpy` or `xarray` array and functions like [`px.choropleth` and `px.choropleth_mapbox` can operate on geographic data](/python/maps/) of the kind you might store in a GeoPandas `GeoDataFrame`. This page details how to provide column-oriented data to most Plotly Express functions.
 
 
 
@@ -166,6 +168,36 @@ fig = px.bar(df, x='year', y=gdp, color='continent', labels={'y':'gdp'},
 fig.show()
 ```
 
+### Input Data as Non-Pandas `DataFrame`s
+
+**New in 5.16**
+
+In the examples above, we've used Pandas DataFrames. You can also provide another type of DataFrame to the `data_frame` argument if that DataFrame has a `to_pandas` method or supports the [Python dataframe interchange protocol](https://data-apis.org/dataframe-protocol/latest/index.html), for example, a [Polars](https://www.pola.rs/) DataFrame.
+
+Plotly Express uses Pandas internally to process the data. When you provide a Non-Pandas DataFrame to the `data_frame` argument of a Plotly Express function, the entire DataFrame is converted to a Pandas DataFrame.
+
+If you are using a type of DataFrame that doesn't have a `to_pandas` method, but supports the Python dataframe interchange protocol, you'll need to have Pandas version 2.0.3 or later installed. 
+
+In this example, we use a Polars DataFrame. If you are using Polars, you'll need to install `pyarrow`, which is used by its [`to_pandas` method](
+https://pola-rs.github.io/polars/py-polars/html/reference/dataframe/api/polars.DataFrame.to_pandas.html)
+
+```python
+import polars as pl
+import plotly.express as px
+
+wide_df = pl.DataFrame(
+    {
+        "nation": ["South Korea", "China", "Canada"],
+        "gold": [24, 10, 9],
+        "silver": [13, 15, 12],
+        "bronze": [9, 12, 12],
+    }
+)
+
+fig = px.bar(wide_df, x="nation", y=["gold", "silver", "bronze"], title="Wide-Form Input")
+fig.show()
+```
+
 ### Input Data as array-like columns: NumPy arrays, lists...
 
 `px` arguments can also be array-like objects such as lists, NumPy arrays, in both long-form or wide-form (for certain functions).
@@ -243,4 +275,4 @@ fig = px.bar(df, x='year', y=gdp, color='continent', labels={'y':'log gdp'},
              hover_data=['country'],
              title='Evolution of world GDP')
 fig.show()
-```
+```

doc/python/wide-form.md

@@ -5,10 +5,10 @@ jupyter:
     text_representation:
       extension: .md
       format_name: markdown
-      format_version: '1.2'
-      jupytext_version: 1.4.2
+      format_version: '1.3'
+      jupytext_version: 1.14.7
   kernelspec:
-    display_name: Python 3
+    display_name: Python 3 (ipykernel)
     language: python
     name: python3
   language_info:
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.7.7
+    version: 3.10.4
   plotly:
     description: Plotly Express' 2D-Cartesian functions accept data in long-, wide-,
       and mixed-form.
@@ -36,7 +36,9 @@ jupyter:
 
 ### Plotly Express works with Column-oriented, Matrix or Geographic Data
 
-Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a Pandas `DataFrame` (in either "long" or "wide" format, see below). [`px.imshow` operates on matrix-like data](/python/imshow/) you might store in a `numpy` or `xarray` array and functions like [`px.choropleth` and `px.choropleth_mapbox` can operate on geographic data](/python/maps/) of the kind you might store in a GeoPandas `GeoDataFrame`. This page details how to provide a specific form of column-oriented data to 2D-Cartesian Plotly Express functions, but you can also check out our [detailed column-input-format documentation](/python/px-arguments/).
+Plotly Express provides functions to visualize a variety of types of data. Most functions such as `px.bar` or `px.scatter` expect to operate on column-oriented data of the type you might store in a `DataFrame` (in either "long" or "wide" format, see below). These functions use Pandas internally to process the data, but also accept other types of DataFrames as arguments. See the [Plotly Express arguments page](/python/px-arguments/) for more details.
+
+[`px.imshow` operates on matrix-like data](/python/imshow/) you might store in a `numpy` or `xarray` array and functions like [`px.choropleth` and `px.choropleth_mapbox` can operate on geographic data](/python/maps/) of the kind you might store in a GeoPandas `GeoDataFrame`. This page details how to provide a specific form of column-oriented data to 2D-Cartesian Plotly Express functions, but you can also check out our [detailed column-input-format documentation](/python/px-arguments/).
 
 ### Plotly Express works with Long-, Wide-, and Mixed-Form Data
 
@@ -312,4 +314,4 @@ fig.show()
 
 fig = px.box(wide_df, orientation="h")
 fig.show()
-```
+```

doc/requirements.txt

@@ -37,3 +37,4 @@ orjson
 dash-bio
 jinja2<3.1
 parmed<=3.4.4; python_version<"3.8"
+polars

packages/javascript/jupyterlab-plotly/package-lock.json

@@ -65,7 +65,7 @@
     "@lumino/messaging": "^1.2.3",
     "@lumino/widgets": "^1.8.1",
     "lodash": "^4.17.4",
-    "plotly.js": "^2.24.1"
+    "plotly.js": "^2.24.2"
   },
   "jupyterlab": {
     "extension": "lib/jupyterlab-plugin",

packages/javascript/jupyterlab-plotly/package.json

@@ -1,6 +1,6 @@
 """
 `plotly.express` is a terse, consistent, high-level wrapper around `plotly.graph_objects`
-for rapid data exploration and figure generation. Learn more at https://plotly.express/
+for rapid data exploration and figure generation. Learn more at https://plotly.com/python/plotly-express/
 """
 from __future__ import absolute_import
 from plotly import optional_imports

packages/python/plotly/plotly/express/__init__.py

@@ -7,6 +7,7 @@
 from _plotly_utils.basevalidators import ColorscaleValidator
 from plotly.colors import qualitative, sequential
 import math
+from packaging import version
 import pandas as pd
 import numpy as np
 
@@ -1307,7 +1308,25 @@ def build_dataframe(args, constructor):
     # Cast data_frame argument to DataFrame (it could be a numpy array, dict etc.)
     df_provided = args["data_frame"] is not None
     if df_provided and not isinstance(args["data_frame"], pd.DataFrame):
-        if hasattr(args["data_frame"], "to_pandas"):
+        if hasattr(args["data_frame"], "__dataframe__") and version.parse(
+            pd.__version__
+        ) >= version.parse("2.0.2"):
+            import pandas.api.interchange
+
+            df_not_pandas = args["data_frame"]
+            try:
+                df_pandas = pandas.api.interchange.from_dataframe(df_not_pandas)
+            except (ImportError, NotImplementedError) as exc:
+                # temporary workaround; developers of third-party libraries themselves
+                # should try a different implementation, if available. For example:
+                # def __dataframe__(self, ...):
+                #   if not some_condition:
+                #     self.to_pandas(...)
+                if not hasattr(df_not_pandas, "to_pandas"):
+                    raise exc
+                df_pandas = df_not_pandas.to_pandas()
+            args["data_frame"] = df_pandas
+        elif hasattr(args["data_frame"], "to_pandas"):
             args["data_frame"] = args["data_frame"].to_pandas()
         else:
             args["data_frame"] = pd.DataFrame(args["data_frame"])

packages/python/plotly/plotly/express/_core.py

@@ -1,3 +1,3 @@
 # DO NOT EDIT
 # This file is generated by the updatebundle setup.py command
-__plotlyjs_version__ = "2.24.1"
+__plotlyjs_version__ = "2.24.2"

packages/python/plotly/plotly/offline/_plotlyjs_version.py

@@ -388,10 +388,8 @@ def test_missing_webbrowser_module(fig1):
     """
     Assert that no errors occur if the webbrowser module is absent
     """
-    try:
-        import builtins
-    except ImportError:
-        import __builtin__ as builtins
+    import builtins
+
     realimport = builtins.__import__
 
     def webbrowser_absent_import(name, globals, locals, fromlist, level):

packages/python/plotly/plotly/package_data/plotly.min.js

@@ -3,9 +3,25 @@
 import numpy as np
 import pandas as pd
 import pytest
+from packaging import version
+import unittest.mock as mock
 from plotly.express._core import build_dataframe
 from pandas.testing import assert_frame_equal
 
+# Fixtures
+# --------
+@pytest.fixture
+def add_interchange_module_for_old_pandas():
+    if not hasattr(pd.api, "interchange"):
+        pd.api.interchange = mock.MagicMock()
+        # to make the following import work: `import pandas.api.interchange`
+        with mock.patch.dict(
+            "sys.modules", {"pandas.api.interchange": pd.api.interchange}
+        ):
+            yield
+    else:
+        yield
+
 
 def test_numpy():
     fig = px.scatter(x=[1, 2, 3], y=[2, 3, 4], color=[1, 3, 9])
@@ -233,6 +249,47 @@ def test_build_df_with_index():
     assert_frame_equal(tips.reset_index()[out["data_frame"].columns], out["data_frame"])
 
 
+def test_build_df_using_interchange_protocol_mock(
+    add_interchange_module_for_old_pandas,
+):
+    class CustomDataFrame:
+        def __dataframe__(self):
+            pass
+
+    input_dataframe = CustomDataFrame()
+    args = dict(data_frame=input_dataframe, x="petal_width", y="sepal_length")
+
+    iris_pandas = px.data.iris()
+
+    with mock.patch("pandas.__version__", "2.0.2"):
+        with mock.patch(
+            "pandas.api.interchange.from_dataframe", return_value=iris_pandas
+        ) as mock_from_dataframe:
+            build_dataframe(args, go.Scatter)
+        mock_from_dataframe.assert_called_once_with(input_dataframe)
+
+
+@pytest.mark.skipif(
+    version.parse(pd.__version__) < version.parse("2.0.2"),
+    reason="plotly doesn't use a dataframe interchange protocol for pandas < 2.0.2",
+)
+@pytest.mark.parametrize("test_lib", ["vaex", "polars"])
+def test_build_df_from_vaex_and_polars(test_lib):
+    if test_lib == "vaex":
+        import vaex as lib
+    else:
+        import polars as lib
+
+    # take out the 'species' columns since the vaex implementation does not cover strings yet
+    iris_pandas = px.data.iris()[["petal_width", "sepal_length"]]
+    iris_vaex = lib.from_pandas(iris_pandas)
+    args = dict(data_frame=iris_vaex, x="petal_width", y="sepal_length")
+    out = build_dataframe(args, go.Scatter)
+    assert_frame_equal(
+        iris_pandas.reset_index()[out["data_frame"].columns], out["data_frame"]
+    )
+
+
 def test_timezones():
     df = pd.DataFrame({"date": ["2015-04-04 19:31:30+1:00"], "value": [3]})
     df["date"] = pd.to_datetime(df["date"])

packages/python/plotly/plotly/tests/test_io/test_renderers.py

@@ -1,6 +1,6 @@
 requests==2.25.1
 tenacity==6.2.0
-pandas==2.0.1
+pandas==2.0.2
 numpy==1.20.3
 xarray==0.17.0
 statsmodels
@@ -19,3 +19,6 @@ matplotlib==2.2.3
 scikit-image==0.18.1
 psutil==5.7.0
 kaleido
+vaex
+pydantic<=1.10.11 # for vaex, see https://github.com/vaexio/vaex/issues/2384
+polars

packages/python/plotly/plotly/tests/test_optional/test_px/test_px_input.py

@@ -128,7 +128,8 @@ start by doing it first if not. Then merge `master` into `doc-prod` to deploy th
 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
+    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