merging master

Author: nicolaskruchten

.circleci/create_conda_optional_env.sh

@@ -16,7 +16,7 @@ if [ ! -d $HOME/miniconda/envs/circle_optional ]; then
     # Create environment
     # PYTHON_VERSION=2.7 or 3.5
     $HOME/miniconda/bin/conda create -n circle_optional --yes python=$PYTHON_VERSION \
-requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets
+requests nbformat six retrying psutil pandas decorator pytest mock nose poppler xarray scikit-image ipython jupyter ipykernel ipywidgets statsmodels
 
     # Install orca into environment
     $HOME/miniconda/bin/conda install --yes -n circle_optional -c plotly plotly-orca==1.3.1

.github/pull_request_template.md

@@ -32,5 +32,6 @@ below :-).
   modified existing tests.
 - [ ] 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.
 
 -->

CHANGELOG.md

@@ -2,6 +2,21 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Dev version
+
+### 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).
+
+### 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
 
 ### Updated

doc/python/hover-text-and-formatting.md

@@ -123,7 +123,7 @@ fig.show()
 
 ### Customizing Hover text with Plotly Express
 
-Plotly Express functions automatically add all the data being plotted (x, y, color etc) to the hover label. Many Plotly Express functions also support configurable hover text. The `hover_data` argument accepts a list of column names to be added to the hover tooltip. The `hover_name` property controls which column is displayed in bold as the tooltip title.
+Plotly Express functions automatically add all the data being plotted (x, y, color etc) to the hover label. Many Plotly Express functions also support configurable hover text. The `hover_data` argument accepts a list of column names to be added to the hover tooltip, or a dictionary for advanced formatting (see the next section). The `hover_name` property controls which column is displayed in bold as the tooltip title.
 
 Here is an example that creates a scatter plot using Plotly Express with custom hover data and a custom hover name.
 
