Merge branch 'master' into deep-magic-underscore-error-msg-rebase

Author: nicholas-esterer

.gitattributes

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

.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).
 
 -->

.gitignore

@@ -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

CHANGELOG.md

@@ -2,15 +2,30 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## [4.12.0] - unreleased
+## [4.13.0] - UNRELEASED
+
+
+
+## [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.0. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.57.0/CHANGELOG.md) for more information. These changes are reflected in the auto-generated `plotly.graph_objects` module.
+- 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
 

README.md

@@ -37,7 +37,7 @@ Our recommended IDE for Plotly’s Python graphing library is Dash Enterprise’
 
 ## 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"`):
 
@@ -86,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
@@ -129,10 +129,10 @@ 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.

binder/requirements.txt

@@ -1,5 +1,5 @@
 jupytext
-plotly==4.11.0
+plotly==4.12.0
 jupyter
 notebook
 pandas==1.0.3

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 ---------------------------------------------------

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.

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...

doc/python/horizontal-vertical-shapes.md

@@ -0,0 +1,121 @@
+---
+jupyter:
+  jupytext:
+    notebook_metadata_filter: all
+    text_representation:
+      extension: .md
+      format_name: markdown
+      format_version: '1.2'
+      jupytext_version: 1.3.0
+  kernelspec:
+    display_name: Python 3
+    language: python
+    name: python3
+  language_info:
+    codemirror_mode:
+      name: ipython
+      version: 3
+    file_extension: .py
+    mimetype: text/x-python
+    name: python
+    nbconvert_exporter: python
+    pygments_lexer: ipython3
+    version: 3.7.3
+  plotly:
+    description: How to add annotated horizontal and vertical lines in Python.
+    display_as: file_settings
+    language: python
+    layout: base
+    name: Shapes
+    order: 37
+    permalink: python/horizontal-vertical-shapes/
+    thumbnail: thumbnail/horizontal-vertical-shapes.jpg
+---
+
+### Horizontal and Vertical Lines and Boxes (Autoshapes) in Plotly.py
+
+*introduced in plotly 4.12*
+
+Horizontal and vertical lines and rectangles (autoshapes) that span an entire
+plot can be added via the `add_hline`, `add_vline`, `add_hrect`, and `add_vrect`
+methods of `plotly.graph_objects.Figure`. Shapes added with these methods are
+added as [layout shapes](/python/shapes) (as shown when doing `print(fig)`, for
+example). These shapes are fixed to the endpoints of one axis, regardless of the
+range of the plot, and fixed to data coordinates on the other axis. The
+following shows some possibilities, try panning and zooming the resulting figure
+to see how the shapes stick to some axes:
+
+
+```python
+import plotly.express as px
+
+df = px.data.iris()
+fig = px.scatter(df, x="sepal_length", y="sepal_width")
+
+# Add a vertical line that spans the entire y axis
+# intersecting the x axis at x=5
+fig.add_vline(x=5, line_color="red")
+# Add a horizontal line that spans the entire x axis
+# intersecting the y axis at y=3
+fig.add_hline(y=3, line_color="blue")
+# Add a vertical rectangle that spans the entire y axis
+# intersecting the x axis at 5.5 and 6.5
+fig.add_vrect(x0=5.5, x1=6.5, line_color="purple")
+# Add a horizontal rectangle that spans the entire x axis
+# intersecting the y axis at 2.5 and 4
+fig.add_hrect(y0=2.5, y1=4, line_color="orange")
+# (try panning and zooming the plot)
+fig.show()
+```
+
+#### Adding Autoshapes to Multiple Facets / Subplots
+
+The same line or box can be added to multiple facets by using the `'all'`
+keyword in the `row` and `col` arguments like with `Figure.add_shape`. For
+example
+```python
+import plotly.express as px
+
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex")
+# Adds a vertical line to all facets
+fig.add_vline(x=30, row="all", col="all", line_color="purple")
+# Adds a horizontal line to all the rows of the second column
+fig.add_hline(y=6, row="all", col=2, line_color="yellow")
+# Adds a vertical rectangle to all the columns of the first row
+fig.add_vrect(x0=20, x1=40, row=1, col="all", line_color="green")
+fig.show()
+```
+The default `row` and `col` values are `"all"` so
+`fig.add_vline(x=30, line_color="purple")` is equivalent
+to `fig.add_vline(x=30, row="all", col="all", line_color="purple")` in the above
+example.
+
+#### Adding Text Annotations to Autoshapes
+
+Text [annotations](/python/text-and-annotations) can be added to an autoshape
+using the `annotation` keyword. Using the above example:
+```python
+import plotly.express as px
+import plotly.graph_objects as go
+
+df = px.data.tips()
+fig = px.scatter(df, x="total_bill", y="tip", facet_row="smoker", facet_col="sex")
+# Add annotations anchored to the top right corner of the resulting lines
+fig.add_vline(x=30, line_color="purple", annotation=go.layout.Annotation(text="A"))
+# Another way to add annotations when we are only interested in specifying text
+fig.add_hline(y=6, row="all", col=2, line_color="yellow", annotation_text="B")
+# Specify the position of the resulting annotations
+fig.add_vrect(
+    x0=20,
+    x1=40,
+    row=1,
+    col="all",
+    line_color="green",
+    annotation_text="C",
+    annotation_position="bottom inside left",
+)
+fig.show()
+```
+Call `help` on any of the autoshape functions in the Python interpreter to learn
+more (e.g., `help(fig.add_vline)`).