Skip to content

Commit cbf9b84

Browse files
committed
Update migration guide to reference v4-migration documentation page
1 parent f589b66 commit cbf9b84

File tree

1 file changed

+1
-79
lines changed

1 file changed

+1
-79
lines changed

migration-guide.md

+1-79
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,5 @@
11
# Migration to Version 4
2-
This section contains guidance for migrating from plotly.py version 3 to version 4.
3-
4-
## Online features moved to chart-studio package.
5-
Prior versions of plotly.py contained functionality for creating figures in both "online" and "offline" modes. In "online" mode figures were uploaded to the Chart Studio cloud (or on-premise) service, whereas in "offline" mode figures were rendered locally. In version 4, all "online" functionality has been removed from the main `plotly` distribution package and moved to the new `chart-studio` distribution package.
6-
7-
To migrate version 3 "online" functionality, first install the `chart-studio` package using pip...
8-
9-
```
10-
$ pip install chart-studio
11-
```
12-
13-
of conda.
14-
15-
```
16-
$ conda install -c plotly chart-studio
17-
```
18-
19-
Then, update your Python import statements to import "online" functionality from the top-level `chart_studio` package, rather than the top-level `plotly` package. For example. replace
20-
21-
```python
22-
from plotly.plotly import plot, iplot
23-
```
24-
25-
with
26-
27-
```python
28-
from chart_studio.plotly import plot, iplot
29-
```
30-
31-
Similarly,
32-
`plotly.api` -> `chart_studio.api`
33-
`plotly.dashboard_objs` -> `chart_studio.dashboard_objs`
34-
`plotly.grid_objs` -> `chart_studio.grid_objs`
35-
`plotly.presentation_objs` -> `chart_studio.presentation_objs`
36-
`plotly.widgets` -> `chart_studio.widgets`
37-
38-
39-
## New default theme
40-
A new default theme has been enabled for figures created with plotly.py version 4. You can revert to the version 3 figure appearance by disabling the default theme as follows:
41-
42-
```python
43-
import plotly.io as pio
44-
pio.templates.default = 'none'
45-
```
46-
See https://plot.ly/python-next/renderers for more information on theming in plotly.py version 4
47-
48-
## Add trace return value
49-
In version 3, the `add_trace` graph object figure method returned a reference to the newly created trace. This was also the case for the `add_{trace_type}` methods (e.g. `add_scatter`, `add_bar`, etc.). In version 4, these methods return a reference to the calling figure. This change was made to support method chaining of figure operations. For example
50-
51-
```python
52-
from plotly.subplots import make_subplots
53-
(make_subplots(rows=1, cols=2)
54-
.add_scatter(y=[2, 1, 3], row=1, col=1)
55-
.add_bar(y=[3, 2, 1], row=1, col=2)
56-
.update_layout(title_text='Figure title')
57-
.show())
58-
```
59-
60-
Code that relied on the `add_*` methods to return a reference to the newly created trace can be updated as follows.
61-
62-
63-
64-
65-
## Renderers framework
66-
Version 4 introduces a new renderers framework that is a generalization of the `plotly.offline.init_notebook_mode` and `plotly.offline.iplot` functions for displaying figures. The `plotly.offline.iplot` function is still available and has been reimplemented on top of the renderers framework, so no changes are required when poritng to version 4. Going forward, we recommend using the renderers framework directly. See https://plot.ly/python-next/renderers for more information.
67-
68-
69-
70-
71-
72-
73-
74-
## Removals
75-
76-
### fileopt argument removal
77-
The `fileopt` argument to `chart_studio.plotly.plot` has been removed, so in-place modifications to previously published figures are no longer supported.
78-
79-
80-
2+
See https://plot.ly/python/next/v4-migration/
813

824
# Migration to Version 3
835
There are many new and great features in plotly.py 3.0 including deeper Jupyter integration, deeper figure validation, improved performance, and more. This guide contains a summary of the breaking changes that you need to be aware of when migrating code from version 2 to version 3.

0 commit comments

Comments
 (0)