Merge branch 'master' into add-pxlinks

Author: nicolaskruchten

Diff for: .circleci/config.yml

@@ -440,6 +440,15 @@ jobs:
               git push --force [email protected]:plotly/plotly.py-docs.git master:built
               rm -rf .git
               cd ../..
+              cd build/ipynb
+              git init
+              git config user.name plotlydocbot
+              git config user.email [email protected]
+              git add *
+              git commit -m "build of https://github.com/plotly/plotly.py/commit/${CIRCLE_SHA1}"
+              git push --force [email protected]:plotly/plotly.py-docs.git master:built_ipynb
+              rm -rf .git
+              cd ../..
             fi
             tar -zcf build/html.tgz build/html
             rm -rf build/html build/ipynb

Diff for: .gitattributes

@@ -1 +1 @@
-plotly/_version.py export-subst
+packages/python/plotly/plotly/_version.py export-subst

Diff for: .github/pull_request_template.md

@@ -33,5 +33,6 @@ below :-).
 - [ ] For a new feature, I have added documentation examples in an existing or
   new tutorial notebook (please see the doc checklist as well).
 - [ ] I have added a CHANGELOG entry if fixing/changing/adding anything substantial.
+- [ ] For a new feature or a change in behaviour, I have updated the relevant docstrings in the code to describe the feature or behaviour (please see the doc checklist as well).
 
 -->

Diff for: .gitignore

@@ -31,7 +31,7 @@ node_modules/
 
 # virtual envs
 vv
-venv
+venv*
 
 # dist files
 build
@@ -46,4 +46,5 @@ temp-plot.html
 doc/python/.ipynb_checkpoints
 doc/python/.mapbox_token
 doc/.ipynb_checkpoints
+tags
 doc/check-or-enforce-order.py

Diff for: CHANGELOG.md