@@ -138,15 +138,42 @@ fig = px.scatter(df_2007, x="gdpPercap", y="lifeExp", log_x=True,
 fig.show()
 ```
 
+### Disabling or customizing hover of columns in plotly express
+
+`hover_data` can also be a dictionary. Its keys are existing columns of the `dataframe` argument, or new labels. For an existing column, the values can be
+* `False` to remove the column from the hover data (for example, if one wishes to remove the column of the `x` argument)
+* `True` to add a different column, with default formatting
+* a formatting string starting with `:` for numbers [d3-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#d3_forma), and `|` for dates in [d3-time-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md#format), for example `:.3f`, `|%a`.
+
+It is also possible to pass new data as values of the `hover_data` dict, either as list-like data, or inside a tuple, which first element is one of the possible values described above for existing columns, and the second element correspond to the list-like data, for example `(True, [1, 2, 3])` or `(':.1f', [1.54, 2.345])`.
+
+These different cases are illustrated in the following example.
+
+```python
+import plotly.express as px
+import numpy as np
+df = px.data.iris()
+fig = px.scatter(df, x='petal_length', y='sepal_length', facet_col='species', color='species',
+                 hover_data={'species':False, # remove species from hover data
+                             'sepal_length':':.2f', # customize hover for column of y attribute
+                             'petal_width':True, # add other column, default formatting
+                             'sepal_width':':.2f', # add other column, customized formatting
+                             # data not in dataframe, default formatting
+                             'suppl_1': np.random.random(len(df)),
+                             # data not in dataframe, customized formatting
+                             'suppl_2': (':.3f', np.random.random(len(df)))
+                            })
+fig.update_layout(height=300)
+fig.show()
+```
+
 ### Customizing hover text with a hovertemplate
 
-To customize the tooltip on your graph you can use [hovertemplate](https://plotly.com/python/reference/#pie-hovertemplate), which is a template string used for rendering the information that appear on hoverbox.
+To customize the tooltip on your graph you can use the [hovertemplate](https://plotly.com/python/reference/#pie-hovertemplate) attribute of `graph_objects` tracces, which is a template string used for rendering the information that appear on hoverbox.
 This template string can include `variables` in %{variable} format, `numbers` in [d3-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Formatting.md#d3_forma), and `date` in [d3-time-format's syntax](https://github.com/d3/d3-3.x-api-reference/blob/master/Time-Formatting.md#format).
 Hovertemplate customize the tooltip text vs. [texttemplate](https://plotly.com/python/reference/#pie-texttemplate) which customizes the text that appears on your chart. <br>
 Set the horizontal alignment of the text within tooltip with [hoverlabel.align](https://plotly.com/python/reference/#layout-hoverlabel-align).
 
-Plotly Express automatically sets the `hovertemplate`, but you can set it manually when using `graph_objects`.
-
 ```python
 import plotly.graph_objects as go
 
@@ -187,6 +214,24 @@ fig = go.Figure(go.Pie(
 fig.show()
 ```
 
+### Modifying the hovertemplate of a plotly express figure
+
+`plotly.express` automatically sets the hovertemplate but you can modify it using the `update_traces` method of the generated figure. It helps to print the hovertemplate generated by `plotly.express` in order to be able to modify it. One can also revert to the default hover information of traces by setting the hovertemplate to `None`.
+
+```python
+import plotly.express as px
+
+df_2007 = px.data.gapminder().query("year==2007")
+
+fig = px.scatter(df_2007, x="gdpPercap", y="lifeExp", log_x=True, color='continent'
+                )
+print("plotly express hovertemplate:", fig.data[0].hovertemplate)
+fig.update_traces(hovertemplate='GDP: %{x} <br>Life Expectany: %{y}') # 
+fig.update_traces(hovertemplate=None, selector={'name':'Europe'}) # revert to default hover
+print("user_defined hovertemplate:", fig.data[0].hovertemplate)
+fig.show()
+```
+
 ### Advanced Hover Template
 
 The following example shows how to format hover template. [Here](https://plotly.com/python/v3/hover-text-and-formatting/#dash-example) is an example to see how to format hovertemplate in Dash.

doc/python/imshow.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 display image data in Python with Plotly.
     display_as: scientific

packages/python/plotly/_plotly_utils/basevalidators.py

@@ -2438,12 +2438,12 @@ def description(self):
 
         return desc
 
-    def validate_coerce(self, v, skip_invalid=False):
+    def validate_coerce(self, v, skip_invalid=False, _validate=True):
         if v is None:
             v = self.data_class()
 
         elif isinstance(v, dict):
-            v = self.data_class(v, skip_invalid=skip_invalid)
+            v = self.data_class(v, skip_invalid=skip_invalid, _validate=_validate)
 
         elif isinstance(v, self.data_class):
             # Copy object
@@ -2614,7 +2614,7 @@ def get_trace_class(self, trace_name):
 
         return self._class_map[trace_name]
 
-    def validate_coerce(self, v, skip_invalid=False):
+    def validate_coerce(self, v, skip_invalid=False, _validate=True):
         from plotly.basedatatypes import BaseTraceType
 
         # Import Histogram2dcontour, this is the deprecated name of the
@@ -2649,15 +2649,15 @@ def validate_coerce(self, v, skip_invalid=False):
                         if skip_invalid:
                             # Treat as scatter trace
                             trace = self.get_trace_class("scatter")(
-                                skip_invalid=skip_invalid, **v_copy
+                                skip_invalid=skip_invalid, _validate=_validate, **v_copy
                             )
                             res.append(trace)
                         else:
                             res.append(None)
                             invalid_els.append(v_el)
                     else:
                         trace = self.get_trace_class(trace_type)(
-                            skip_invalid=skip_invalid, **v_copy
+                            skip_invalid=skip_invalid, _validate=_validate, **v_copy
                         )
                         res.append(trace)
                 else:

packages/python/plotly/codegen/__init__.py

@@ -266,7 +266,6 @@ def perform_codegen():
     for dep_clas in DEPRECATED_DATATYPES:
         root_datatype_imports.append(f"._deprecations.{dep_clas}")
 
-    validate_import = "from .._validate import validate\n"
     optional_figure_widget_import = f"""
 if sys.version_info < (3, 7):
     try:
@@ -307,7 +306,7 @@ def __getattr__(import_name):
         rel_classes = datatype_rel_class_imports[path_parts]
         rel_modules = datatype_rel_module_imports.get(path_parts, [])
         if path_parts == ():
-            init_extra = validate_import + optional_figure_widget_import
+            init_extra = optional_figure_widget_import
         else:
             init_extra = ""
         write_init_py(graph_objs_pkg, path_parts, rel_modules, rel_classes, init_extra)
@@ -325,7 +324,7 @@ def __getattr__(import_name):
     graph_objects_init_source = build_from_imports_py(
         graph_objects_rel_modules,
         graph_objects_rel_classes,
-        init_extra=validate_import + optional_figure_widget_import,
+        init_extra=optional_figure_widget_import,
     )
     graph_objects_path = opath.join(outdir, "graph_objects", "__init__.py")
     os.makedirs(opath.join(outdir, "graph_objects"), exist_ok=True)

packages/python/plotly/codegen/datatypes.py

@@ -349,6 +349,7 @@ def __init__(self"""
         # Handle skip_invalid
         # -------------------
         self._skip_invalid = kwargs.pop('skip_invalid', False)
+        self._validate = kwargs.pop('_validate', True)
         """
     )
 

packages/python/plotly/plotly/__init__.py

@@ -72,7 +72,6 @@
             ".io",
             ".data",
             ".colors",
-            ".express",
         ],
         [".version.__version__"],
     )