Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 9c4b235

Browse filesBrowse files
KullyKully
committed
chris' comments
1 parent fdba978 commit 9c4b235
Copy full SHA for 9c4b235

File tree

3 files changed

+267
-13
lines changed
Filter options

3 files changed

+267
-13
lines changed

‎plotly/dashboard_objs/__init__.py

Copy file name to clipboard
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
from . dashboard_objs import Dashboard

‎plotly/dashboard_objs/dashboard_objs.py

Copy file name to clipboardExpand all lines: plotly/dashboard_objs/dashboard_objs.py
+205-3Lines changed: 205 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,69 @@
55
A module for creating and manipulating dashboard content. You can create
66
a Dashboard object, insert boxes, swap boxes, remove a box and get an HTML
77
preview of the Dashboard.
8+
9+
The current workflow for making and manipulating dashboard follows:
10+
1) Create a Dashboard
11+
2) Modify the Dashboard (insert, swap, remove, etc)
12+
3) Preview the Dashboard (run `.get_preview()`)
13+
4) Repeat steps 2) and 3) as long as desired
14+
15+
The basic box object that your insert into a dashboard is just a `dict`.
16+
The minimal dict for a box is:
17+
18+
```
19+
{
20+
'type': 'box',
21+
'boxType': 'plot'
22+
}
23+
```
24+
25+
where 'fileId' can be set to the 'username:#' of your plot. The other
26+
parameters
27+
a box takes are `shareKey` (default is None) and `title` (default is '').
28+
29+
You will need to use the `.get_preview()` method quite regularly as this will
30+
return an HTML representation of the dashboard in which the boxes in the HTML
31+
are labelled with on-the-fly-generated numbers which change after each
32+
modification to the dashboard.
33+
34+
Example: Create a simple Dashboard object
35+
```
36+
import plotly.dashboard_objs as dashboard
37+
38+
box_1 = {
39+
'type': 'box',
40+
'boxType': 'plot',
41+
'fileId': 'username:some#',
42+
'title': 'box 1'
43+
}
44+
45+
box_2 = {
46+
'type': 'box',
47+
'boxType': 'plot',
48+
'fileId': 'username:some#',
49+
'title': 'box 2'
50+
}
51+
52+
box_3 = {
53+
'type': 'box',
54+
'boxType': 'plot',
55+
'fileId': 'username:some#',
56+
'title': 'box 3'
57+
}
58+
59+
my_dboard = dashboard.Dashboard()
60+
my_dboard.insert(box_1)
61+
# my_dboard.get_preview()
62+
my_dboard.insert(box_2, 'above', 1)
63+
# my_dboard.get_preview()
64+
my_dboard.insert(box_3, 'left', 2)
65+
# my_dboard.get_preview()
66+
my_dboard.swap(1, 2)
67+
# my_dboard.get_preview()
68+
my_dboard.remove(1)
69+
# my_dboard.get_preview()
70+
```
871
"""
972

1073
import pprint
@@ -134,6 +197,70 @@ def _add_html_text(dashboard_html, text, top_left_x, top_left_y, box_w, box_h):
134197

135198

136199
class Dashboard(dict):
200+
"""
201+
Dashboard class for creating interactive dashboard objects.
202+
203+
Dashboards are dicts that contain boxes which hold plot information.
204+
These boxes can be arranged in various ways. The most basic form of
205+
a box is:
206+
207+
```
208+
{
209+
'type': 'box',
210+
'boxType': 'plot'
211+
}
212+
```
213+
214+
where 'fileId' can be set to the 'username:#' of your plot. The other
215+
parameters a box takes are `shareKey` (default is None) and `title`
216+
(default is '').
217+
218+
`.get_preview()` should be called quite regularly to get an HTML
219+
representation of the dashboard in which the boxes in the HTML
220+
are labelled with on-the-fly-generated numbers or box ids which
221+
change after each modification to the dashboard.
222+
223+
`.get_box()` returns the box located in the dashboard by calling
224+
its box id as displayed via `.get_preview()`.
225+
226+
Example: Create a simple Dashboard object
227+
```
228+
import plotly.dashboard_objs as dashboard
229+
230+
box_1 = {
231+
'type': 'box',
232+
'boxType': 'plot',
233+
'fileId': 'username:some#',
234+
'title': 'box 1'
235+
}
236+
237+
box_2 = {
238+
'type': 'box',
239+
'boxType': 'plot',
240+
'fileId': 'username:some#',
241+
'title': 'box 2'
242+
}
243+
244+
box_3 = {
245+
'type': 'box',
246+
'boxType': 'plot',
247+
'fileId': 'username:some#',
248+
'title': 'box 3'
249+
}
250+
251+
my_dboard = dashboard.Dashboard()
252+
my_dboard.insert(box_1)
253+
# my_dboard.get_preview()
254+
my_dboard.insert(box_2, 'above', 1)
255+
# my_dboard.get_preview()
256+
my_dboard.insert(box_3, 'left', 2)
257+
# my_dboard.get_preview()
258+
my_dboard.swap(1, 2)
259+
# my_dboard.get_preview()
260+
my_dboard.remove(1)
261+
# my_dboard.get_preview()
262+
```
263+
"""
137264
def __init__(self, content=None):
138265
if content is None:
139266
content = {}
@@ -160,7 +287,7 @@ def _compute_box_ids(self):
160287
max_id = max(box_ids_to_path.keys())
161288
except ValueError:
162289
max_id = 0
163-
box_ids_to_path[max_id + 1] = node[1] # list(...)
290+
box_ids_to_path[max_id + 1] = node[1]
164291

165292
return box_ids_to_path
166293

@@ -355,6 +482,27 @@ def insert(self, box, side='above', box_id=None):
355482
'left', and 'right'.
356483
:param (int) box_id: the box id which is used as the reference box for
357484
the insertion of the box.
485+
486+
Example:
487+
```
488+
import plotly.dashboard_objs as dashboard
489+
490+
box_1 = {
491+
'type': 'box',
492+
'boxType': 'plot',
493+
'fileId': 'username:some#',
494+
'title': 'box 1'
495+
}
496+
497+
my_dboard = dashboard.Dashboard()
498+
my_dboard.insert(box_1)
499+
my_dboard.insert(box_1, 'left', 1)
500+
my_dboard.insert(box_1, 'below', 2)
501+
my_dboard.insert(box_1, 'right', 3)
502+
my_dboard.insert(box_1, 'above', 4)
503+
504+
my_dboard.get_preview()
505+
```
358506
"""
359507
box_ids_to_path = self._compute_box_ids()
360508

