Release 5.0.0

CHANGELOG.md

@@ -3,30 +3,45 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
 
-## UNRELEASED
+## [5.0.0] - 2021-06-21
 
-### Updated
+### Updated/Changed
+
+Items in this section may be considered backwards-incompatible changes for the purposes of [Semantic Versioning](http://semver.org/) but we expect the vast majority of users to be able to upgrade to version 5.0 without encountering any issues.
 
-- Updated Plotly.js to version 2.0.0. See the [plotly.js 2.0.0 CHANGELOG](https://github.com/plotly/plotly.js/blob/v2.0.0/CHANGELOG.md) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
-  - new `marker.pattern` options for `bar`-like trace types
-  - dropped support for IE9 and IE10
-  - dropped support for long-deprecated `graph_objects` like `area` traces and `scatter.(t|r)` and `layout.(radial|angular)axis` attributes
-  - deprecated `heatmapgl`, `pointcloud` traces as well as all `transform` attributes
+- **Dropped support for Python older than 3.6** [#3160](https://github.com/plotly/plotly.py/pull/3160)
+- Updated Plotly.js to from version 1.58.4 to version 2.1.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#210----2021-06-18) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module. Notable changes include:
+    - dropped support for IE9 and IE10
+    - dropped support for long-deprecated `graph_objects` like `area` traces and `scatter.(t|r)` and `layout.(radial|angular)axis` attributes
+    - modebar no longer has `hovermode` or `showspikes` buttons by default (can be added back with `layout.modebar.add=v1hovermode`)
+    - "Aa" text no longer appears on legend items unless `mode="text"`
+    - In `bar` traces, `textposition` now defaults to `"auto"`
+    - Font size for legend and colorbar titles now matches axis title font size (slightly bigger)
+    - deprecated `heatmapgl`, `pointcloud` traces as well as all `transform` attributes
 - Combined `plotlywidget` into `jupyterlab-plotly` and packaged them as a federated extension [#3142](https://github.com/plotly/plotly.py/pull/3142) with massive thanks to [@fcollonval](https://github.com/fcollonval) for the contribution
+  - In addition to this change, large Plotly.js bundles are now lazily loaded on-demand by JupyterLab
 - Plotly.js CDN url will now be versioned by default for HTML exports using `include_plotlyjs='cdn'` and for "connected" renderers. [#2961](https://github.com/plotly/plotly.py/pull/2961) with thanks to [@adehad](https://github.com/adehad) for the contribution
-- Dropped support for Python older than 3.6 [#3160](https://github.com/plotly/plotly.py/pull/3160)
 - Recommending Kaleido by default over Orca [#3094](https://github.com/plotly/plotly.py/pull/3094)
 - Replaced `retrying` dependency with `tenacity` [#2911](https://github.com/plotly/plotly.py/pull/2911) with thanks to [@jmsmdy](https://github.com/jmsmdy) for the contribution
+- Plotly Express now always takes into account every value in `category_orders` when computing discrete mappings (color, symbol, line-dash, pattern-shapes) as well as facets, even those values which are absent in the data [#3247](https://github.com/plotly/plotly.py/pull/3247)
 
 ### Added
 
+- Additions due to bumping Plotly.js from 1.58.4 to 2.1.0 (see [changelog]((https://github.com/plotly/plotly.js/blob/master/CHANGELOG.md#210----2021-06-18))):
+  - New `icicle` trace type, with thanks to [@Kully](https://github.com/Kully) and [@mtwichan](https://github.com/mtwichan) of [Zyphr](https://www.zyphr.ca/) for their contribution!
+  - New `marker.pattern` options for `bar`-like trace types with thanks to [@s417-lama](https://github.com/s417-lama) for the contribution!
+  - New `legendrank` attribute to control rank of traces within legends
+- Plotly Express' `px.bar()`, `px.histogram()` and `px.bar_polar()` now support the `pattern_shape` argument [#3252](https://github.com/plotly/plotly.py/pull/3252)
+- New Plotly Express `px.icicle()` function, with thanks to [@Kully](https://github.com/Kully) and [@mtwichan](https://github.com/mtwichan) of [Zyphr](https://www.zyphr.ca/) for their contribution! [#3256](https://github.com/plotly/plotly.py/pull/3256)
 - New functions in `plotly.colors`: `get_colorscale()` and `sample_colorscale()` [#3136](https://github.com/plotly/plotly.py/pull/3136) and [#3186](https://github.com/plotly/plotly.py/pull/3186) with thanks to [@CarlAndersson](https://github.com/CarlAndersson) for the contributions
 - Faster JSON encoding when `orjson` is present [#2955](https://github.com/plotly/plotly.py/pull/2955)
 
 ### Fixed
 
 - Pandas and Numpy datetime serialization fixes [#3022](https://github.com/plotly/plotly.py/pull/3022)
 - Fixed selected points of histograms in FigureWidget [#2771](https://github.com/plotly/plotly.py/pull/2771) with thanks to [@meffmadd](https://github.com/meffmadd) for the contribution
+- Static image export now honors `layout.(width|height)`[#3240](https://github.com/plotly/plotly.py/pull/3240)
+- Improvements to "matplotlylib" conversion utility in `plotly.tools.mpl_to_plotly()` with thanks to [@fdion](https://github.com/fdion) [#3143](https://github.com/plotly/plotly.py/pull/3143)
 
 
 ## [4.14.3] - 2021-01-12

README.md

@@ -37,9 +37,9 @@ Our recommended IDE for Plotly’s Python graphing library is Dash Enterprise’
 
 ## Quickstart
 
-`pip install plotly==4.14.3`
+`pip install plotly==5.0.0`
 
-Inside [Jupyter notebook](https://jupyter.org/install) (installable with `pip install "notebook>=5.3" "ipywidgets>=7.5"`):
+Inside [Jupyter](https://jupyter.org/install) (installable with `pip install "jupyterlab>=3" "ipywidgets>=7.6"`):
 
 ```python
 import plotly.graph_objects as go
@@ -86,57 +86,54 @@ 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==4.14.3
+pip install plotly==5.0.0
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=4.14.3
+conda install -c plotly plotly=5.0.0
 ```
 
-### Jupyter Notebook Support
+### JupyterLab Support
 
-For use in the Jupyter Notebook, install the `notebook` and `ipywidgets`
+For use in [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), install the `jupyterlab` and `ipywidgets`
 packages using `pip`:
 
 ```
-pip install "notebook>=5.3" "ipywidgets>=7.5"
+$ pip install "jupyterlab>=3" "ipywidgets>=7.6"
 ```
 
 or `conda`:
 
 ```
-conda install "notebook>=5.3" "ipywidgets>=7.5"
+$ conda install "jupyterlab>=3" "ipywidgets>=7.6"
 ```
 
-### JupyterLab Support
-
-For use in JupyterLab, install the `jupyterlab` and `ipywidgets`
-packages using `pip`:
+The instructions above apply to JupyterLab 3.x. **For JupyterLab 2 or earlier**, run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
 
 ```
-pip install jupyterlab "ipywidgets>=7.5"
+# JupyterLab 2.x renderer support
+jupyter labextension install jupyterlab-plotly@5.0.0 @jupyter-widgets/jupyterlab-manager
 ```
 
-or `conda`:
+Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.
+
+### Jupyter Notebook Support
+
+For use in the Jupyter Notebook, install the `notebook` and `ipywidgets`
+packages using `pip`:
 
 ```
-conda install jupyterlab "ipywidgets>=7.5"
+pip install "notebook>=5.3" "ipywidgets>=7.5"
 ```
 
-Then run the following commands to install the required JupyterLab extensions (note that this will require [`node`](https://nodejs.org/) to be installed):
+or `conda`:
 
 ```
-# Basic JupyterLab renderer support
-jupyter labextension install jupyterlab-plotly@4.14.3
-
-# OPTIONAL: Jupyter widgets extension for FigureWidget support
-jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.14.3
+conda install "notebook>=5.3" "ipywidgets>=7.5"
 ```
 
-Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.
-
 ### Static Image Export
 
 plotly.py supports [static image export](https://plotly.com/python/static-image-export/),

doc/python/aggregations.md

@@ -33,6 +33,8 @@ jupyter:
     thumbnail: thumbnail/aggregations.jpg
 ---
 
+> **Note** `transforms` are deprecated in `plotly` v5 and will be removed in a future version.
+
 #### Introduction
 
 Aggregates are a type of transform that can be applied to values in a given expression. Available aggregations are:

doc/python/bar-charts.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.6.0
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -47,7 +47,7 @@ fig.show()
 ```
 
 
-#### Bar chart with Long Format Data
+#### Bar charts with Long Format Data
 
 Long-form data has one row per observation, and one column per variable. This is suitable for storing and displaying multivariate data i.e. with dimension greater than 2. This format is sometimes called "tidy".
 
@@ -69,7 +69,7 @@ fig.show()
 long_df
 ```
 
-#### Bar chart with Wide Format Data
+#### Bar charts with Wide Format Data
 Wide-form data has one row per value of one of the first variable, and one column per value of the second variable. This is suitable for storing and displaying 2-dimensional data.
 
 ```python
@@ -85,7 +85,7 @@ fig.show()
 wide_df
 ```
 
-### Bar chart in Dash
+### Bar charts in Dash
 
 [Dash](https://plotly.com/dash/) is the best way to build analytical apps in Python using Plotly figures. To run the app below, run `pip install dash`, click "Download" to get the code and run `python app.py`.
 
@@ -98,9 +98,9 @@ snippet_url = 'https://dash-gallery.plotly.host/python-docs-dash-snippets/'
 IFrame(snippet_url + 'bar-charts', width='100%', height=630)
 ```
 
-### Customize bar chart with Plotly Express
+### Customize bar charts with Plotly Express
 
-The bar plot can be customized using keyword arguments.
+The bar plot can be customized using keyword arguments, for example to use [continuous color](https://plotly.com/python/colorscales/), as below, or [discrete color](/python/discrete-color/), as above.
 
 ```python
 import plotly.express as px
@@ -122,8 +122,9 @@ fig = px.bar(df, x="sex", y="total_bill", color='time')
 fig.show()
 ```
 
+The default stacked bar chart behavior can be changed to grouped (also known as clustered) using the `barmode` argument:
+
 ```python
-# Change the default stacking
 import plotly.express as px
 df = px.data.tips()
 fig = px.bar(df, x="sex", y="total_bill",
@@ -132,6 +133,20 @@ fig = px.bar(df, x="sex", y="total_bill",
 fig.show()
 ```
 
+*New in v5.0*
+
+
+Bar charts afford the use of [patterns (also known as hatching or texture)](/python/pattern-hatching-texture/) in addition to color:
+
+```python
+import plotly.express as px
+df = px.data.medals_long()
+
+fig = px.bar(df, x="medal", y="count", color="nation",
+             pattern_shape="nation", pattern_shape_sequence=[".", "x", "+"])
+fig.show()
+```
+
 #### Facetted subplots
 
 Use the keyword arguments `facet_row` (resp. `facet_col`) to create facetted subplots, where different rows (resp. columns) correspond to different values of the dataframe column specified in `facet_row`.
@@ -335,8 +350,8 @@ for key in data:
         ])
     ))
 
-fig.update_xaxes( 
-    tickvals=np.cumsum(widths)-widths/2, 
+fig.update_xaxes(
+    tickvals=np.cumsum(widths)-widths/2,
     ticktext= ["%s<br>%d" % (l, w) for l, w in zip(labels, widths)]
 )