##// END OF EJS Templates
Drop jquery dependency in IPython.display.Javascript
Grant Nestor -
Show More
@@ -1,1421 +1,1427 b''
1 1 # -*- coding: utf-8 -*-
2 2 """Top-level display functions for displaying object in different formats."""
3 3
4 4 # Copyright (c) IPython Development Team.
5 5 # Distributed under the terms of the Modified BSD License.
6 6
7 7
8 8 from binascii import b2a_hex, b2a_base64, hexlify
9 9 import json
10 10 import mimetypes
11 11 import os
12 12 import struct
13 13 import sys
14 14 import warnings
15 15 from copy import deepcopy
16 16
17 17 from IPython.utils.py3compat import cast_unicode
18 18 from IPython.testing.skipdoctest import skip_doctest
19 19
20 20 __all__ = ['display', 'display_pretty', 'display_html', 'display_markdown',
21 21 'display_svg', 'display_png', 'display_jpeg', 'display_latex', 'display_json',
22 22 'display_javascript', 'display_pdf', 'DisplayObject', 'TextDisplayObject',
23 23 'Pretty', 'HTML', 'Markdown', 'Math', 'Latex', 'SVG', 'ProgressBar', 'JSON',
24 24 'GeoJSON', 'Javascript', 'Image', 'clear_output', 'set_matplotlib_formats',
25 25 'set_matplotlib_close', 'publish_display_data', 'update_display', 'DisplayHandle',
26 26 'Video']
27 27
28 28 #-----------------------------------------------------------------------------
29 29 # utility functions
30 30 #-----------------------------------------------------------------------------
31 31
32 32 def _safe_exists(path):
33 33 """Check path, but don't let exceptions raise"""
34 34 try:
35 35 return os.path.exists(path)
36 36 except Exception:
37 37 return False
38 38
39 39 def _merge(d1, d2):
40 40 """Like update, but merges sub-dicts instead of clobbering at the top level.
41 41
42 42 Updates d1 in-place
43 43 """
44 44
45 45 if not isinstance(d2, dict) or not isinstance(d1, dict):
46 46 return d2
47 47 for key, value in d2.items():
48 48 d1[key] = _merge(d1.get(key), value)
49 49 return d1
50 50
51 51 def _display_mimetype(mimetype, objs, raw=False, metadata=None):
52 52 """internal implementation of all display_foo methods
53 53
54 54 Parameters
55 55 ----------
56 56 mimetype : str
57 57 The mimetype to be published (e.g. 'image/png')
58 58 objs : tuple of objects
59 59 The Python objects to display, or if raw=True raw text data to
60 60 display.
61 61 raw : bool
62 62 Are the data objects raw data or Python objects that need to be
63 63 formatted before display? [default: False]
64 64 metadata : dict (optional)
65 65 Metadata to be associated with the specific mimetype output.
66 66 """
67 67 if metadata:
68 68 metadata = {mimetype: metadata}
69 69 if raw:
70 70 # turn list of pngdata into list of { 'image/png': pngdata }
71 71 objs = [ {mimetype: obj} for obj in objs ]
72 72 display(*objs, raw=raw, metadata=metadata, include=[mimetype])
73 73
74 74 #-----------------------------------------------------------------------------
75 75 # Main functions
76 76 #-----------------------------------------------------------------------------
77 77
78 78 # use * to indicate transient is keyword-only
79 79 def publish_display_data(data, metadata=None, source=None, *, transient=None, **kwargs):
80 80 """Publish data and metadata to all frontends.
81 81
82 82 See the ``display_data`` message in the messaging documentation for
83 83 more details about this message type.
84 84
85 85 Keys of data and metadata can be any mime-type.
86 86
87 87 Parameters
88 88 ----------
89 89 data : dict
90 90 A dictionary having keys that are valid MIME types (like
91 91 'text/plain' or 'image/svg+xml') and values that are the data for
92 92 that MIME type. The data itself must be a JSON'able data
93 93 structure. Minimally all data should have the 'text/plain' data,
94 94 which can be displayed by all frontends. If more than the plain
95 95 text is given, it is up to the frontend to decide which
96 96 representation to use.
97 97 metadata : dict
98 98 A dictionary for metadata related to the data. This can contain
99 99 arbitrary key, value pairs that frontends can use to interpret
100 100 the data. mime-type keys matching those in data can be used
101 101 to specify metadata about particular representations.
102 102 source : str, deprecated
103 103 Unused.
104 104 transient : dict, keyword-only
105 105 A dictionary of transient data, such as display_id.
106 106 """
107 107 from IPython.core.interactiveshell import InteractiveShell
108 108
109 109 display_pub = InteractiveShell.instance().display_pub
110 110
111 111 # only pass transient if supplied,
112 112 # to avoid errors with older ipykernel.
113 113 # TODO: We could check for ipykernel version and provide a detailed upgrade message.
114 114 if transient:
115 115 kwargs['transient'] = transient
116 116
117 117 display_pub.publish(
118 118 data=data,
119 119 metadata=metadata,
120 120 **kwargs
121 121 )
122 122
123 123
124 124 def _new_id():
125 125 """Generate a new random text id with urandom"""
126 126 return b2a_hex(os.urandom(16)).decode('ascii')
127 127
128 128
129 129 def display(*objs, include=None, exclude=None, metadata=None, transient=None, display_id=None, **kwargs):
130 130 """Display a Python object in all frontends.
131 131
132 132 By default all representations will be computed and sent to the frontends.
133 133 Frontends can decide which representation is used and how.
134 134
135 135 In terminal IPython this will be similar to using :func:`print`, for use in richer
136 136 frontends see Jupyter notebook examples with rich display logic.
137 137
138 138 Parameters
139 139 ----------
140 140 objs : tuple of objects
141 141 The Python objects to display.
142 142 raw : bool, optional
143 143 Are the objects to be displayed already mimetype-keyed dicts of raw display data,
144 144 or Python objects that need to be formatted before display? [default: False]
145 145 include : list, tuple or set, optional
146 146 A list of format type strings (MIME types) to include in the
147 147 format data dict. If this is set *only* the format types included
148 148 in this list will be computed.
149 149 exclude : list, tuple or set, optional
150 150 A list of format type strings (MIME types) to exclude in the format
151 151 data dict. If this is set all format types will be computed,
152 152 except for those included in this argument.
153 153 metadata : dict, optional
154 154 A dictionary of metadata to associate with the output.
155 155 mime-type keys in this dictionary will be associated with the individual
156 156 representation formats, if they exist.
157 157 transient : dict, optional
158 158 A dictionary of transient data to associate with the output.
159 159 Data in this dict should not be persisted to files (e.g. notebooks).
160 160 display_id : str, bool optional
161 161 Set an id for the display.
162 162 This id can be used for updating this display area later via update_display.
163 163 If given as `True`, generate a new `display_id`
164 164 kwargs: additional keyword-args, optional
165 165 Additional keyword-arguments are passed through to the display publisher.
166 166
167 167 Returns
168 168 -------
169 169
170 170 handle: DisplayHandle
171 171 Returns a handle on updatable displays for use with :func:`update_display`,
172 172 if `display_id` is given. Returns :any:`None` if no `display_id` is given
173 173 (default).
174 174
175 175 Examples
176 176 --------
177 177
178 178 >>> class Json(object):
179 179 ... def __init__(self, json):
180 180 ... self.json = json
181 181 ... def _repr_pretty_(self, pp, cycle):
182 182 ... import json
183 183 ... pp.text(json.dumps(self.json, indent=2))
184 184 ... def __repr__(self):
185 185 ... return str(self.json)
186 186 ...
187 187
188 188 >>> d = Json({1:2, 3: {4:5}})
189 189
190 190 >>> print(d)
191 191 {1: 2, 3: {4: 5}}
192 192
193 193 >>> display(d)
194 194 {
195 195 "1": 2,
196 196 "3": {
197 197 "4": 5
198 198 }
199 199 }
200 200
201 201 >>> def int_formatter(integer, pp, cycle):
202 202 ... pp.text('I'*integer)
203 203
204 204 >>> plain = get_ipython().display_formatter.formatters['text/plain']
205 205 >>> plain.for_type(int, int_formatter)
206 206 <function _repr_pprint at 0x...>
207 207 >>> display(7-5)
208 208 II
209 209
210 210 >>> del plain.type_printers[int]
211 211 >>> display(7-5)
212 212 2
213 213
214 214 See Also
215 215 --------
216 216
217 217 :func:`update_display`
218 218
219 219 Notes
220 220 -----
221 221
222 222 In Python, objects can declare their textual representation using the
223 223 `__repr__` method. IPython expands on this idea and allows objects to declare
224 224 other, rich representations including:
225 225
226 226 - HTML
227 227 - JSON
228 228 - PNG
229 229 - JPEG
230 230 - SVG
231 231 - LaTeX
232 232
233 233 A single object can declare some or all of these representations; all are
234 234 handled by IPython's display system.
235 235
236 236 The main idea of the first approach is that you have to implement special
237 237 display methods when you define your class, one for each representation you
238 238 want to use. Here is a list of the names of the special methods and the
239 239 values they must return:
240 240
241 241 - `_repr_html_`: return raw HTML as a string
242 242 - `_repr_json_`: return a JSONable dict
243 243 - `_repr_jpeg_`: return raw JPEG data
244 244 - `_repr_png_`: return raw PNG data
245 245 - `_repr_svg_`: return raw SVG data as a string
246 246 - `_repr_latex_`: return LaTeX commands in a string surrounded by "$".
247 247 - `_repr_mimebundle_`: return a full mimebundle containing the mapping
248 248 from all mimetypes to data.
249 249 Use this for any mime-type not listed above.
250 250
251 251 When you are directly writing your own classes, you can adapt them for
252 252 display in IPython by following the above approach. But in practice, you
253 253 often need to work with existing classes that you can't easily modify.
254 254
255 255 You can refer to the documentation on integrating with the display system in
256 256 order to register custom formatters for already existing types
257 257 (:ref:`integrating_rich_display`).
258 258
259 259 .. versionadded:: 5.4 display available without import
260 260 .. versionadded:: 6.1 display available without import
261 261
262 262 Since IPython 5.4 and 6.1 :func:`display` is automatically made available to
263 263 the user without import. If you are using display in a document that might
264 264 be used in a pure python context or with older version of IPython, use the
265 265 following import at the top of your file::
266 266
267 267 from IPython.display import display
268 268
269 269 """
270 270 from IPython.core.interactiveshell import InteractiveShell
271 271
272 272 if not InteractiveShell.initialized():
273 273 # Directly print objects.
274 274 print(*objs)
275 275 return
276 276
277 277 raw = kwargs.pop('raw', False)
278 278 if transient is None:
279 279 transient = {}
280 280 if metadata is None:
281 281 metadata={}
282 282 if display_id:
283 283 if display_id is True:
284 284 display_id = _new_id()
285 285 transient['display_id'] = display_id
286 286 if kwargs.get('update') and 'display_id' not in transient:
287 287 raise TypeError('display_id required for update_display')
288 288 if transient:
289 289 kwargs['transient'] = transient
290 290
291 291 if not raw:
292 292 format = InteractiveShell.instance().display_formatter.format
293 293
294 294 for obj in objs:
295 295 if raw:
296 296 publish_display_data(data=obj, metadata=metadata, **kwargs)
297 297 else:
298 298 format_dict, md_dict = format(obj, include=include, exclude=exclude)
299 299 if not format_dict:
300 300 # nothing to display (e.g. _ipython_display_ took over)
301 301 continue
302 302 if metadata:
303 303 # kwarg-specified metadata gets precedence
304 304 _merge(md_dict, metadata)
305 305 publish_display_data(data=format_dict, metadata=md_dict, **kwargs)
306 306 if display_id:
307 307 return DisplayHandle(display_id)
308 308
309 309
310 310 # use * for keyword-only display_id arg
311 311 def update_display(obj, *, display_id, **kwargs):
312 312 """Update an existing display by id
313 313
314 314 Parameters
315 315 ----------
316 316
317 317 obj:
318 318 The object with which to update the display
319 319 display_id: keyword-only
320 320 The id of the display to update
321 321
322 322 See Also
323 323 --------
324 324
325 325 :func:`display`
326 326 """
327 327 kwargs['update'] = True
328 328 display(obj, display_id=display_id, **kwargs)
329 329
330 330
331 331 class DisplayHandle(object):
332 332 """A handle on an updatable display
333 333
334 334 Call `.update(obj)` to display a new object.
335 335
336 336 Call `.display(obj`) to add a new instance of this display,
337 337 and update existing instances.
338 338
339 339 See Also
340 340 --------
341 341
342 342 :func:`display`, :func:`update_display`
343 343
344 344 """
345 345
346 346 def __init__(self, display_id=None):
347 347 if display_id is None:
348 348 display_id = _new_id()
349 349 self.display_id = display_id
350 350
351 351 def __repr__(self):
352 352 return "<%s display_id=%s>" % (self.__class__.__name__, self.display_id)
353 353
354 354 def display(self, obj, **kwargs):
355 355 """Make a new display with my id, updating existing instances.
356 356
357 357 Parameters
358 358 ----------
359 359
360 360 obj:
361 361 object to display
362 362 **kwargs:
363 363 additional keyword arguments passed to display
364 364 """
365 365 display(obj, display_id=self.display_id, **kwargs)
366 366
367 367 def update(self, obj, **kwargs):
368 368 """Update existing displays with my id
369 369
370 370 Parameters
371 371 ----------
372 372
373 373 obj:
374 374 object to display
375 375 **kwargs:
376 376 additional keyword arguments passed to update_display
377 377 """
378 378 update_display(obj, display_id=self.display_id, **kwargs)
379 379
380 380
381 381 def display_pretty(*objs, **kwargs):
382 382 """Display the pretty (default) representation of an object.
383 383
384 384 Parameters
385 385 ----------
386 386 objs : tuple of objects
387 387 The Python objects to display, or if raw=True raw text data to
388 388 display.
389 389 raw : bool
390 390 Are the data objects raw data or Python objects that need to be
391 391 formatted before display? [default: False]
392 392 metadata : dict (optional)
393 393 Metadata to be associated with the specific mimetype output.
394 394 """
395 395 _display_mimetype('text/plain', objs, **kwargs)
396 396
397 397
398 398 def display_html(*objs, **kwargs):
399 399 """Display the HTML representation of an object.
400 400
401 401 Note: If raw=False and the object does not have a HTML
402 402 representation, no HTML will be shown.
403 403
404 404 Parameters
405 405 ----------
406 406 objs : tuple of objects
407 407 The Python objects to display, or if raw=True raw HTML data to
408 408 display.
409 409 raw : bool
410 410 Are the data objects raw data or Python objects that need to be
411 411 formatted before display? [default: False]
412 412 metadata : dict (optional)
413 413 Metadata to be associated with the specific mimetype output.
414 414 """
415 415 _display_mimetype('text/html', objs, **kwargs)
416 416
417 417
418 418 def display_markdown(*objs, **kwargs):
419 419 """Displays the Markdown representation of an object.
420 420
421 421 Parameters
422 422 ----------
423 423 objs : tuple of objects
424 424 The Python objects to display, or if raw=True raw markdown data to
425 425 display.
426 426 raw : bool
427 427 Are the data objects raw data or Python objects that need to be
428 428 formatted before display? [default: False]
429 429 metadata : dict (optional)
430 430 Metadata to be associated with the specific mimetype output.
431 431 """
432 432
433 433 _display_mimetype('text/markdown', objs, **kwargs)
434 434
435 435
436 436 def display_svg(*objs, **kwargs):
437 437 """Display the SVG representation of an object.
438 438
439 439 Parameters
440 440 ----------
441 441 objs : tuple of objects
442 442 The Python objects to display, or if raw=True raw svg data to
443 443 display.
444 444 raw : bool
445 445 Are the data objects raw data or Python objects that need to be
446 446 formatted before display? [default: False]
447 447 metadata : dict (optional)
448 448 Metadata to be associated with the specific mimetype output.
449 449 """
450 450 _display_mimetype('image/svg+xml', objs, **kwargs)
451 451
452 452
453 453 def display_png(*objs, **kwargs):
454 454 """Display the PNG representation of an object.
455 455
456 456 Parameters
457 457 ----------
458 458 objs : tuple of objects
459 459 The Python objects to display, or if raw=True raw png data to
460 460 display.
461 461 raw : bool
462 462 Are the data objects raw data or Python objects that need to be
463 463 formatted before display? [default: False]
464 464 metadata : dict (optional)
465 465 Metadata to be associated with the specific mimetype output.
466 466 """
467 467 _display_mimetype('image/png', objs, **kwargs)
468 468
469 469
470 470 def display_jpeg(*objs, **kwargs):
471 471 """Display the JPEG representation of an object.
472 472
473 473 Parameters
474 474 ----------
475 475 objs : tuple of objects
476 476 The Python objects to display, or if raw=True raw JPEG data to
477 477 display.
478 478 raw : bool
479 479 Are the data objects raw data or Python objects that need to be
480 480 formatted before display? [default: False]
481 481 metadata : dict (optional)
482 482 Metadata to be associated with the specific mimetype output.
483 483 """
484 484 _display_mimetype('image/jpeg', objs, **kwargs)
485 485
486 486
487 487 def display_latex(*objs, **kwargs):
488 488 """Display the LaTeX representation of an object.
489 489
490 490 Parameters
491 491 ----------
492 492 objs : tuple of objects
493 493 The Python objects to display, or if raw=True raw latex data to
494 494 display.
495 495 raw : bool
496 496 Are the data objects raw data or Python objects that need to be
497 497 formatted before display? [default: False]
498 498 metadata : dict (optional)
499 499 Metadata to be associated with the specific mimetype output.
500 500 """
501 501 _display_mimetype('text/latex', objs, **kwargs)
502 502
503 503
504 504 def display_json(*objs, **kwargs):
505 505 """Display the JSON representation of an object.
506 506
507 507 Note that not many frontends support displaying JSON.
508 508
509 509 Parameters
510 510 ----------
511 511 objs : tuple of objects
512 512 The Python objects to display, or if raw=True raw json data to
513 513 display.
514 514 raw : bool
515 515 Are the data objects raw data or Python objects that need to be
516 516 formatted before display? [default: False]
517 517 metadata : dict (optional)
518 518 Metadata to be associated with the specific mimetype output.
519 519 """
520 520 _display_mimetype('application/json', objs, **kwargs)
521 521
522 522
523 523 def display_javascript(*objs, **kwargs):
524 524 """Display the Javascript representation of an object.
525 525
526 526 Parameters
527 527 ----------
528 528 objs : tuple of objects
529 529 The Python objects to display, or if raw=True raw javascript data to
530 530 display.
531 531 raw : bool
532 532 Are the data objects raw data or Python objects that need to be
533 533 formatted before display? [default: False]
534 534 metadata : dict (optional)
535 535 Metadata to be associated with the specific mimetype output.
536 536 """
537 537 _display_mimetype('application/javascript', objs, **kwargs)
538 538
539 539
540 540 def display_pdf(*objs, **kwargs):
541 541 """Display the PDF representation of an object.
542 542
543 543 Parameters
544 544 ----------
545 545 objs : tuple of objects
546 546 The Python objects to display, or if raw=True raw javascript data to
547 547 display.
548 548 raw : bool
549 549 Are the data objects raw data or Python objects that need to be
550 550 formatted before display? [default: False]
551 551 metadata : dict (optional)
552 552 Metadata to be associated with the specific mimetype output.
553 553 """
554 554 _display_mimetype('application/pdf', objs, **kwargs)
555 555
556 556
557 557 #-----------------------------------------------------------------------------
558 558 # Smart classes
559 559 #-----------------------------------------------------------------------------
560 560
561 561
562 562 class DisplayObject(object):
563 563 """An object that wraps data to be displayed."""
564 564
565 565 _read_flags = 'r'
566 566 _show_mem_addr = False
567 567 metadata = None
568 568
569 569 def __init__(self, data=None, url=None, filename=None, metadata=None):
570 570 """Create a display object given raw data.
571 571
572 572 When this object is returned by an expression or passed to the
573 573 display function, it will result in the data being displayed
574 574 in the frontend. The MIME type of the data should match the
575 575 subclasses used, so the Png subclass should be used for 'image/png'
576 576 data. If the data is a URL, the data will first be downloaded
577 577 and then displayed. If
578 578
579 579 Parameters
580 580 ----------
581 581 data : unicode, str or bytes
582 582 The raw data or a URL or file to load the data from
583 583 url : unicode
584 584 A URL to download the data from.
585 585 filename : unicode
586 586 Path to a local file to load the data from.
587 587 metadata : dict
588 588 Dict of metadata associated to be the object when displayed
589 589 """
590 590 if data is not None and isinstance(data, str):
591 591 if data.startswith('http') and url is None:
592 592 url = data
593 593 filename = None
594 594 data = None
595 595 elif _safe_exists(data) and filename is None:
596 596 url = None
597 597 filename = data
598 598 data = None
599 599
600 600 self.data = data
601 601 self.url = url
602 602 self.filename = filename
603 603
604 604 if metadata is not None:
605 605 self.metadata = metadata
606 606 elif self.metadata is None:
607 607 self.metadata = {}
608 608
609 609 self.reload()
610 610 self._check_data()
611 611
612 612 def __repr__(self):
613 613 if not self._show_mem_addr:
614 614 cls = self.__class__
615 615 r = "<%s.%s object>" % (cls.__module__, cls.__name__)
616 616 else:
617 617 r = super(DisplayObject, self).__repr__()
618 618 return r
619 619
620 620 def _check_data(self):
621 621 """Override in subclasses if there's something to check."""
622 622 pass
623 623
624 624 def _data_and_metadata(self):
625 625 """shortcut for returning metadata with shape information, if defined"""
626 626 if self.metadata:
627 627 return self.data, deepcopy(self.metadata)
628 628 else:
629 629 return self.data
630 630
631 631 def reload(self):
632 632 """Reload the raw data from file or URL."""
633 633 if self.filename is not None:
634 634 with open(self.filename, self._read_flags) as f:
635 635 self.data = f.read()
636 636 elif self.url is not None:
637 637 try:
638 638 # Deferred import
639 639 from urllib.request import urlopen
640 640 response = urlopen(self.url)
641 641 self.data = response.read()
642 642 # extract encoding from header, if there is one:
643 643 encoding = None
644 644 for sub in response.headers['content-type'].split(';'):
645 645 sub = sub.strip()
646 646 if sub.startswith('charset'):
647 647 encoding = sub.split('=')[-1].strip()
648 648 break
649 649 # decode data, if an encoding was specified
650 650 if encoding:
651 651 self.data = self.data.decode(encoding, 'replace')
652 652 except:
653 653 self.data = None
654 654
655 655 class TextDisplayObject(DisplayObject):
656 656 """Validate that display data is text"""
657 657 def _check_data(self):
658 658 if self.data is not None and not isinstance(self.data, str):
659 659 raise TypeError("%s expects text, not %r" % (self.__class__.__name__, self.data))
660 660
661 661 class Pretty(TextDisplayObject):
662 662
663 663 def _repr_pretty_(self, pp, cycle):
664 664 return pp.text(self.data)
665 665
666 666
667 667 class HTML(TextDisplayObject):
668 668
669 669 def _repr_html_(self):
670 670 return self._data_and_metadata()
671 671
672 672 def __html__(self):
673 673 """
674 674 This method exists to inform other HTML-using modules (e.g. Markupsafe,
675 675 htmltag, etc) that this object is HTML and does not need things like
676 676 special characters (<>&) escaped.
677 677 """
678 678 return self._repr_html_()
679 679
680 680
681 681 class Markdown(TextDisplayObject):
682 682
683 683 def _repr_markdown_(self):
684 684 return self._data_and_metadata()
685 685
686 686
687 687 class Math(TextDisplayObject):
688 688
689 689 def _repr_latex_(self):
690 690 s = "$$%s$$" % self.data.strip('$')
691 691 if self.metadata:
692 692 return s, deepcopy(self.metadata)
693 693 else:
694 694 return s
695 695
696 696
697 697 class Latex(TextDisplayObject):
698 698
699 699 def _repr_latex_(self):
700 700 return self._data_and_metadata()
701 701
702 702
703 703 class SVG(DisplayObject):
704 704
705 705 _read_flags = 'rb'
706 706 # wrap data in a property, which extracts the <svg> tag, discarding
707 707 # document headers
708 708 _data = None
709 709
710 710 @property
711 711 def data(self):
712 712 return self._data
713 713
714 714 @data.setter
715 715 def data(self, svg):
716 716 if svg is None:
717 717 self._data = None
718 718 return
719 719 # parse into dom object
720 720 from xml.dom import minidom
721 721 x = minidom.parseString(svg)
722 722 # get svg tag (should be 1)
723 723 found_svg = x.getElementsByTagName('svg')
724 724 if found_svg:
725 725 svg = found_svg[0].toxml()
726 726 else:
727 727 # fallback on the input, trust the user
728 728 # but this is probably an error.
729 729 pass
730 730 svg = cast_unicode(svg)
731 731 self._data = svg
732 732
733 733 def _repr_svg_(self):
734 734 return self._data_and_metadata()
735 735
736 736 class ProgressBar(DisplayObject):
737 737 """Progressbar supports displaying a progressbar like element
738 738 """
739 739 def __init__(self, total):
740 740 """Creates a new progressbar
741 741
742 742 Parameters
743 743 ----------
744 744 total : int
745 745 maximum size of the progressbar
746 746 """
747 747 self.total = total
748 748 self._progress = 0
749 749 self.html_width = '60ex'
750 750 self.text_width = 60
751 751 self._display_id = hexlify(os.urandom(8)).decode('ascii')
752 752
753 753 def __repr__(self):
754 754 fraction = self.progress / self.total
755 755 filled = '=' * int(fraction * self.text_width)
756 756 rest = ' ' * (self.text_width - len(filled))
757 757 return '[{}{}] {}/{}'.format(
758 758 filled, rest,
759 759 self.progress, self.total,
760 760 )
761 761
762 762 def _repr_html_(self):
763 763 return "<progress style='width:{}' max='{}' value='{}'></progress>".format(
764 764 self.html_width, self.total, self.progress)
765 765
766 766 def display(self):
767 767 display(self, display_id=self._display_id)
768 768
769 769 def update(self):
770 770 display(self, display_id=self._display_id, update=True)
771 771
772 772 @property
773 773 def progress(self):
774 774 return self._progress
775 775
776 776 @progress.setter
777 777 def progress(self, value):
778 778 self._progress = value
779 779 self.update()
780 780
781 781 def __iter__(self):
782 782 self.display()
783 783 self._progress = -1 # First iteration is 0
784 784 return self
785 785
786 786 def __next__(self):
787 787 """Returns current value and increments display by one."""
788 788 self.progress += 1
789 789 if self.progress < self.total:
790 790 return self.progress
791 791 else:
792 792 raise StopIteration()
793 793
794 794 class JSON(DisplayObject):
795 795 """JSON expects a JSON-able dict or list
796 796
797 797 not an already-serialized JSON string.
798 798
799 799 Scalar types (None, number, string) are not allowed, only dict or list containers.
800 800 """
801 801 # wrap data in a property, which warns about passing already-serialized JSON
802 802 _data = None
803 803 def __init__(self, data=None, url=None, filename=None, expanded=False, metadata=None, root='root', **kwargs):
804 804 """Create a JSON display object given raw data.
805 805
806 806 Parameters
807 807 ----------
808 808 data : dict or list
809 809 JSON data to display. Not an already-serialized JSON string.
810 810 Scalar types (None, number, string) are not allowed, only dict
811 811 or list containers.
812 812 url : unicode
813 813 A URL to download the data from.
814 814 filename : unicode
815 815 Path to a local file to load the data from.
816 816 expanded : boolean
817 817 Metadata to control whether a JSON display component is expanded.
818 818 metadata: dict
819 819 Specify extra metadata to attach to the json display object.
820 820 root : str
821 821 The name of the root element of the JSON tree
822 822 """
823 823 self.metadata = {
824 824 'expanded': expanded,
825 825 'root': root,
826 826 }
827 827 if metadata:
828 828 self.metadata.update(metadata)
829 829 if kwargs:
830 830 self.metadata.update(kwargs)
831 831 super(JSON, self).__init__(data=data, url=url, filename=filename)
832 832
833 833 def _check_data(self):
834 834 if self.data is not None and not isinstance(self.data, (dict, list)):
835 835 raise TypeError("%s expects JSONable dict or list, not %r" % (self.__class__.__name__, self.data))
836 836
837 837 @property
838 838 def data(self):
839 839 return self._data
840 840
841 841 @data.setter
842 842 def data(self, data):
843 843 if isinstance(data, str):
844 844 if getattr(self, 'filename', None) is None:
845 845 warnings.warn("JSON expects JSONable dict or list, not JSON strings")
846 846 data = json.loads(data)
847 847 self._data = data
848 848
849 849 def _data_and_metadata(self):
850 850 return self.data, self.metadata
851 851
852 852 def _repr_json_(self):
853 853 return self._data_and_metadata()
854 854
855 _css_t = """$("head").append($("<link/>").attr({
856 rel: "stylesheet",
857 type: "text/css",
858 href: "%s"
859 }));
855 _css_t = """var link = document.createElement("link");
856 link.ref = "stylesheet";
857 link.type = "text/css";
858 link.href = "%s";
859 document.head.appendChild(link);
860 860 """
861 861
862 _lib_t1 = """$.getScript("%s", function () {
863 """
864 _lib_t2 = """});
862 _lib_t1 = """var script = document.createElement("script");
863 script.type = "text/javascript";
864 script.src = "%s";
865 script.onload = script.onreadystatechange = function() {
866 if (!this.readyState || this.readyState == 'complete') {
865 867 """
866 868
869 _lib_t2 = """}
870 };
871 document.head.appendChild(script);"""
872
867 873 class GeoJSON(JSON):
868 874 """GeoJSON expects JSON-able dict
869 875
870 876 not an already-serialized JSON string.
871 877
872 878 Scalar types (None, number, string) are not allowed, only dict containers.
873 879 """
874 880
875 881 def __init__(self, *args, **kwargs):
876 882 """Create a GeoJSON display object given raw data.
877 883
878 884 Parameters
879 885 ----------
880 886 data : dict or list
881 887 VegaLite data. Not an already-serialized JSON string.
882 888 Scalar types (None, number, string) are not allowed, only dict
883 889 or list containers.
884 890 url_template : string
885 891 Leaflet TileLayer URL template: http://leafletjs.com/reference.html#url-template
886 892 layer_options : dict
887 893 Leaflet TileLayer options: http://leafletjs.com/reference.html#tilelayer-options
888 894 url : unicode
889 895 A URL to download the data from.
890 896 filename : unicode
891 897 Path to a local file to load the data from.
892 898 metadata: dict
893 899 Specify extra metadata to attach to the json display object.
894 900
895 901 Examples
896 902 --------
897 903
898 904 The following will display an interactive map of Mars with a point of
899 905 interest on frontend that do support GeoJSON display.
900 906
901 907 >>> from IPython.display import GeoJSON
902 908
903 909 >>> GeoJSON(data={
904 910 ... "type": "Feature",
905 911 ... "geometry": {
906 912 ... "type": "Point",
907 913 ... "coordinates": [-81.327, 296.038]
908 914 ... }
909 915 ... },
910 916 ... url_template="http://s3-eu-west-1.amazonaws.com/whereonmars.cartodb.net/{basemap_id}/{z}/{x}/{y}.png",
911 917 ... layer_options={
912 918 ... "basemap_id": "celestia_mars-shaded-16k_global",
913 919 ... "attribution" : "Celestia/praesepe",
914 920 ... "minZoom" : 0,
915 921 ... "maxZoom" : 18,
916 922 ... })
917 923 <IPython.core.display.GeoJSON object>
918 924
919 925 In the terminal IPython, you will only see the text representation of
920 926 the GeoJSON object.
921 927
922 928 """
923 929
924 930 super(GeoJSON, self).__init__(*args, **kwargs)
925 931
926 932
927 933 def _ipython_display_(self):
928 934 bundle = {
929 935 'application/geo+json': self.data,
930 936 'text/plain': '<IPython.display.GeoJSON object>'
931 937 }
932 938 metadata = {
933 939 'application/geo+json': self.metadata
934 940 }
935 941 display(bundle, metadata=metadata, raw=True)
936 942
937 943 class Javascript(TextDisplayObject):
938 944
939 945 def __init__(self, data=None, url=None, filename=None, lib=None, css=None):
940 946 """Create a Javascript display object given raw data.
941 947
942 948 When this object is returned by an expression or passed to the
943 949 display function, it will result in the data being displayed
944 950 in the frontend. If the data is a URL, the data will first be
945 951 downloaded and then displayed.
946 952
947 953 In the Notebook, the containing element will be available as `element`,
948 954 and jQuery will be available. Content appended to `element` will be
949 955 visible in the output area.
950 956
951 957 Parameters
952 958 ----------
953 959 data : unicode, str or bytes
954 960 The Javascript source code or a URL to download it from.
955 961 url : unicode
956 962 A URL to download the data from.
957 963 filename : unicode
958 964 Path to a local file to load the data from.
959 965 lib : list or str
960 966 A sequence of Javascript library URLs to load asynchronously before
961 967 running the source code. The full URLs of the libraries should
962 968 be given. A single Javascript library URL can also be given as a
963 969 string.
964 970 css: : list or str
965 971 A sequence of css files to load before running the source code.
966 972 The full URLs of the css files should be given. A single css URL
967 973 can also be given as a string.
968 974 """
969 975 if isinstance(lib, str):
970 976 lib = [lib]
971 977 elif lib is None:
972 978 lib = []
973 979 if isinstance(css, str):
974 980 css = [css]
975 981 elif css is None:
976 982 css = []
977 983 if not isinstance(lib, (list,tuple)):
978 984 raise TypeError('expected sequence, got: %r' % lib)
979 985 if not isinstance(css, (list,tuple)):
980 986 raise TypeError('expected sequence, got: %r' % css)
981 987 self.lib = lib
982 988 self.css = css
983 989 super(Javascript, self).__init__(data=data, url=url, filename=filename)
984 990
985 991 def _repr_javascript_(self):
986 992 r = ''
987 993 for c in self.css:
988 994 r += _css_t % c
989 995 for l in self.lib:
990 996 r += _lib_t1 % l
991 997 r += self.data
992 998 r += _lib_t2*len(self.lib)
993 999 return r
994 1000
995 1001 # constants for identifying png/jpeg data
996 1002 _PNG = b'\x89PNG\r\n\x1a\n'
997 1003 _JPEG = b'\xff\xd8'
998 1004
999 1005 def _pngxy(data):
1000 1006 """read the (width, height) from a PNG header"""
1001 1007 ihdr = data.index(b'IHDR')
1002 1008 # next 8 bytes are width/height
1003 1009 return struct.unpack('>ii', data[ihdr+4:ihdr+12])
1004 1010
1005 1011 def _jpegxy(data):
1006 1012 """read the (width, height) from a JPEG header"""
1007 1013 # adapted from http://www.64lines.com/jpeg-width-height
1008 1014
1009 1015 idx = 4
1010 1016 while True:
1011 1017 block_size = struct.unpack('>H', data[idx:idx+2])[0]
1012 1018 idx = idx + block_size
1013 1019 if data[idx:idx+2] == b'\xFF\xC0':
1014 1020 # found Start of Frame
1015 1021 iSOF = idx
1016 1022 break
1017 1023 else:
1018 1024 # read another block
1019 1025 idx += 2
1020 1026
1021 1027 h, w = struct.unpack('>HH', data[iSOF+5:iSOF+9])
1022 1028 return w, h
1023 1029
1024 1030 def _gifxy(data):
1025 1031 """read the (width, height) from a GIF header"""
1026 1032 return struct.unpack('<HH', data[6:10])
1027 1033
1028 1034
1029 1035 class Image(DisplayObject):
1030 1036
1031 1037 _read_flags = 'rb'
1032 1038 _FMT_JPEG = u'jpeg'
1033 1039 _FMT_PNG = u'png'
1034 1040 _FMT_GIF = u'gif'
1035 1041 _ACCEPTABLE_EMBEDDINGS = [_FMT_JPEG, _FMT_PNG, _FMT_GIF]
1036 1042 _MIMETYPES = {
1037 1043 _FMT_PNG: 'image/png',
1038 1044 _FMT_JPEG: 'image/jpeg',
1039 1045 _FMT_GIF: 'image/gif',
1040 1046 }
1041 1047
1042 1048 def __init__(self, data=None, url=None, filename=None, format=None,
1043 1049 embed=None, width=None, height=None, retina=False,
1044 1050 unconfined=False, metadata=None):
1045 1051 """Create a PNG/JPEG/GIF image object given raw data.
1046 1052
1047 1053 When this object is returned by an input cell or passed to the
1048 1054 display function, it will result in the image being displayed
1049 1055 in the frontend.
1050 1056
1051 1057 Parameters
1052 1058 ----------
1053 1059 data : unicode, str or bytes
1054 1060 The raw image data or a URL or filename to load the data from.
1055 1061 This always results in embedded image data.
1056 1062 url : unicode
1057 1063 A URL to download the data from. If you specify `url=`,
1058 1064 the image data will not be embedded unless you also specify `embed=True`.
1059 1065 filename : unicode
1060 1066 Path to a local file to load the data from.
1061 1067 Images from a file are always embedded.
1062 1068 format : unicode
1063 1069 The format of the image data (png/jpeg/jpg/gif). If a filename or URL is given
1064 1070 for format will be inferred from the filename extension.
1065 1071 embed : bool
1066 1072 Should the image data be embedded using a data URI (True) or be
1067 1073 loaded using an <img> tag. Set this to True if you want the image
1068 1074 to be viewable later with no internet connection in the notebook.
1069 1075
1070 1076 Default is `True`, unless the keyword argument `url` is set, then
1071 1077 default value is `False`.
1072 1078
1073 1079 Note that QtConsole is not able to display images if `embed` is set to `False`
1074 1080 width : int
1075 1081 Width in pixels to which to constrain the image in html
1076 1082 height : int
1077 1083 Height in pixels to which to constrain the image in html
1078 1084 retina : bool
1079 1085 Automatically set the width and height to half of the measured
1080 1086 width and height.
1081 1087 This only works for embedded images because it reads the width/height
1082 1088 from image data.
1083 1089 For non-embedded images, you can just set the desired display width
1084 1090 and height directly.
1085 1091 unconfined: bool
1086 1092 Set unconfined=True to disable max-width confinement of the image.
1087 1093 metadata: dict
1088 1094 Specify extra metadata to attach to the image.
1089 1095
1090 1096 Examples
1091 1097 --------
1092 1098 # embedded image data, works in qtconsole and notebook
1093 1099 # when passed positionally, the first arg can be any of raw image data,
1094 1100 # a URL, or a filename from which to load image data.
1095 1101 # The result is always embedding image data for inline images.
1096 1102 Image('http://www.google.fr/images/srpr/logo3w.png')
1097 1103 Image('/path/to/image.jpg')
1098 1104 Image(b'RAW_PNG_DATA...')
1099 1105
1100 1106 # Specifying Image(url=...) does not embed the image data,
1101 1107 # it only generates `<img>` tag with a link to the source.
1102 1108 # This will not work in the qtconsole or offline.
1103 1109 Image(url='http://www.google.fr/images/srpr/logo3w.png')
1104 1110
1105 1111 """
1106 1112 if filename is not None:
1107 1113 ext = self._find_ext(filename)
1108 1114 elif url is not None:
1109 1115 ext = self._find_ext(url)
1110 1116 elif data is None:
1111 1117 raise ValueError("No image data found. Expecting filename, url, or data.")
1112 1118 elif isinstance(data, str) and (
1113 1119 data.startswith('http') or _safe_exists(data)
1114 1120 ):
1115 1121 ext = self._find_ext(data)
1116 1122 else:
1117 1123 ext = None
1118 1124
1119 1125 if format is None:
1120 1126 if ext is not None:
1121 1127 if ext == u'jpg' or ext == u'jpeg':
1122 1128 format = self._FMT_JPEG
1123 1129 elif ext == u'png':
1124 1130 format = self._FMT_PNG
1125 1131 elif ext == u'gif':
1126 1132 format = self._FMT_GIF
1127 1133 else:
1128 1134 format = ext.lower()
1129 1135 elif isinstance(data, bytes):
1130 1136 # infer image type from image data header,
1131 1137 # only if format has not been specified.
1132 1138 if data[:2] == _JPEG:
1133 1139 format = self._FMT_JPEG
1134 1140
1135 1141 # failed to detect format, default png
1136 1142 if format is None:
1137 1143 format = self._FMT_PNG
1138 1144
1139 1145 if format.lower() == 'jpg':
1140 1146 # jpg->jpeg
1141 1147 format = self._FMT_JPEG
1142 1148
1143 1149 self.format = format.lower()
1144 1150 self.embed = embed if embed is not None else (url is None)
1145 1151
1146 1152 if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
1147 1153 raise ValueError("Cannot embed the '%s' image format" % (self.format))
1148 1154 if self.embed:
1149 1155 self._mimetype = self._MIMETYPES.get(self.format)
1150 1156
1151 1157 self.width = width
1152 1158 self.height = height
1153 1159 self.retina = retina
1154 1160 self.unconfined = unconfined
1155 1161 super(Image, self).__init__(data=data, url=url, filename=filename,
1156 1162 metadata=metadata)
1157 1163
1158 1164 if self.width is None and self.metadata.get('width', {}):
1159 1165 self.width = metadata['width']
1160 1166
1161 1167 if self.height is None and self.metadata.get('height', {}):
1162 1168 self.height = metadata['height']
1163 1169
1164 1170 if retina:
1165 1171 self._retina_shape()
1166 1172
1167 1173
1168 1174 def _retina_shape(self):
1169 1175 """load pixel-doubled width and height from image data"""
1170 1176 if not self.embed:
1171 1177 return
1172 1178 if self.format == self._FMT_PNG:
1173 1179 w, h = _pngxy(self.data)
1174 1180 elif self.format == self._FMT_JPEG:
1175 1181 w, h = _jpegxy(self.data)
1176 1182 elif self.format == self._FMT_GIF:
1177 1183 w, h = _gifxy(self.data)
1178 1184 else:
1179 1185 # retina only supports png
1180 1186 return
1181 1187 self.width = w // 2
1182 1188 self.height = h // 2
1183 1189
1184 1190 def reload(self):
1185 1191 """Reload the raw data from file or URL."""
1186 1192 if self.embed:
1187 1193 super(Image,self).reload()
1188 1194 if self.retina:
1189 1195 self._retina_shape()
1190 1196
1191 1197 def _repr_html_(self):
1192 1198 if not self.embed:
1193 1199 width = height = klass = ''
1194 1200 if self.width:
1195 1201 width = ' width="%d"' % self.width
1196 1202 if self.height:
1197 1203 height = ' height="%d"' % self.height
1198 1204 if self.unconfined:
1199 1205 klass = ' class="unconfined"'
1200 1206 return u'<img src="{url}"{width}{height}{klass}/>'.format(
1201 1207 url=self.url,
1202 1208 width=width,
1203 1209 height=height,
1204 1210 klass=klass,
1205 1211 )
1206 1212
1207 1213 def _repr_mimebundle_(self, include=None, exclude=None):
1208 1214 """Return the image as a mimebundle
1209 1215
1210 1216 Any new mimetype support should be implemented here.
1211 1217 """
1212 1218 if self.embed:
1213 1219 mimetype = self._mimetype
1214 1220 data, metadata = self._data_and_metadata(always_both=True)
1215 1221 if metadata:
1216 1222 metadata = {mimetype: metadata}
1217 1223 return {mimetype: data}, metadata
1218 1224 else:
1219 1225 return {'text/html': self._repr_html_()}
1220 1226
1221 1227 def _data_and_metadata(self, always_both=False):
1222 1228 """shortcut for returning metadata with shape information, if defined"""
1223 1229 b64_data = b2a_base64(self.data).decode('ascii')
1224 1230 md = {}
1225 1231 if self.metadata:
1226 1232 md.update(self.metadata)
1227 1233 if self.width:
1228 1234 md['width'] = self.width
1229 1235 if self.height:
1230 1236 md['height'] = self.height
1231 1237 if self.unconfined:
1232 1238 md['unconfined'] = self.unconfined
1233 1239 if md or always_both:
1234 1240 return b64_data, md
1235 1241 else:
1236 1242 return b64_data
1237 1243
1238 1244 def _repr_png_(self):
1239 1245 if self.embed and self.format == self._FMT_PNG:
1240 1246 return self._data_and_metadata()
1241 1247
1242 1248 def _repr_jpeg_(self):
1243 1249 if self.embed and self.format == self._FMT_JPEG:
1244 1250 return self._data_and_metadata()
1245 1251
1246 1252 def _find_ext(self, s):
1247 1253 return s.split('.')[-1].lower()
1248 1254
1249 1255
1250 1256 class Video(DisplayObject):
1251 1257
1252 1258 def __init__(self, data=None, url=None, filename=None, embed=False, mimetype=None):
1253 1259 """Create a video object given raw data or an URL.
1254 1260
1255 1261 When this object is returned by an input cell or passed to the
1256 1262 display function, it will result in the video being displayed
1257 1263 in the frontend.
1258 1264
1259 1265 Parameters
1260 1266 ----------
1261 1267 data : unicode, str or bytes
1262 1268 The raw video data or a URL or filename to load the data from.
1263 1269 Raw data will require passing `embed=True`.
1264 1270 url : unicode
1265 1271 A URL for the video. If you specify `url=`,
1266 1272 the image data will not be embedded.
1267 1273 filename : unicode
1268 1274 Path to a local file containing the video.
1269 1275 Will be interpreted as a local URL unless `embed=True`.
1270 1276 embed : bool
1271 1277 Should the video be embedded using a data URI (True) or be
1272 1278 loaded using a <video> tag (False).
1273 1279
1274 1280 Since videos are large, embedding them should be avoided, if possible.
1275 1281 You must confirm embedding as your intention by passing `embed=True`.
1276 1282
1277 1283 Local files can be displayed with URLs without embedding the content, via::
1278 1284
1279 1285 Video('./video.mp4')
1280 1286
1281 1287 mimetype: unicode
1282 1288 Specify the mimetype for embedded videos.
1283 1289 Default will be guessed from file extension, if available.
1284 1290
1285 1291 Examples
1286 1292 --------
1287 1293
1288 1294 Video('https://archive.org/download/Sita_Sings_the_Blues/Sita_Sings_the_Blues_small.mp4')
1289 1295 Video('path/to/video.mp4')
1290 1296 Video('path/to/video.mp4', embed=True)
1291 1297 Video(b'raw-videodata', embed=True)
1292 1298 """
1293 1299 if url is None and isinstance(data, str) and data.startswith(('http:', 'https:')):
1294 1300 url = data
1295 1301 data = None
1296 1302 elif os.path.exists(data):
1297 1303 filename = data
1298 1304 data = None
1299 1305
1300 1306 if data and not embed:
1301 1307 msg = ''.join([
1302 1308 "To embed videos, you must pass embed=True ",
1303 1309 "(this may make your notebook files huge)\n",
1304 1310 "Consider passing Video(url='...')",
1305 1311 ])
1306 1312 raise ValueError(msg)
1307 1313
1308 1314 self.mimetype = mimetype
1309 1315 self.embed = embed
1310 1316 super(Video, self).__init__(data=data, url=url, filename=filename)
1311 1317
1312 1318 def _repr_html_(self):
1313 1319 # External URLs and potentially local files are not embedded into the
1314 1320 # notebook output.
1315 1321 if not self.embed:
1316 1322 url = self.url if self.url is not None else self.filename
1317 1323 output = """<video src="{0}" controls>
1318 1324 Your browser does not support the <code>video</code> element.
1319 1325 </video>""".format(url)
1320 1326 return output
1321 1327
1322 1328 # Embedded videos are base64-encoded.
1323 1329 mimetype = self.mimetype
1324 1330 if self.filename is not None:
1325 1331 if not mimetype:
1326 1332 mimetype, _ = mimetypes.guess_type(self.filename)
1327 1333
1328 1334 with open(self.filename, 'rb') as f:
1329 1335 video = f.read()
1330 1336 else:
1331 1337 video = self.data
1332 1338 if isinstance(video, str):
1333 1339 # unicode input is already b64-encoded
1334 1340 b64_video = video
1335 1341 else:
1336 1342 b64_video = b2a_base64(video).decode('ascii').rstrip()
1337 1343
1338 1344 output = """<video controls>
1339 1345 <source src="data:{0};base64,{1}" type="{0}">
1340 1346 Your browser does not support the video tag.
1341 1347 </video>""".format(mimetype, b64_video)
1342 1348 return output
1343 1349
1344 1350 def reload(self):
1345 1351 # TODO
1346 1352 pass
1347 1353
1348 1354
1349 1355 def clear_output(wait=False):
1350 1356 """Clear the output of the current cell receiving output.
1351 1357
1352 1358 Parameters
1353 1359 ----------
1354 1360 wait : bool [default: false]
1355 1361 Wait to clear the output until new output is available to replace it."""
1356 1362 from IPython.core.interactiveshell import InteractiveShell
1357 1363 if InteractiveShell.initialized():
1358 1364 InteractiveShell.instance().display_pub.clear_output(wait)
1359 1365 else:
1360 1366 print('\033[2K\r', end='')
1361 1367 sys.stdout.flush()
1362 1368 print('\033[2K\r', end='')
1363 1369 sys.stderr.flush()
1364 1370
1365 1371
1366 1372 @skip_doctest
1367 1373 def set_matplotlib_formats(*formats, **kwargs):
1368 1374 """Select figure formats for the inline backend. Optionally pass quality for JPEG.
1369 1375
1370 1376 For example, this enables PNG and JPEG output with a JPEG quality of 90%::
1371 1377
1372 1378 In [1]: set_matplotlib_formats('png', 'jpeg', quality=90)
1373 1379
1374 1380 To set this in your config files use the following::
1375 1381
1376 1382 c.InlineBackend.figure_formats = {'png', 'jpeg'}
1377 1383 c.InlineBackend.print_figure_kwargs.update({'quality' : 90})
1378 1384
1379 1385 Parameters
1380 1386 ----------
1381 1387 *formats : strs
1382 1388 One or more figure formats to enable: 'png', 'retina', 'jpeg', 'svg', 'pdf'.
1383 1389 **kwargs :
1384 1390 Keyword args will be relayed to ``figure.canvas.print_figure``.
1385 1391 """
1386 1392 from IPython.core.interactiveshell import InteractiveShell
1387 1393 from IPython.core.pylabtools import select_figure_formats
1388 1394 # build kwargs, starting with InlineBackend config
1389 1395 kw = {}
1390 1396 from ipykernel.pylab.config import InlineBackend
1391 1397 cfg = InlineBackend.instance()
1392 1398 kw.update(cfg.print_figure_kwargs)
1393 1399 kw.update(**kwargs)
1394 1400 shell = InteractiveShell.instance()
1395 1401 select_figure_formats(shell, formats, **kw)
1396 1402
1397 1403 @skip_doctest
1398 1404 def set_matplotlib_close(close=True):
1399 1405 """Set whether the inline backend closes all figures automatically or not.
1400 1406
1401 1407 By default, the inline backend used in the IPython Notebook will close all
1402 1408 matplotlib figures automatically after each cell is run. This means that
1403 1409 plots in different cells won't interfere. Sometimes, you may want to make
1404 1410 a plot in one cell and then refine it in later cells. This can be accomplished
1405 1411 by::
1406 1412
1407 1413 In [1]: set_matplotlib_close(False)
1408 1414
1409 1415 To set this in your config files use the following::
1410 1416
1411 1417 c.InlineBackend.close_figures = False
1412 1418
1413 1419 Parameters
1414 1420 ----------
1415 1421 close : bool
1416 1422 Should all matplotlib figures be automatically closed after each cell is
1417 1423 run?
1418 1424 """
1419 1425 from ipykernel.pylab.config import InlineBackend
1420 1426 cfg = InlineBackend.instance()
1421 1427 cfg.close_figures = close
General Comments 0
You need to be logged in to leave comments. Login now