@@ -2,6 +2,36 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [4.13.0] - UNRELEASED
+
+### Added
+
+- `go.Figure` now has a `set_subplots` method to set subplots on an already
+  existing figure.
+- Added `Turbo` colorscale
+
+
+## [4.12.1] - UNRELEASED
+
+
+
+## [4.12.0] - 2020-10-23
+
+### Added
+
+- For `add_trace`, `add_shape`, `add_annotation` and `add_layout_image`, the `row` and/or `col` argument now also accept the string `"all"`. `row="all"` adds the object to all the subplot rows and `col="all"` adds the object to all the subplot columns. ([#2840](https://github.com/plotly/plotly.py/pull/2840))
+- Shapes that reference the plot axes in one dimension and the data in another dimension can be added with the new `add_hline`, `add_vline`, `add_hrect`, `add_vrect` functions, which also support the `row="all"` and `col="all"` arguments. ([#2840](https://github.com/plotly/plotly.py/pull/2840))
+- The `add_trace`, `add_shape`, `add_annotation`, `add_layout_image`, `add_hline`, `add_vline`, `add_hrect`, `add_vrect` functions accept an argument `exclude_empty_subplots` which if `True`, only adds the object to subplots already containing traces or layout objects. This is useful in conjunction with the `row="all"` and `col="all"` arguments. ([#2840](https://github.com/plotly/plotly.py/pull/2840))
+- For all `go.Figure` functions accepting a selector argument (e.g., `select_traces`), this argument can now also be a function which is passed each relevant graph object (in the case of `select_traces`, it is passed every trace in the figure). For graph objects where this function returns true, the graph object is included in the selection. ([#2844](https://github.com/plotly/plotly.py/pull/2844))
+
+### Added
+
+- Better magic underscore error messages. For example, `some_fig.update_layout(geo_ltaxis_showgrid=True)` shows `Bad property path:\ngeo_ltaxis_showgrid\n   ^` and lists the valid properties for `geo`.
+
+### Updated
+
+- Updated Plotly.js to version 1.57.1. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.57.1/CHANGELOG.md) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module.
+
 ## [4.11.0] - 2020-10-01
 
 ### Updated
@@ -16,6 +46,11 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Updated
 
+- The JSON serialization of plotly figures had been accelerated by handling
+  differently figures with and without NaN and Inf values ([#2880](https://github.com/plotly/plotly.py/pull/2880)).
+  
+### Updated
+
 - Updated Plotly.js to version 1.55.2. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.55.2/CHANGELOG.md) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module.
 - `px.imshow` has a new `binary_string` boolean argument, which passes the
   image data as a b64 binary string when True. Using binary strings allow for

Diff for: README.md

@@ -31,9 +31,13 @@
     </tr>
 </table>
 
+## Data Science Workspaces
+
+Our recommended IDE for Plotly’s Python graphing library is Dash Enterprise’s [Data Science Workspaces](https://plotly.com/dash/workspaces/), which has both Jupyter notebook and Python code file support.
+
 ## Quickstart
 
-`pip install plotly==4.11.0`
+`pip install plotly==4.12.0`
 
 Inside [Jupyter notebook](https://jupyter.org/install) (installable with `pip install "notebook>=5.3" "ipywidgets>=7.2"`):
 
@@ -82,13 +86,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.11.0
+pip install plotly==4.12.0
 ```
 
 or conda.
 
 ```
-conda install -c plotly plotly=4.11.0
+conda install -c plotly plotly=4.12.0
 ```
 
 ### Jupyter Notebook Support
@@ -125,18 +129,18 @@ Then run the following commands to install the required JupyterLab extensions (n
 
 ```
 # Basic JupyterLab renderer support
-jupyter labextension install jupyterlab-plotly@4.11.0
+jupyter labextension install jupyterlab-plotly@4.12.0
 
 # OPTIONAL: Jupyter widgets extension for FigureWidget support
-jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.11.0
+jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.12.0
 ```
 
 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/),
-using the either the [`kaleido`](https://github.com/plotly/Kaleido)
+using either the [`kaleido`](https://github.com/plotly/Kaleido)
 package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca)
 command line utility (legacy as of `plotly` version 4.9).
 

Diff for: binder/requirements.txt

@@ -1,5 +1,5 @@
 jupytext
-plotly==4.11.0
+plotly==4.12.0
 jupyter
 notebook
 pandas==1.0.3
@@ -18,3 +18,4 @@ cufflinks==0.17.3
 kaleido
 scikit-learn
 umap-learn
+wget

Diff for: doc/apidoc/conf.py

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

Diff for: doc/python/bar-charts.md

@@ -287,6 +287,56 @@ fig = go.Figure(data=[go.Bar(
 fig.show()
 ```
 
+Bar charts with custom widths can be used to make mekko charts (also known as marimekko charts, mosaic plots, or variwide charts).
+
+```python
+import plotly.graph_objects as go
+import numpy as np
+
+labels = ["apples","oranges","pears","bananas"]
+widths = np.array([10,20,20,50])
+
+data = {
+    "South": [50,80,60,70],
+    "North": [50,20,40,30]
+}
+
+fig = go.Figure()
+for key in data:
+    fig.add_trace(go.Bar(
+        name=key,
+        y=data[key],
+        x=np.cumsum(widths)-widths,
+        width=widths,
+        offset=0,
+        customdata=np.transpose([labels, widths*data[key]]),
+        texttemplate="%{y} x %{width} =<br>%{customdata[1]}",
+        textposition="inside",
+        textangle=0,
+        textfont_color="white",
+        hovertemplate="<br>".join([
+            "label: %{customdata[0]}",
+            "width: %{width}",
+            "height: %{y}",
+            "area: %{customdata[1]}",
+        ])
+    ))
+
+fig.update_xaxes( 
+    tickvals=np.cumsum(widths)-widths/2, 
+    ticktext= ["%s<br>%d" % (l, w) for l, w in zip(labels, widths)]
+)
+
+fig.update_xaxes(range=[0,100])
+fig.update_yaxes(range=[0,100])
+
+fig.update_layout(
+    title_text="Marimekko Chart",
+    barmode="stack",
+    uniformtext=dict(mode="hide", minsize=10),
+)
+```
+
 ### Customizing Individual Bar Base
 
 ```python

Diff for: doc/python/builtin-colorscales.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.1
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.7.7
   plotly:
     description: A reference for the built-in named continuous (sequential, diverging
       and cylclical) color scales in Plotly.
@@ -83,11 +83,11 @@ Here are all the built-in scales in the `plotly.colors.sequential` module:
 ```python
 import plotly.express as px
 
-fig = px.colors.sequential.swatches()
+fig = px.colors.sequential.swatches_continuous()
 fig.show()
 ```
 
-Note: `RdBu` was included in this module by mistake, even though it is a diverging color scale.
+Note: `RdBu` was included in the `sequential` module by mistake, even though it is a diverging color scale.
 It is intentionally left in for backwards-compatibility reasons.
 
 ### Built-In Diverging Color scales
@@ -102,7 +102,7 @@ Here are all the built-in scales in the `plotly.colors.diverging` module:
 ```python
 import plotly.express as px
 
-fig = px.colors.diverging.swatches().update_layout(margin_b=10)
+fig = px.colors.diverging.swatches_continuous()
 fig.show()
 ```
 
@@ -121,6 +121,6 @@ import plotly.express as px
 fig = px.colors.cyclical.swatches_cyclical()
 fig.show()
 
-fig = px.colors.cyclical.swatches()
+fig = px.colors.cyclical.swatches_continuous()
 fig.show()
-```
+```

Diff for: doc/python/choropleth-maps.md

@@ -6,7 +6,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.1
+      jupytext_version: 1.4.2
   kernelspec:
     display_name: Python 3
     language: python
@@ -20,7 +20,7 @@ jupyter:
     name: python
     nbconvert_exporter: python
     pygments_lexer: ipython3
-    version: 3.6.8
+    version: 3.7.7
   plotly:
     description: How to make choropleth maps in Python with Plotly.
     display_as: maps
@@ -164,7 +164,25 @@ fig.update_layout(margin={"r":0,"t":0,"l":0,"b":0})
 fig.show()
 ```
 
-<!-- #region -->
+### Using GeoPandas Data Frames
+
+`px.choropleth` accepts the `geometry` of a [GeoPandas](https://geopandas.org/) data frame as the input to `geojson` if the `geometry` contains polygons.
+
+```python
+import plotly.express as px
+import geopandas as gpd
+
+geo_df = gpd.read_file(gpd.datasets.get_path('nybb')).to_crs("EPSG:4326")
+
+fig = px.choropleth(geo_df,
+                   geojson=geo_df.geometry,
+                   locations=geo_df.index,
+                   color='Shape_Leng',
+                   hover_name="BoroName")
+fig.update_geos(fitbounds="locations", visible=False)
+fig.show()
+```
+
 
 ### Using Built-in Country and State Geometries
 
@@ -179,7 +197,6 @@ Plotly comes with two built-in geometries which do not require an external GeoJS
 
 To use the built-in countries geometry, provide `locations` as [three-letter ISO country codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3).
 
-<!-- #endregion -->
 
 ```python
 import plotly.express as px

Diff for: doc/python/figure-structure.md

@@ -95,18 +95,31 @@ The third of the three top-level attributes of a figure is `frames`, whose value
 
 ### The `config` Object
 
-At [render-time](/python/renderers/), it is also possible to control certain figure behaviors which are not considered part of the figure proper i.e. the behaviour of the "modebar" and how the figure relates to mouse actions like scrolling etc. The object that contains these options is called the [`config`, and has its own documentation page](/python/configuration-options/). It is exposed in Python as the `config` keyword argument of the `.show()` method on `plotly.graph_objects.Figure` objects.
+At [render-time](/python/renderers/), it is also possible to control certain figure behaviors which are not considered part of the figure proper i.e. the behavior of the "modebar" and how the figure relates to mouse actions like scrolling etc. The object that contains these options is called the [`config`, and has its own documentation page](/python/configuration-options/). It is exposed in Python as the `config` keyword argument of the `.show()` method on `plotly.graph_objects.Figure` objects.
 
-### Positioning With Paper or Container Coordinates
+### Positioning With Paper, Container Coordinates, or Axis Domain Coordinates
 
 Various figure components configured within the layout of the figure support positioning attributes named `x` or `y`, whose values may be specified in "paper coordinates" (sometimes referred to as "plot fractions" or "normalized coordinates"). Examples include `layout.xaxis.domain` or `layout.legend.x` or `layout.annotation[].x`.
 
 Positioning in paper coordinates is *not* done in absolute pixel terms, but rather in terms relative to a coordinate system defined with an origin `(0,0)` at `(layout.margin.l, layout.margin.b)` and a point `(1,1)` at `(layout.width-layout.margin.r, layout.height-layout.margin.t)` (note: `layout.margin` values are pixel values, as are `layout.width` and `layout.height`). Paper coordinate values less than 0 or greater than 1 are permitted, and refer to areas within the plot margins.
 
+To position an object in "paper" coordinates, the corresponding axis reference
+is set to `"paper"`. For instance a shape's `xref` attribute would be set to
+`"paper"` so that the `x` value of the shape refers to its position in paper
+coordinates.
+
 Note that the contents of the `layout.margin` attribute are by default computed based on the position and dimensions of certain items like the title or legend, and may be made dependent on the position and dimensions of tick labels as well when setting the `layout.xaxis.automargin` attribute to `True`. This has the effect of automatically increasing the margin values and therefore shrinking the physical area defined between the `(0,0)` and `(1,1)` points. Positioning certain items at paper coordinates less than 0 or greater than 1 will also trigger this behavior. The `layout.width` and `layout.height`, however, are taken as givens, so a figure will never grow or shrink based on its contents.
 
 The figure title may be positioned using "container coordinates" which have `(0,0)` and `(1,1)` anchored at the bottom-left and top-right of the figure, respectively, and therefore are independent of the values of layout.margin.
 
+Furthermore, shapes, annotations, and images can be placed relative to an axis's
+domain so that, for instance, an `x` value of `0.5` would place the object
+halfway along the x-axis, regardless of the domain as specified in the
+`layout.xaxis.domain` attribute. This behavior can be specified by adding
+`' domain'` to the axis reference in the axis referencing attribute of the object.
+For example, setting `yref = 'y2 domain'` for a shape will refer to the length
+and position of the axis named `y2`.
+
 ### 2D Cartesian Trace Types and Subplots
 
 The most commonly-used kind of subplot is a [two-dimensional Cartesian subplot](/python/axes/). Traces compatible with these subplots support `xaxis` and `yaxis` attributes whose values must refer to corresponding objects in the layout portion of the figure. For example, if `xaxis="x"`, and `yaxis="y"` (which is the default) then this trace is drawn on the subplot at the intersection of the axes configured under `layout.xaxis` and `layout.yaxis`, but if `xaxis="x2"` and `yaxis="y3"` then the trace is drawn at the intersection of the axes configured under `layout.xaxis2` and `layout.yaxis3`. Note that attributes such as `layout.xaxis` and `layout.xaxis2` etc do not have to be explicitly defined, in which case default values will be inferred. Multiple traces of different types can be drawn on the same subplot.

Diff for: doc/python/getting-started.md

@@ -59,13 +59,13 @@ We also encourage you to join the [Plotly Community Forum](http://community.plot
 `plotly` may be installed using pip...
 
 ```
-$ pip install plotly==4.11.0
+$ pip install plotly==4.12.0
 ```
 
 or conda.
 
 ```
-$ conda install -c plotly plotly=4.11.0
+$ conda install -c plotly plotly=4.12.0
 ```
 
 This package contains everything you need to write figures to standalone HTML files.
@@ -144,10 +144,10 @@ Then run the following commands to install the required JupyterLab extensions (n
 
 ```
 # JupyterLab renderer support
-jupyter labextension install jupyterlab-plotly@4.11.0
+jupyter labextension install jupyterlab-plotly@4.12.0
 
 # OPTIONAL: Jupyter widgets extension
-jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.11.0
+jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.12.0
 ```
 
 These packages contain everything you need to run JupyterLab...