@@ -403,7 +551,27 @@ def insert(self, box, side='above', box_id=None):
403551
self._set_container_sizes()
404552

405553
def remove(self, box_id):
406-
"""Remove a box from the dashboard by its box_id."""
554+
"""
555+
Remove a box from the dashboard by its box_id.
556+
557+
Example:
558+
```
559+
import plotly.dashboard_objs as dashboard
560+
561+
box_1 = {
562+
'type': 'box',
563+
'boxType': 'plot',
564+
'fileId': 'username:some#',
565+
'title': 'box 1'
566+
}
567+
568+
my_dboard = dashboard.Dashboard()
569+
my_dboard.insert(box_1)
570+
my_dboard.remove(1)
571+
572+
my_dboard.get_preview()
573+
```
574+
"""
407575
box_ids_to_path = self._compute_box_ids()
408576
if box_id not in box_ids_to_path:
409577
raise exceptions.PlotlyError(ID_NOT_VALID_MESSAGE)
@@ -424,7 +592,41 @@ def remove(self, box_id):
424592
self._set_container_sizes()
425593

426594
def swap(self, box_id_1, box_id_2):
427-
"""Swap two boxes with their specified ids."""
595+
"""
596+
Swap two boxes with their specified ids.
597+
598+
Example:
599+
```
600+
import plotly.dashboard_objs as dashboard
601+
602+
box_1 = {
603+
'type': 'box',
604+
'boxType': 'plot',
605+
'fileId': 'username:first#',
606+
'title': 'first box'
607+
}
608+
609+
box_2 = {
610+
'type': 'box',
611+
'boxType': 'plot',
612+
'fileId': 'username:second#',
613+
'title': 'second box'
614+
}
615+
616+
my_dboard = dashboard.Dashboard()
617+
my_dboard.insert(box_1)
618+
my_dboard.insert(box_2, 'above', 1)
619+
620+
# check box at box id 1
621+
box_at_1 = my_dboard.get_box(1)
622+
print(box_at_1)
623+
624+
my_dboard.swap(1, 2)
625+
626+
box_after_swap = my_dboard.get_box(1)
627+
print(box_after_swap)
628+
```
629+
"""
428630
box_ids_to_path = self._compute_box_ids()
429631
box_1 = self.get_box(box_id_1)
430632
box_2 = self.get_box(box_id_2)

