8000 changelog and doc tweaks · samaffolter/plotly.py@c929086 · GitHub
[go: up one dir, main page]
Skip to content

Commit c929086

Browse files
nicolaskruchtennicolaskruchten
committed
changelog and doc tweaks
1 parent 4fd8736 commit c929086

File tree

6 files changed

+75
-49
lines changed

6 files changed

+75
-49
lines changed

‎CHANGELOG.md

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,27 @@ This project adheres to [Semantic Versioning](http://semver.org/).
44

55
## [4.9.0] - unreleased
66

7-
### Updated
8-
9-
- Updated Plotly.js to version 1.54.6. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.6/CHANGELOG.md) for more information.
10-
- Added all cartesian-2d Plotly Express functions, plus `imshow` to Pandas backend with `kind` option
11-
- `plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
12-
-
137
### Added
148

159
- Added image export support using [Kaleido](https://github.com/plotly/Kaleido). The image export backend can be configured using the new `engine` argument to `plotly.io.to_image` and `plotly.io.write_image`. The `engine` argument may be set to `"kaleido"`, `"orca"`, or `"auto"`. The default is `engine="auto"`, in which case the Kaleido backend is enabled if the `kaleido` package from PyPI is installed, otherwise Orca is used. ([#2613](https://github.com/plotly/plotly.py/pull/2613)).
16-
- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
10+
- `plotly.express.timeline()` added as an official alternative to `plotly.figure_factories.create_gantt()` ([#2626](https://github.com/plotly/plotly.py/pull/2626))
11+
- `create_hexbin_mapbox()` added to Figure Factories, with thanks to [@RenaudLN](https://github.com/RenaudLN) for the impressive contribution!
1712
- `facet_row_spacing` and `facet_col_spacing` added to Plotly Express cartesian 2d functions ([#2614](https://github.com/plotly/plotly.py/pull/2614))
18-
- `base` added to Plotly Express `bar` and `bar_polar` functions
19-
- `plotly.express.timeline()` added as an official alternative to `plotly.figure_factories.create_gantt()`
20-
- `create_hexbin_mapbox()` added to Figure Factories, with thanks to [@RenaudLN](https://github.com/RenaudLN) for the contribution!
13+
- `base` added to Plotly Express `bar` and `bar_polar` functions ([#2626](https://github.com/plotly/plotly.py/pull/2626))
14+
- `px.NO_COLOR` constant to override wide-form color assignment in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
2115

2216
### Fixed
2317

2418
- trendline traces are now of type `scattergl` when `render_mode="webgl"` in Plotly Express ([#2614](https://github.com/plotly/plotly.py/pull/2614))
19+
- regression from 4.8.1 whereby `"parent"` was not accepted as part of `path` for `px.sunburst()` and `px.treemap()` ([#2640](https://github.com/plotly/plotly.py/pull/2640))
20+
- `create_dendrogram()` figure factory now works correctly with `scipy` 1.5.1 ([#2627](https://github.com/plotly/plotly.py/pull/2627))
21+
22+
### Updated
23+
24+
- Updated Plotly.js to version 1.54.6. See the [plotly.js CHANGELOG](https://github.com/plotly/plotly.js/blob/v1.54.6/CHANGELOG.md) for more information.
25+
- Added all cartesian-2d Plotly Express functions, plus `imshow`, to Pandas backend with `kind` option ([#2541](https://github.com/plotly/plotly.py/pull/2541))
26+
- `plotly.express.imshow` now uses data frame index and columns names and values to populate axis parameters by default ([#2539](https://github.com/plotly/plotly.py/pull/2539))
27+
- Javascript extensions are now build using Node 12, and have an updated `package-lock.json` with many fewer security warnings ([#2636](https://github.com/plotly/plotly.py/pull/2636))
2528

2629

2730
## [4.8.2] - 2020-06-26

‎README.md

Lines changed: 16 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -133,24 +133,33 @@ jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.
133133

134134
Please check out our [Troubleshooting guide](https://plotly.com/python/troubleshooting/) if you run into any problems with JupyterLab.
135135

136-
### Static Image Export with Kaleido
136+
### Static Image Export
137137

138-
plotly.py supports static image export using the `to_image` and `write_image`
139-
functions in the `plotly.io` module. This functionality requires the
140-
[`kaleido`](https://github.com/plotly/Kaleido) package which can be installed
138+
plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
139+
using the either the [`kaleido`](https://github.com/plotly/Kaleido)
140+
package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca)
141+
command line utility (legacy as of `plotly` version 4.9).
142+
143+
#### Kaleido
144+
145+
The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
141146
using pip...
142147

143148
```
144149
$ pip install -U kaleido
145150
```
146151

147152
or conda.
153+
148154
```
149155
$ conda install -c plotly python-kaleido
150-
```
156+
```
151157

