|
1 | 1 | # 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/ |
81 | 3 |
|
82 | 4 | # Migration to Version 3
|
83 | 5 | 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