Merge branch 'master' into issue-2550

Merges most up-to-date master

Author: nicholas-esterer

Diff for: CHANGELOG.md

@@ -2,22 +2,73 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## Dev version
+## [4.8.2] - unreleased
+
+### Fixed
+
+- Fixed special cases with `px.sunburst` and `px.treemap` with `path` input ([#2524](https://github.com/plotly/plotly.py/pull/2524))
+
+## [4.8.1] - 2020-05-28
+
+### Fixed
+
+- Fixed the accidental removal of some functions and submodules from `plotly.colors` and `plotly.express.colors`
+
+## [4.8.0] - 2020-05-26
 
 ### Added
 
-- The `hover_data` parameter of `px` functions can now be a dictionary. This
-  makes it possible to skip hover information for some arguments or to change  
-  the formatting of hover informatiom [#2377](https://github.com/plotly/plotly.py/pull/2377).
+- `plotly` now provides a Plotly Express-backed Pandas-compatible plotting backend, which can be activated via `pandas.options.plotting.backend = "plotly"`. Note that it is not intended to implement every Pandas plotting function, nor is it intended to replicate the behaviour of every argument, although per the changes below, `x` and `y` should behave similarly. ([#2336](https://github.com/plotly/plotly.py/pull/2336))
+- New datasets have been added to `plotly.express.data`: `stocks`, `experiment`, `medals_wide` and `medals_long`. ([#2336](https://github.com/plotly/plotly.py/pull/2336))
+- plotly `go.Figure` and `go.FigureWidget` now have a `_repr_html_` and a `_repr_mimebundle_` method, which are [standard hooks for integration in systems based on IPython](https://ipython.readthedocs.io/en/stable/config/integrating.html). In particular, with `_repr_html_` plotly figures can now be used within [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html) without any scraper. These additions should not change anything to the way plotly figures are displayed in notebook environments, since the `_ipython_display_` method (already present in earlier versions) takes precedence over the new methods.
+
+### Updated
+
+- The behaviour of the `x`, `y`, `orientation`, `histfunc`, `violinmode`, `boxmode` and `stripmode` arguments for 2d-cartesian functions in Plotly Express (i.e. `scatter`, `line`, `area`, `bar`, `histogram`, `violin`, `box`, `strip`, `funnel`, `density_heatmap` and `density_contour`) has been refined ([#2336](https://github.com/plotly/plotly.py/pull/2336)):
+    - if `x` or `y` is missing, it is inferred to be the index of `data_frame` if `data_frame` provided, otherwise a stable index of integers starting at 0. In the case of `px.bar`, if the provided value is not continuous, the missing value is treated as a column of 1s named "count", so as to behave more like `px.histogram` and to avoid sizing the resulting bars differently based on their position in the column. Previously, missing values defaulted to integers starting at 0 *per trace* which made it potentially inconsistent or misleading.
+    - if `x` (`y`) is missing, `orientation` now defaults to `v` (`h`). Previously it always defaulted to `v` but this is not considered a breaking change, as the cases in which it now defaults to `h` caused unreadable output if set to `v`.
+    - if both `x` and `y` are provided and one of them does not contain continuous values, `orientation` defaults to the value perpendicular to that axis. Previously it always defaulted to `v` but this is not considered a breaking change, as the cases in which it now defaults to `h` caused unreadable output if set to `v`.
+    - if either `x` or `y` (but not both) may now be provided as a list of column references into `data_frame` or columns of data, in which case the imputed data frame will be treated as "wide" data and `melt()`ed internally before applying the usual mapping rules, with function-specific defaults.
+    - if neither `x` nor `y` is provided but `data_frame` is, the data frame will be treated as "wide" with defaults depending on the value of `orientation` (and `orientation` has accordingly been added to `scatter`, `line`, `density_heatmap`, and `density_contour` for this purpose). Previously this would have resulted in an empty figure.
+    - if both `x` and `y` are provided to `histogram`, and if `x`, `y` and `z` are provided to `density_heatmap` or `density_contour`, then `histfunc` now defaults to `sum` so as to avoid ignoring the provided data, and to cause `histogram` and `bar` to behave more similarly.
+    - `violinmode`, `boxmode` and `stripmode` now default to `overlay` if `x` (`y`) in in `v` (`h`) orientation is also mapped to `color`, to avoid strange spacing issues with the previous default of `group` in all cases.
+- The Plotly Express arguments `color_discrete_map`, `symbol_map` and `line_dash_map` now accept the string `"identity"` which causes the corresponding input data to be used as-is rather than mapped into `color_discrete_sequence`, `symbol_sequence` or `line_dash_sequence`, respectively. ([#2336](https://github.com/plotly/plotly.py/pull/2336))
+- Plotly Express now accepts `px.Constant` or `px.Range` objects in the place of column references so as to express constant or increasing integer values. ([#2336](https://github.com/plotly/plotly.py/pull/2336))
+
+
+## [4.7.1] - 2020-05-08
+
+### Fixed
+
+ - Fix `AttributeError: module 'plotly.graph_objs' has no attribute 'FigureWidget'` exception on `from plotly.graph_objs import *` when `ipywidgets` is not installed. Error also occurred when importing `plotly.figure_factor`. It is now possible to import `plotly.graph_objs.FigureWidget` when `ipywidgets` is not installed, and an informative `ImportError` exception will be raised in the `FigureWidget` constructor ([#2443](https://github.com/plotly/plotly.py/issues/2443), [#1111](https://github.com/plotly/plotly.py/issues/1111)).
+ - Fix `TypeError: unhashable type: 'Template'` during `Figure` construction when `plotly.io.templates.default` is set to a `Template` object rather than a string.
+
+
+## [4.7.0] - 2020-05-06
+
+### Updated
+
+- Updated Plotly.js to version 1.54.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.1/CHANGELOG.md) for more information. The main new feature of this version of Plotly.js is the possibility to draw layout shapes, using custom dragmodes and corresponding modebar buttons.
+- The sphinx-gallery scraper has been updated to work with different structures of galleries [#2149](https://github.com/plotly/plotly.py/pull/2419)
+
+### Added
+
+- The `hover_data` parameter of `px` functions can now be a dictionary. This makes it possible to skip hover information for some arguments or to change the formatting of hover informatiom [#2377](https://github.com/plotly/plotly.py/pull/2377).
+- It's now possible to build a development version of Plotly.py against the build artifacts from a non-`master` branch of Plotly.js, which makes for faster QA and development cycles [#2349](https://github.com/plotly/plotly.py/pull/2349). Thanks [@zouhairm](https://github.com/zouhairm) for this Pull Request!
+
+### Fixed
+
+- Plotly Express trendlines now handle missing data correctly [#2357](https://github.com/plotly/plotly.py/pull/2357)
 
 ### Performance
+
 This version includes several performance improvements ([#2368](https://github.com/plotly/plotly.py/pull/2368), [#2403](https://github.com/plotly/plotly.py/pull/2403)).
- 
+
  - Child graph objects (e.g. `figure.layout.xaxis`) are no longer created eagerly during graph object construction. Instead, they are created lazily the first time the property is accessed.
  - Property validation is now disabled for select internal operations.
  - When used with Python 3.7 and above, ploty.py now takes advantage of [PEP-562](https://www.python.org/dev/peps/pep-0562/) to perform submodule imports lazily.  This dramatically improves import times.
 
-## [4.6] - 2020-03-31
+## [4.6.0] - 2020-03-31
 
 ### Updated
 

Diff for: README.md

@@ -33,7 +33,7 @@
 
 ## Quickstart
 
-`pip install plotly==4.6.0`
+`pip install plotly==4.8.1`
 
 Inside [Jupyter notebook](https://jupyter.org/install) (installable with `pip install "notebook>=5.3" "ipywidgets>=7.2"`):
 
@@ -82,13 +82,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==4.6.0
+pip install plotly==4.8.1
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=4.6.0
+conda install -c plotly plotly=4.8.1
 ```
 
 ### Jupyter Notebook Support
@@ -112,44 +112,27 @@ For use in JupyterLab, install the `jupyterlab` and `ipywidgets`
 packages using pip...
 
 ```
-pip install jupyterlab==1.2 "ipywidgets==7.5"
+pip install jupyterlab "ipywidgets==7.5"
 ```
 
 or conda.
 
 ```
-conda install jupyterlab=1.2
-conda install "ipywidgets=7.5"
+conda install jupyterlab "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):
 
 ```
-# Avoid "JavaScript heap out of memory" errors during extension installation
-# (OS X/Linux)
-export NODE_OPTIONS=--max-old-space-size=4096
-# (Windows)
-set NODE_OPTIONS=--max-old-space-size=4096
+# Basic JupyterLab renderer support
+jupyter labextension install [email protected]
 
-# Jupyter widgets extension
-jupyter labextension install @jupyter-widgets/[email protected] --no-build
-
-# FigureWidget support
-jupyter labextension install [email protected] --no-build
-
-# and jupyterlab renderer support
-jupyter labextension install [email protected] --no-build
-
-# Build extensions (must be done to activate extensions since --no-build is used above)
-jupyter lab build
-
-# Unset NODE_OPTIONS environment variable
-# (OS X/Linux)
-unset NODE_OPTIONS
-# (Windows)
-set NODE_OPTIONS=
+# OPTIONAL: Jupyter widgets extension for FigureWidget support
+jupyter labextension install @jupyter-widgets/jupyterlab-manager [email protected]
 ```
 
+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 using the `to_image` and `write_image`

Diff for: binder/requirements.txt

@@ -1,9 +1,9 @@
 jupytext
-plotly==4.6.0
+plotly==4.8.1
 jupyter
 notebook
-pandas
-statsmodels==0.10.1
+pandas==1.0.3
+statsmodels==0.11.1
 scipy
 patsy==0.5.1
 numpy

Diff for: contributing.md

@@ -128,18 +128,28 @@ conda activate plotly-dev
 [conda-env]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-with-commands
 [virtualenv]: http://docs.python-guide.org/en/latest/dev/virtualenvs/
 
-### Install requirements
-
-    $ pip install -r packages/python/plotly/requirements.txt
-    $ pip install -r packages/python/plotly/optional-requirements.txt
-
-### Editable install of plotly packages (install from source)
+### Install requirements - (Non-Windows)
+```bash
+(plotly_dev) $ pip install -r packages/python/plotly/requirements.txt
+(plotly_dev) $ pip install -r packages/python/plotly/optional-requirements.txt
+ ```   
+### Install requirements - (Windows + Conda)
+Because Windows requires Visual Studio libraries to compile some of the optional dependencies, follow these steps to
+complete installation and avoid gdal-config errors.
 
-    $ pip install -e packages/python/plotly/
-    $ pip install -e packages/python/chart-studio/
-    $ pip install -e packages/python/plotly-geo/
+```bash
+(plotly_dev) $ pip install -r packages/python/plotly/requirements.txt
+(plotly_dev) $ conda install fiona
+(plotly_dev) $ pip install -r packages/python/plotly/optional-requirements.txt
+```
 
-This will ensure that the installed packages link to your local development
+### Editable install of plotly packages
+```bash
+(plotly_dev) $ pip install -e packages/python/plotly/
+(plotly_dev) $ pip install -e packages/python/chart-studio/
+(plotly_dev) $ pip install -e packages/python/plotly-geo/
+```
+This will ensure that the installed packages links to your local development
 directory, meaning that all changes you make reflect directly in your
 environment (don't forget to restart the Jupyter kernel though!). For more
 information see the
@@ -152,11 +162,11 @@ documentation on _development mode_.
 
 Run the following commands in your virtual environment to use the
 development version of `FigureWidget`,
-
-    $ jupyter nbextension enable --py widgetsnbextension
-    $ jupyter nbextension install --py --symlink --sys-prefix plotlywidget
-    $ jupyter nbextension enable --py --sys-prefix plotlywidget
-
+```bash
+(plotly_dev) $ jupyter nbextension enable --py widgetsnbextension
+(plotly_dev) $ jupyter nbextension install --py --symlink --sys-prefix plotlywidget
+(plotly_dev) $ jupyter nbextension enable --py --sys-prefix plotlywidget
+```
 To make plotly plots show up in JupyterLab, you also need to [install the plotly jupyterlab extensions][plotly-jl].
 
 [plotly-jl]: https://plot.ly/python/getting-started/#jupyterlab-support-python-35

Diff for: doc/apidoc/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = python3 -m sphinx
+SPHINXBUILD   = python -m sphinx
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -22,9 +22,13 @@ help:
 	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*.py
 	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*/*.py
 	sed -i 's/:class:`plotly.graph_objects/:class:`plotly.graph_objs/g' ../../packages/python/plotly/plotly/graph_objs/*/*/*/*.py
-	sphinx-apidoc -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api
+	cp ../../packages/python/plotly/_plotly_utils/colors/sequential.py ../../packages/python/plotly/_plotly_utils/colors/diverging.py ../../packages/python/plotly/_plotly_utils/colors/qualitative.py ../../packages/python/plotly/_plotly_utils/colors/cyclical.py ../../packages/python/plotly/_plotly_utils/colors/colorbrewer.py ../../packages/python/plotly/_plotly_utils/colors/carto.py ../../packages/python/plotly/_plotly_utils/colors/cmocean.py ../../packages/python/plotly/plotly/colors
+	cp ../../packages/python/plotly/_plotly_utils/colors/sequential.py ../../packages/python/plotly/_plotly_utils/colors/diverging.py ../../packages/python/plotly/_plotly_utils/colors/qualitative.py ../../packages/python/plotly/_plotly_utils/colors/cyclical.py ../../packages/python/plotly/_plotly_utils/colors/colorbrewer.py ../../packages/python/plotly/_plotly_utils/colors/carto.py ../../packages/python/plotly/_plotly_utils/colors/cmocean.py ../../packages/python/plotly/plotly/express/colors
+	sphinx-apidoc -M -o generated ../../packages/python/plotly/plotly ../../packages/python/plotly/plotly/validators ../../packages/python/plotly/plotly/tests ../../packages/python/plotly/plotly/matplotlylib/ ../../packages/python/plotly/plotly/offline ../../packages/python/plotly/plotly/api
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	git checkout -- ../../packages/python/plotly/plotly/graph_objs
+	rm ../../packages/python/plotly/plotly/colors/diverging.py ../../packages/python/plotly/plotly/colors/sequential.py ../../packages/python/plotly/plotly/colors/qualitative.py ../../packages/python/plotly/plotly/colors/cyclical.py ../../packages/python/plotly/plotly/colors/colorbrewer.py ../../packages/python/plotly/plotly/colors/carto.py ../../packages/python/plotly/plotly/colors/cmocean.py
+	rm ../../packages/python/plotly/plotly/express/colors/diverging.py ../../packages/python/plotly/plotly/express/colors/sequential.py ../../packages/python/plotly/plotly/express/colors/qualitative.py ../../packages/python/plotly/plotly/express/colors/cyclical.py ../../packages/python/plotly/plotly/express/colors/colorbrewer.py ../../packages/python/plotly/plotly/express/colors/carto.py ../../packages/python/plotly/plotly/express/colors/cmocean.py
 	rename 's/graph_objs/graph_objects/' _build/html/*.html _build/html/generated/*.html
 	mv _build/html/generated/plotly.graph_objs.html _build/html/generated/plotly.graph_objects.html
 	sed -i 's/graph_objs/graph_objects/g' _build/html/*.html 

Diff for: doc/apidoc/conf.py

@@ -22,13 +22,13 @@
 # -- Project information -----------------------------------------------------
 
 project = ""
-copyright = "2019, plotly team"
-author = "plotly team"
+copyright = "2020, Plotly"
+author = "Plotly"
 
 # The short X.Y version
 version = ""
 # The full version, including alpha/beta/rc tags
-release = "4.6.0"
+release = "4.8.1"
 
 
 # -- General configuration ---------------------------------------------------

Diff for: doc/apidoc/index.rst

@@ -17,6 +17,8 @@ Submodules
 * :ref:`Subplots: helper function for layout out multi-plot figures <subplots>`
 * :ref:`Figure Factories: helper methods for building specific complex charts <ff>`
 * :ref:`I/O: low-level interface for displaying, reading and writing figures <io>`
+* :mod:`plotly.colors`: colorscales and utility functions
+* :mod:`plotly.data`: built-in datasets for demonstration, educational and test purposes
 
 Full reference list
 -------------------

Diff for: doc/apidoc/plotly.express.rst

@@ -1,7 +1,7 @@
 .. _px:
 
 `plotly.express`: high-level interface for data visualization
-================================
+=============================================================
 
 The `plotly.express <https://plot.ly/python/plotly-express/>`_ module is
 plotly's high-level API for rapid figure generation. ::
@@ -49,4 +49,12 @@ plotly's high-level API for rapid figure generation. ::
     imshow
 
 
+`plotly.express` subpackages
+---------------------------
 
+
+.. toctree::
+   :maxdepth: 1
+
+   generated/plotly.express.data.rst
+   generated/plotly.express.colors.rst

Diff for: doc/apidoc/plotly.figure_factory.rst

@@ -13,6 +13,7 @@
    create_annotated_heatmap
    create_bullet
    create_candlestick
+   create_choropleth
    create_dendrogram
    create_distplot
    create_facet_grid

Diff for: doc/apidoc/plotly.graph_objects.rst

@@ -18,7 +18,7 @@ Figure
    :toctree: generated/
    :template: class_figure.rst
 
-   Figure  
+   Figure
 
 
 Layout
@@ -31,7 +31,7 @@ Layout
    Layout
 
 
-Simple charts
+Simple Traces
 --------------
 
 .. autosummary::
@@ -47,7 +47,7 @@ Simple charts
    Contour
    Table
 
-Distributions
+Distribution Traces
 -------------
 
 .. autosummary::
@@ -60,7 +60,7 @@ Distributions
    Histogram2d
    Histogram2dContour
 
-Finance
+Finance Traces
 -------
 
 .. autosummary::
@@ -74,7 +74,7 @@ Finance
    Funnelarea
    Indicator
 
-3D
+3D Traces
 --
 
 .. autosummary::
@@ -89,7 +89,7 @@ Finance
    Volume
    Isosurface
 
-Maps
+Map Traces
 ----
 
 .. autosummary::
@@ -102,7 +102,7 @@ Maps
    Choroplethmapbox
    Densitymapbox
 
-Specialized
+Specialized Traces
 -----------
 
 .. autosummary::