152-
### Static Image Export with Orca
153-
While Kaleido is now the recommended image export approach because it is easier to install and more widely compatible, image export can also be supported
158+
#### Orca
159+
160+
While Kaleido is now the recommended image export approach because it is easier to install
161+
and more widely compatible, [static image export](https://plotly.com/python/static-image-export/)
162+
can also be supported
154163
by the legacy [orca](https://github.com/plotly/orca) command line utility and the
155164
[`psutil`](https://github.com/giampaolo/psutil) Python package.
156165

@@ -168,13 +177,6 @@ pip install psutil
168177

169178
and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
170179

171-
#### Troubleshooting
172-
173-
##### Wrong Executable found
174-
175-
If you get an error message stating that the `orca` executable that was found is not valid, this may be because another executable with the same name was found on your system. Please specify the complete path to the Plotly-Orca binary that you downloaded (for instance in the Miniconda folder) with the following command:
176-
177-
`plotly.io.orca.config.executable = '/home/your_name/miniconda3/bin/orca'`
178180

179181
### Extended Geo Support
180182

‎doc/python/getting-started.md

Lines changed: 26 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -180,42 +180,49 @@ Please check out our [Troubleshooting guide](/python/troubleshooting/) if you ru
180180

181181
See [_Displaying Figures in Python_](/python/renderers/) for more information on the renderers framework, and see [_Plotly FigureWidget Overview_](/python/figurewidget/) for more information on using `FigureWidget`.
182182

183-
#### Static Image Export Support
183+
### Static Image Export
184184

185-
plotly.py supports static image export using the `to_image` and `write_image`
186-
functions in the `plotly.io` package. This functionality requires the
187-
installation of the plotly [orca](https://github.com/plotly/orca) command line utility and the
188-
[`psutil`](https://github.com/giampaolo/psutil) and [`requests`](https://2.python-requests.org/en/master/) Python packages.
185+
plotly.py supports [static image export](https://plotly.com/python/static-image-export/),
186+
using the either the [`kaleido`](https://github.com/plotly/Kaleido)
187+
package (recommended, supported as of `plotly` version 4.9) or the [orca](https://github.com/plotly/orca)
188+
command line utility (legacy as of `plotly` version 4.9).
189189

190-
> Note: The `requests` library is used to communicate between the Python process and a local orca server process, it is not used to communicate with any external services.
190+
#### Kaleido
191191

192-
These dependencies can all be installed using conda:
192+
The [`kaleido`](https://github.com/plotly/Kaleido) package has no dependencies and can be installed
193+
using pip...
193194

194195
```
195-
$ conda install -c plotly plotly-orca==1.2.1 psutil requests
196+
$ pip install -U kaleido
196197
```
197198

198-
Or, `psutil` and `requests` can be installed using pip...
199+
or conda.
199200

200201
```
201-
$ pip install psutil requests
202+
$ conda install -c plotly python-kaleido
202203
```
203204

204-
and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
205+
#### Orca
205206

206-
These packages contain everything you need to save figures as static images.
207+
While Kaleido is now the recommended image export approach because it is easier to install
208+
and more widely compatible, [static image export](https://plotly.com/python/static-image-export/)
209+
can also be supported
210+
by the legacy [orca](https://github.com/plotly/orca) command line utility and the
211+
[`psutil`](https://github.com/giampaolo/psutil) Python package.
207212

208-
<!-- #endregion -->
213+
These dependencies can both be installed using conda:
209214

210-
```python
211-
import plotly.graph_objects as go
212-
fig = go.FigureWidget(data=go.Bar(y=[2, 3, 1]))
213-
fig.write_image('figure.png')
215+
```
216+
conda install -c plotly plotly-orca==1.3.1 psutil
214217
```
215218

216-
<!-- #region -->
219+
Or, `psutil` can be installed using pip...
220+
221+
```
222+
pip install psutil
223+
```
217224

218-
See [_Static Image Export in Python_](/python/static-image-export/) for more information on static image export.
225+
and orca can be installed according to the instructions in the [orca README](https://github.com/plotly/orca).
219226

220227
#### Extended Geo Support
221228

‎doc/python/orca-management.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ jupyter:
3636
### Overview
3737
This section covers the lower-level details of how plotly.py can use orca to perform static image generation.
3838

39-
> Orca is no longer the recommended way to do static image export. We now recommend Kaleido, as described in the [Static Image Export](/python/static-image-export/) section .
39+
> As of `plotly` version 4.9, Orca is no longer the recommended way to do static image export. We now recommend Kaleido, as described in the [Static Image Export](/python/static-image-export/) section .
4040
4141
Please refer to the [Static Image Export](/python/static-image-export/) section for general information on creating static images from plotly.py figures.
4242

‎doc/python/static-image-export.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,21 +42,23 @@ Plotly figures are interactive when viewed in a web browser: you can hover over
4242

4343
<!-- #region -->
4444
#### Install Dependencies
45-
Static image generation requires either [Kaleido](https://github.com/plotly/Kaleido) (recommended) or [orca](https://github.com/plotly/orca) (legacy). The `kaleido` package can be installed using pip...
45+
46+
Static image generation requires either [Kaleido](https://github.com/plotly/Kaleido) (recommended, supported as of `plotly` 4.9) or [orca](https://github.com/plotly/orca) (legacy as of `plotly` 4.9). The `kaleido` package can be installed using pip...
4647
```
4748
$ pip install -U kaleido
4849
```
4950

5051
or conda.
5152
```
5253
$ conda install -c plotly python-kaleido
53-
```
54+
```
5455

5556
While Kaleido is now the recommended approach, image export can also be supported by the legacy [orca](https://github.com/plotly/orca) command line utility. See the [Orca Management](/python/orca-management/) section for instructions on installing, configuring, and troubleshooting orca.
5657

5758
<!-- #endregion -->
5859

5960
### Create a Figure
61+
6062
Now let's create a simple scatter plot with 100 random points of varying color and size.
6163

6264
```python
@@ -87,6 +89,7 @@ fig.show()
8789
```
8890

8991
### Write Image File
92+
9093
The `plotly.io.write_image` function is used to write an image to a file or file-like python object. You can also use the `.write_image` graph object figure method.
9194

9295
Let's first create an output directory to store our images
@@ -146,6 +149,7 @@ fig.write_image("images/fig1.eps")
146149
**Note:** It is important to note that any figures containing WebGL traces (i.e. of type `scattergl`, `heatmapgl`, `contourgl`, `scatter3d`, `surface`, `mesh3d`, `scatterpolargl`, `cone`, `streamtube`, `splom`, or `parcoords`) that are exported in a vector format will include encapsulated rasters, instead of vectors, for some parts of the image.
147150

148151
### Get Image as Bytes
152+
149153
The `plotly.io.to_image` function is used to return an image as a bytes object. You can also use the `.to_image` graph object figure method.
150154

151155
Let convert the figure to a **PNG** bytes object...
@@ -178,7 +182,7 @@ Image(img_bytes)
178182

179183
<!-- #region -->
180184
### Specify Image Export Engine
181-
If `kaleido` is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to use orca instead. The `engine` argument to the `to_image` and `write_image` functions can be used to override this default behavior.
185+
If `kaleido` is installed, it will automatically be used to perform image export. If it is not installed, plotly.py will attempt to use `orca` instead. The `engine` argument to the `to_image` and `write_image` functions can be used to override this default behavior.
182186

183187
Here is an example of specifying that orca should be used:
184188
```python
@@ -199,7 +203,7 @@ Various image export settings can be configured using the `plotly.io.kaleido.sco
199203
```python
200204
import plotly.io as pio
201205
pio.kaleido.scope.default_format = "svg"
202-
```
206+
```
203207

204208
Here is a complete listing of the available image export settings:
205209

‎doc/python/troubleshooting.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,4 +102,14 @@ unset NODE_OPTIONS
102102
set NODE_OPTIONS=
103103
```
104104

105-
<!-- #endregion -->
105+
<!-- #endregion -->
106+
107+
108+
### Orca Problems
109+
110+
> Note: as of `plotly` version 4.9, we recommend using [`kaleido`](https://github.com/plotly/Kaleido)
111+
> instead of Orca for [static image export](/python/static-image-export/)
112+
113+
If you get an error message stating that the `orca` executable that was found is not valid, this may be because another executable with the same name was found on your system. Please specify the complete path to the Plotly-Orca binary that you downloaded (for instance in the Miniconda folder) with the following command:
114+
115+
`plotly.io.orca.config.executable = '/home/your_name/miniconda3/bin/orca'`

0 commit comments

Comments
 (0)
0