‎plotly/plotly/plotly.py

Copy file name to clipboardExpand all lines: plotly/plotly/plotly.py
+61-10Lines changed: 61 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1348,8 +1348,50 @@ def get_grid(grid_url, raw=False):
13481348
class dashboard_ops:
13491349
"""
13501350
Interface to Plotly's Dashboards API.
1351+
13511352
Plotly Dashboards are JSON blobs. They are made up by a bunch of
13521353
containers which contain either empty boxes or boxes with file urls.
1354+
For more info on Dashboard objects themselves, run
1355+
`help(plotly.dashboard_objs)`.
1356+
1357+
Example 1: Upload Simple Dashboard
1358+
```
1359+
import plotly.plotly as py
1360+
import plotly.dashboard_objs as dashboard
1361+
box_1 = {
1362+
'type': 'box',
1363+
'boxType': 'plot',
1364+
'fileId': 'username:123',
1365+
'title': 'box 1'
1366+
}
1367+
1368+
box_2 = {
1369+
'type': 'box',
1370+
'boxType': 'plot',
1371+
'fileId': 'username:456',
1372+
'title': 'box 2'
1373+
}
1374+
1375+
my_dboard = dashboard.Dashboard()
1376+
my_dboard.insert(box_1)
1377+
# my_dboard.get_preview()
1378+
my_dboard.insert(box_2, 'above', 1)
1379+
# my_dboard.get_preview()
1380+
1381+
py.dashboard_ops.upload(my_dboard)
1382+
```
1383+
1384+
Example 2: Retreive Dashboard from Plotly
1385+
```
1386+
# works if you have at least one dashboard in your files
1387+
import plotly.plotly as py
1388+
import plotly.dashboard_objs as dashboard
1389+
1390+
dboard_names = get_dashboard_names()
1391+
first_dboard = get_dashboard(dboard_names[0])
1392+
1393+
first_dboard.get_preview()
1394+
```
13531395
"""
13541396
@classmethod
13551397
def upload(cls, dashboard, filename, sharing='public', auto_open=True):
@@ -1364,7 +1406,7 @@ def upload(cls, dashboard, filename, sharing='public', auto_open=True):
13641406
name if it already exists in your files.
13651407
:param (str) sharing: can be set to either 'public', 'private'
13661408
or 'secret'. If 'public', your dashboard will be viewable by
1367-
all other users. If 'secret', only you can see your dashboard.
1409+
all other users. If 'private' only you can see your dashboard.
13681410
If 'secret', the url will be returned with a sharekey appended
13691411
to the url. Anyone with the url may view the dashboard.
13701412
:param (bool) auto_open: automatically opens the dashboard in the
@@ -1385,27 +1427,36 @@ def upload(cls, dashboard, filename, sharing='public', auto_open=True):
13851427

13861428
# lookup if pre-existing filename already exists
13871429
try:
1388-
v2.files.lookup(filename)
1389-
matching_dashboard = cls._get_dashboard_json(
1390-
filename, False
1391-
)
1430+
lookup_res = v2.files.lookup(filename)
1431+
matching_file = json.loads(lookup_res.content)
13921432

1393-
if matching_dashboard['filetype'] == 'dashboard':
1394-
old_fid = matching_dashboard['fid']
1433+
if matching_file['filetype'] == 'dashboard':
1434+
old_fid = matching_file['fid']
13951435
res = v2.dashboards.update(old_fid, data)
1436+
else:
1437+
raise exceptions.PlotlyError(
1438+
"'{filename}' is already a {filetype} in your account. "
1439+
"While you can overwrite dashboards with the same name, "
1440+
"you can't change overwrite files with a different type. "
1441+
"Try deleting '{filename}' in your account or changing "
1442+
"the filename.".format(
1443+
filename=filename,
1444+
filetype=matching_file['filetype']
1445+
)
1446+
)
13961447

13971448
except exceptions.PlotlyRequestError:
13981449
res = v2.dashboards.create(data)
13991450
res.raise_for_status()
14001451

14011452
url = res.json()['web_url']
14021453

1403-
if auto_open:
1404-
webbrowser.open_new(res.json()['web_url'])
1405-
14061454
if sharing == 'secret':
14071455
url = add_share_key_to_url(url)
14081456

1457+
if auto_open:
1458+
webbrowser.open_new(res.json()['web_url'])
1459+
14091460
return url
14101461

14111462
@classmethod

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.