Merge pull request #942 from plotly/ipyplotly_integration

Plotly 3.0.0 - Deep Jupyter Integration, Validation, Performance, and More

Author: jonmmease

.gitignore

@@ -10,14 +10,28 @@
 
 *.tox
 
-build
-
-dist
-
 debug_script.py
 
 test_output.txt
 
 plotly/api/v2/spectacle_presentations.py
 
-plotly/presentation_objs/
+plotly/presentation_objs/
+
+.idea
+
+js/node_modules/
+
+# Compiled javascript
+plotlywidget/static/
+
+.pytest_cache
+
+# virtual envs
+vv
+venv
+
+# dist files
+build
+dist
+plotly.egg-info/

CHANGELOG.md

@@ -2,9 +2,22 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
-## [2.7.1] - [UNRELEASED]
-### Updated
-- error message for `plotly.figure_factory.create_choropleth` is now helpful to Anaconda users who do not have the correct modules installed for the County Choropleth figure factory.
+## 3.0.0 - 2018-07-05
+
+This is a major version with many exciting updates. See the [Introducing plotly.py 3.0.0](https://medium.com/@plotlygraphs/introducing-plotly-py-3-0-0-7bb1333f69c6) post for more information.
+
+### Added
+- Full Jupyter ipywidgets integration with the new `graph_objs.FigureWidget` class
+- `FigureWidget` figures can be updated interactively using property assignment syntax
+- The full trace and layout API is generated from the plotly schema to provide a great experience for interactive use in the notebook
+- Support for setting array properties as numpy arrays. When numpy arrays are used, ipywidgets binary serialization protocol is used to avoid converting these to JSON strings.
+- Context manager API for animation. Run `help(go.Figure().batch_animate)` for the full doc string.
+- Perform automatic retries when communicating with plot.ly services. This introduces a new required dependency on the [retrying](https://pypi.org/project/retrying/) library.
+- Improved data validation covering the full API with clear, informative error messages. This means that incorrect properties and/or values now always raise a `ValueError` with a description of the error, the invalid property, and the available properties on the level that it was placed in the graph object. Eg. `go.Scatter(foo=123)` raises a validation error. See https://plot.ly/python/reference/ for a reference to all valid properties and values in the Python API.
+- Error message for `plotly.figure_factory.create_choropleth` is now helpful to Anaconda users who do not have the correct modules installed for the County Choropleth figure factory.
+
+### Changed / Deprecated
+Please see the [migration guid](migration-guide.md) for a full list of the changes and deprecations in version 3.0.0
 
 ## [2.7.0] - 2018-05-23
 ### Updated

MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.rst
+include README.md
+include plotlywidget.json

README.md

@@ -1,11 +1,6 @@
 # plotly.py
 
-> 📢  Announcement!  
-> Registration is open for a 2 day, Dash master class in Washington DC, June 9-10.  
-> [Register online here](https://plotcon.plot.ly/tickets/) 🎚📈🏛
-
-***
-
+## Overview
 [plotly.py](https://plot.ly/d3-js-for-python-and-pandas-charts/) is an interactive, browser-based graphing library for Python :sparkles:
 
 Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is a high-level, declarative charting library. plotly.js ships with over 30 chart types, including scientific charts, 3D graphs, statistical charts, SVG maps, financial charts, and more.
@@ -22,14 +17,42 @@ Built on top of [plotly.js](https://github.com/plotly/plotly.js), `plotly.py` is
 ***
 
 - [Online Documentation](https://plot.ly/python)
-- [`contributing.md`](https://github.com/plotly/python-api/blob/master/contributing.md)
+- [Contributing](contributing.md)
+- [Changelog](CHANGELOG.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
+- [Version 3 Migration Guide](migration-guide.md)
 - [New! Announcing Dash](https://medium.com/@plotlygraphs/introducing-dash-5ecf7191b503)
 - [Community](https://community.plot.ly/c/api/python)
 
 ***
 
-Code and documentation copyright 2017 Plotly, Inc.
+## Installation of plotly.py Version 3
+To install plotly.py and enable Jupyter or Jupyter Lab support, run:
+```
+pip install "plotly>=3.0"
+pip install "notebook>=5.3" "ipywidgets>=7.2"  # only necessary for Jupyter Notebook environments
+```
+
+If you're using older versions of `notebook` or `ipywidgets` you may need to manually activate the widget extensions (this should not be needed for `notebook>=5.3` and `ipywidgets>=7.2`)
+
+```
+jupyter nbextension enable --py widgetsnbextension --sys-prefix
+jupyter nbextension enable --py plotlywidget --sys-prefix
+```
+
+In addition, to add JupyterLab support run the following commands
+
+```
+pip install jupyterlab
+export NODE_OPTIONS=--max-old-space-size=4096
+jupyter labextension install @jupyter-widgets/jupyterlab-manager # install the Jupyter widgets extension
+jupyter labextension install plotlywidget
+```
+
+If you're migrating from plotly.py version 2, please check out the [migration guid](migration-guide.md)
+
+## Copyright and Licenses
+Code and documentation copyright 2018 Plotly, Inc.
 
 Code released under the [MIT license](LICENSE.txt).
 

_plotly_utils/README.md

@@ -0,0 +1,7 @@
+This package is for utilities that are used during code generation
+and at runtime.  The reason for not placing these under the main plotly/
+package is that this avoids the complications of importing the module
+we're generating code into during code generation.
+
+This module must be independent of (it must not import from) both
+plotly/ and codegen/