Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# -*- coding: utf-8 -*-
2"""Display formatters.
4This module defines the base instances in order to implement custom
5formatters/mimetypes
6got objects:
8As we want to see internal IPython working we are going to use the following
9function to diaply objects instead of the normal print or display method:
11 >>> ip = get_ipython()
12 >>> ip.display_formatter.format(...)
13 ({'text/plain': 'Ellipsis'}, {})
15This return a tuple with the mimebumdle for the current object, and the
16associated metadata.
19We can now define our own formatter and register it:
22 >>> from IPython.core.formatters import BaseFormatter, FormatterABC
25 >>> class LLMFormatter(BaseFormatter):
26 ...
27 ... format_type = 'x-vendor/llm'
28 ... print_method = '_repr_llm_'
29 ... _return_type = (dict, str)
31 >>> llm_formatter = LLMFormatter(parent=ip.display_formatter)
33 >>> ip.display_formatter.formatters[LLMFormatter.format_type] = llm_formatter
35Now any class that define `_repr_llm_` will return a x-vendor/llm as part of
36it's display data:
38 >>> class A:
39 ...
40 ... def _repr_llm_(self, *kwargs):
41 ... return 'This a A'
42 ...
44 >>> ip.display_formatter.format(A())
45 ({'text/plain': '<IPython.core.formatters.A at ...>', 'x-vendor/llm': 'This a A'}, {})
47As usual, you can register methods for third party types (see
48:ref:`third_party_formatting`)
50 >>> def llm_int(obj):
51 ... return 'This is the integer %s, in between %s and %s'%(obj, obj-1, obj+1)
53 >>> llm_formatter.for_type(int, llm_int)
55 >>> ip.display_formatter.format(42)
56 ({'text/plain': '42', 'x-vendor/llm': 'This is the integer 42, in between 41 and 43'}, {})
59Inheritance diagram:
61.. inheritance-diagram:: IPython.core.formatters
62 :parts: 3
63"""
65# Copyright (c) IPython Development Team.
66# Distributed under the terms of the Modified BSD License.
68import abc
69import sys
70import traceback
71import warnings
72from io import StringIO
74from decorator import decorator
76from traitlets.config.configurable import Configurable
77from .getipython import get_ipython
78from ..utils.sentinel import Sentinel
79from ..utils.dir2 import get_real_method
80from ..lib import pretty
81from traitlets import (
82 Bool, Dict, Integer, Unicode, CUnicode, ObjectName, List,
83 ForwardDeclaredInstance,
84 default, observe,
85)
87from typing import Any
90class DisplayFormatter(Configurable):
92 active_types = List(Unicode(),
93 help="""List of currently active mime-types to display.
94 You can use this to set a white-list for formats to display.
96 Most users will not need to change this value.
97 """,
98 ).tag(config=True)
100 @default('active_types')
101 def _active_types_default(self):
102 return self.format_types
104 @observe('active_types')
105 def _active_types_changed(self, change):
106 for key, formatter in self.formatters.items():
107 if key in change['new']:
108 formatter.enabled = True
109 else:
110 formatter.enabled = False
112 ipython_display_formatter = ForwardDeclaredInstance("FormatterABC") # type: ignore
114 @default("ipython_display_formatter")
115 def _default_formatter(self):
116 return IPythonDisplayFormatter(parent=self)
118 mimebundle_formatter = ForwardDeclaredInstance("FormatterABC") # type: ignore
120 @default("mimebundle_formatter")
121 def _default_mime_formatter(self):
122 return MimeBundleFormatter(parent=self)
124 # A dict of formatter whose keys are format types (MIME types) and whose
125 # values are subclasses of BaseFormatter.
126 formatters = Dict()
128 @default("formatters")
129 def _formatters_default(self):
130 """Activate the default formatters."""
131 formatter_classes = [
132 PlainTextFormatter,
133 HTMLFormatter,
134 MarkdownFormatter,
135 SVGFormatter,
136 PNGFormatter,
137 PDFFormatter,
138 JPEGFormatter,
139 LatexFormatter,
140 JSONFormatter,
141 JavascriptFormatter
142 ]
143 d = {}
144 for cls in formatter_classes:
145 f = cls(parent=self)
146 d[f.format_type] = f
147 return d
149 def format(self, obj, include=None, exclude=None):
150 """Return a format data dict for an object.
152 By default all format types will be computed.
154 The following MIME types are usually implemented:
156 * text/plain
157 * text/html
158 * text/markdown
159 * text/latex
160 * application/json
161 * application/javascript
162 * application/pdf
163 * image/png
164 * image/jpeg
165 * image/svg+xml
167 Parameters
168 ----------
169 obj : object
170 The Python object whose format data will be computed.
171 include : list, tuple or set; optional
172 A list of format type strings (MIME types) to include in the
173 format data dict. If this is set *only* the format types included
174 in this list will be computed.
175 exclude : list, tuple or set; optional
176 A list of format type string (MIME types) to exclude in the format
177 data dict. If this is set all format types will be computed,
178 except for those included in this argument.
179 Mimetypes present in exclude will take precedence over the ones in include
181 Returns
182 -------
183 (format_dict, metadata_dict) : tuple of two dicts
184 format_dict is a dictionary of key/value pairs, one of each format that was
185 generated for the object. The keys are the format types, which
186 will usually be MIME type strings and the values and JSON'able
187 data structure containing the raw data for the representation in
188 that format.
190 metadata_dict is a dictionary of metadata about each mime-type output.
191 Its keys will be a strict subset of the keys in format_dict.
193 Notes
194 -----
195 If an object implement `_repr_mimebundle_` as well as various
196 `_repr_*_`, the data returned by `_repr_mimebundle_` will take
197 precedence and the corresponding `_repr_*_` for this mimetype will
198 not be called.
200 """
201 format_dict = {}
202 md_dict = {}
204 if self.ipython_display_formatter(obj):
205 # object handled itself, don't proceed
206 return {}, {}
208 format_dict, md_dict = self.mimebundle_formatter(obj, include=include, exclude=exclude)
210 if format_dict or md_dict:
211 if include:
212 format_dict = {k:v for k,v in format_dict.items() if k in include}
213 md_dict = {k:v for k,v in md_dict.items() if k in include}
214 if exclude:
215 format_dict = {k:v for k,v in format_dict.items() if k not in exclude}
216 md_dict = {k:v for k,v in md_dict.items() if k not in exclude}
218 for format_type, formatter in self.formatters.items():
219 if format_type in format_dict:
220 # already got it from mimebundle, maybe don't render again.
221 # exception: manually registered per-mime renderer
222 # check priority:
223 # 1. user-registered per-mime formatter
224 # 2. mime-bundle (user-registered or repr method)
225 # 3. default per-mime formatter (e.g. repr method)
226 try:
227 formatter.lookup(obj)
228 except KeyError:
229 # no special formatter, use mime-bundle-provided value
230 continue
231 if include and format_type not in include:
232 continue
233 if exclude and format_type in exclude:
234 continue
236 md = None
237 try:
238 data = formatter(obj)
239 except:
240 # FIXME: log the exception
241 raise
243 # formatters can return raw data or (data, metadata)
244 if isinstance(data, tuple) and len(data) == 2:
245 data, md = data
247 if data is not None:
248 format_dict[format_type] = data
249 if md is not None:
250 md_dict[format_type] = md
251 return format_dict, md_dict
253 @property
254 def format_types(self):
255 """Return the format types (MIME types) of the active formatters."""
256 return list(self.formatters.keys())
259#-----------------------------------------------------------------------------
260# Formatters for specific format types (text, html, svg, etc.)
261#-----------------------------------------------------------------------------
264def _safe_repr(obj):
265 """Try to return a repr of an object
267 always returns a string, at least.
268 """
269 try:
270 return repr(obj)
271 except Exception as e:
272 return "un-repr-able object (%r)" % e
275class FormatterWarning(UserWarning):
276 """Warning class for errors in formatters"""
278@decorator
279def catch_format_error(method, self, *args, **kwargs):
280 """show traceback on failed format call"""
281 try:
282 r = method(self, *args, **kwargs)
283 except NotImplementedError:
284 # don't warn on NotImplementedErrors
285 return self._check_return(None, args[0])
286 except Exception:
287 exc_info = sys.exc_info()
288 ip = get_ipython()
289 if ip is not None:
290 ip.showtraceback(exc_info)
291 else:
292 traceback.print_exception(*exc_info)
293 return self._check_return(None, args[0])
294 return self._check_return(r, args[0])
297class FormatterABC(metaclass=abc.ABCMeta):
298 """ Abstract base class for Formatters.
300 A formatter is a callable class that is responsible for computing the
301 raw format data for a particular format type (MIME type). For example,
302 an HTML formatter would have a format type of `text/html` and would return
303 the HTML representation of the object when called.
304 """
306 # The format type of the data returned, usually a MIME type.
307 format_type = 'text/plain'
309 # Is the formatter enabled...
310 enabled = True
312 @abc.abstractmethod
313 def __call__(self, obj):
314 """Return a JSON'able representation of the object.
316 If the object cannot be formatted by this formatter,
317 warn and return None.
318 """
319 return repr(obj)
322def _mod_name_key(typ):
323 """Return a (__module__, __name__) tuple for a type.
325 Used as key in Formatter.deferred_printers.
326 """
327 module = getattr(typ, '__module__', None)
328 name = getattr(typ, '__name__', None)
329 return (module, name)
332def _get_type(obj):
333 """Return the type of an instance (old and new-style)"""
334 return getattr(obj, '__class__', None) or type(obj)
337_raise_key_error = Sentinel(
338 "_raise_key_error",
339 __name__,
340 """
341Special value to raise a KeyError
343Raise KeyError in `BaseFormatter.pop` if passed as the default value to `pop`
344""",
345)
348class BaseFormatter(Configurable):
349 """A base formatter class that is configurable.
351 This formatter should usually be used as the base class of all formatters.
352 It is a traited :class:`Configurable` class and includes an extensible
353 API for users to determine how their objects are formatted. The following
354 logic is used to find a function to format an given object.
356 1. The object is introspected to see if it has a method with the name
357 :attr:`print_method`. If is does, that object is passed to that method
358 for formatting.
359 2. If no print method is found, three internal dictionaries are consulted
360 to find print method: :attr:`singleton_printers`, :attr:`type_printers`
361 and :attr:`deferred_printers`.
363 Users should use these dictionaries to register functions that will be
364 used to compute the format data for their objects (if those objects don't
365 have the special print methods). The easiest way of using these
366 dictionaries is through the :meth:`for_type` and :meth:`for_type_by_name`
367 methods.
369 If no function/callable is found to compute the format data, ``None`` is
370 returned and this format type is not used.
371 """
373 format_type = Unicode("text/plain")
374 _return_type: Any = str
376 enabled = Bool(True).tag(config=True)
378 print_method = ObjectName('__repr__')
380 # The singleton printers.
381 # Maps the IDs of the builtin singleton objects to the format functions.
382 singleton_printers = Dict().tag(config=True)
384 # The type-specific printers.
385 # Map type objects to the format functions.
386 type_printers = Dict().tag(config=True)
388 # The deferred-import type-specific printers.
389 # Map (modulename, classname) pairs to the format functions.
390 deferred_printers = Dict().tag(config=True)
392 @catch_format_error
393 def __call__(self, obj):
394 """Compute the format for an object."""
395 if self.enabled:
396 # lookup registered printer
397 try:
398 printer = self.lookup(obj)
399 except KeyError:
400 pass
401 else:
402 return printer(obj)
403 # Finally look for special method names
404 method = get_real_method(obj, self.print_method)
405 if method is not None:
406 return method()
407 return None
408 else:
409 return None
411 def __contains__(self, typ):
412 """map in to lookup_by_type"""
413 try:
414 self.lookup_by_type(typ)
415 except KeyError:
416 return False
417 else:
418 return True
420 def _check_return(self, r, obj):
421 """Check that a return value is appropriate
423 Return the value if so, None otherwise, warning if invalid.
424 """
425 if r is None or isinstance(r, self._return_type) or \
426 (isinstance(r, tuple) and r and isinstance(r[0], self._return_type)):
427 return r
428 else:
429 warnings.warn(
430 "%s formatter returned invalid type %s (expected %s) for object: %s" % \
431 (self.format_type, type(r), self._return_type, _safe_repr(obj)),
432 FormatterWarning
433 )
435 def lookup(self, obj):
436 """Look up the formatter for a given instance.
438 Parameters
439 ----------
440 obj : object instance
442 Returns
443 -------
444 f : callable
445 The registered formatting callable for the type.
447 Raises
448 ------
449 KeyError if the type has not been registered.
450 """
451 # look for singleton first
452 obj_id = id(obj)
453 if obj_id in self.singleton_printers:
454 return self.singleton_printers[obj_id]
455 # then lookup by type
456 return self.lookup_by_type(_get_type(obj))
458 def lookup_by_type(self, typ):
459 """Look up the registered formatter for a type.
461 Parameters
462 ----------
463 typ : type or '__module__.__name__' string for a type
465 Returns
466 -------
467 f : callable
468 The registered formatting callable for the type.
470 Raises
471 ------
472 KeyError if the type has not been registered.
473 """
474 if isinstance(typ, str):
475 typ_key = tuple(typ.rsplit('.',1))
476 if typ_key not in self.deferred_printers:
477 # We may have it cached in the type map. We will have to
478 # iterate over all of the types to check.
479 for cls in self.type_printers:
480 if _mod_name_key(cls) == typ_key:
481 return self.type_printers[cls]
482 else:
483 return self.deferred_printers[typ_key]
484 else:
485 for cls in pretty._get_mro(typ):
486 if cls in self.type_printers or self._in_deferred_types(cls):
487 return self.type_printers[cls]
489 # If we have reached here, the lookup failed.
490 raise KeyError("No registered printer for {0!r}".format(typ))
492 def for_type(self, typ, func=None):
493 """Add a format function for a given type.
495 Parameters
496 ----------
497 typ : type or '__module__.__name__' string for a type
498 The class of the object that will be formatted using `func`.
500 func : callable
501 A callable for computing the format data.
502 `func` will be called with the object to be formatted,
503 and will return the raw data in this formatter's format.
504 Subclasses may use a different call signature for the
505 `func` argument.
507 If `func` is None or not specified, there will be no change,
508 only returning the current value.
510 Returns
511 -------
512 oldfunc : callable
513 The currently registered callable.
514 If you are registering a new formatter,
515 this will be the previous value (to enable restoring later).
516 """
517 # if string given, interpret as 'pkg.module.class_name'
518 if isinstance(typ, str):
519 type_module, type_name = typ.rsplit('.', 1)
520 return self.for_type_by_name(type_module, type_name, func)
522 try:
523 oldfunc = self.lookup_by_type(typ)
524 except KeyError:
525 oldfunc = None
527 if func is not None:
528 self.type_printers[typ] = func
530 return oldfunc
532 def for_type_by_name(self, type_module, type_name, func=None):
533 """Add a format function for a type specified by the full dotted
534 module and name of the type, rather than the type of the object.
536 Parameters
537 ----------
538 type_module : str
539 The full dotted name of the module the type is defined in, like
540 ``numpy``.
542 type_name : str
543 The name of the type (the class name), like ``dtype``
545 func : callable
546 A callable for computing the format data.
547 `func` will be called with the object to be formatted,
548 and will return the raw data in this formatter's format.
549 Subclasses may use a different call signature for the
550 `func` argument.
552 If `func` is None or unspecified, there will be no change,
553 only returning the current value.
555 Returns
556 -------
557 oldfunc : callable
558 The currently registered callable.
559 If you are registering a new formatter,
560 this will be the previous value (to enable restoring later).
561 """
562 key = (type_module, type_name)
564 try:
565 oldfunc = self.lookup_by_type("%s.%s" % key)
566 except KeyError:
567 oldfunc = None
569 if func is not None:
570 self.deferred_printers[key] = func
571 return oldfunc
573 def pop(self, typ, default=_raise_key_error):
574 """Pop a formatter for the given type.
576 Parameters
577 ----------
578 typ : type or '__module__.__name__' string for a type
579 default : object
580 value to be returned if no formatter is registered for typ.
582 Returns
583 -------
584 obj : object
585 The last registered object for the type.
587 Raises
588 ------
589 KeyError if the type is not registered and default is not specified.
590 """
592 if isinstance(typ, str):
593 typ_key = tuple(typ.rsplit('.',1))
594 if typ_key not in self.deferred_printers:
595 # We may have it cached in the type map. We will have to
596 # iterate over all of the types to check.
597 for cls in self.type_printers:
598 if _mod_name_key(cls) == typ_key:
599 old = self.type_printers.pop(cls)
600 break
601 else:
602 old = default
603 else:
604 old = self.deferred_printers.pop(typ_key)
605 else:
606 if typ in self.type_printers:
607 old = self.type_printers.pop(typ)
608 else:
609 old = self.deferred_printers.pop(_mod_name_key(typ), default)
610 if old is _raise_key_error:
611 raise KeyError("No registered value for {0!r}".format(typ))
612 return old
614 def _in_deferred_types(self, cls):
615 """
616 Check if the given class is specified in the deferred type registry.
618 Successful matches will be moved to the regular type registry for future use.
619 """
620 mod = getattr(cls, '__module__', None)
621 name = getattr(cls, '__name__', None)
622 key = (mod, name)
623 if key in self.deferred_printers:
624 # Move the printer over to the regular registry.
625 printer = self.deferred_printers.pop(key)
626 self.type_printers[cls] = printer
627 return True
628 return False
631class PlainTextFormatter(BaseFormatter):
632 """The default pretty-printer.
634 This uses :mod:`IPython.lib.pretty` to compute the format data of
635 the object. If the object cannot be pretty printed, :func:`repr` is used.
636 See the documentation of :mod:`IPython.lib.pretty` for details on
637 how to write pretty printers. Here is a simple example::
639 def dtype_pprinter(obj, p, cycle):
640 if cycle:
641 return p.text('dtype(...)')
642 if hasattr(obj, 'fields'):
643 if obj.fields is None:
644 p.text(repr(obj))
645 else:
646 p.begin_group(7, 'dtype([')
647 for i, field in enumerate(obj.descr):
648 if i > 0:
649 p.text(',')
650 p.breakable()
651 p.pretty(field)
652 p.end_group(7, '])')
653 """
655 # The format type of data returned.
656 format_type = Unicode('text/plain')
658 # This subclass ignores this attribute as it always need to return
659 # something.
660 enabled = Bool(True).tag(config=False)
662 max_seq_length = Integer(pretty.MAX_SEQ_LENGTH,
663 help="""Truncate large collections (lists, dicts, tuples, sets) to this size.
665 Set to 0 to disable truncation.
666 """,
667 ).tag(config=True)
669 # Look for a _repr_pretty_ methods to use for pretty printing.
670 print_method = ObjectName('_repr_pretty_')
672 # Whether to pretty-print or not.
673 pprint = Bool(True).tag(config=True)
675 # Whether to be verbose or not.
676 verbose = Bool(False).tag(config=True)
678 # The maximum width.
679 max_width = Integer(79).tag(config=True)
681 # The newline character.
682 newline = Unicode('\n').tag(config=True)
684 # format-string for pprinting floats
685 float_format = Unicode('%r')
686 # setter for float precision, either int or direct format-string
687 float_precision = CUnicode('').tag(config=True)
689 @observe('float_precision')
690 def _float_precision_changed(self, change):
691 """float_precision changed, set float_format accordingly.
693 float_precision can be set by int or str.
694 This will set float_format, after interpreting input.
695 If numpy has been imported, numpy print precision will also be set.
697 integer `n` sets format to '%.nf', otherwise, format set directly.
699 An empty string returns to defaults (repr for float, 8 for numpy).
701 This parameter can be set via the '%precision' magic.
702 """
703 new = change['new']
704 if '%' in new:
705 # got explicit format string
706 fmt = new
707 try:
708 fmt%3.14159
709 except Exception as e:
710 raise ValueError("Precision must be int or format string, not %r"%new) from e
711 elif new:
712 # otherwise, should be an int
713 try:
714 i = int(new)
715 assert i >= 0
716 except ValueError as e:
717 raise ValueError("Precision must be int or format string, not %r"%new) from e
718 except AssertionError as e:
719 raise ValueError("int precision must be non-negative, not %r"%i) from e
721 fmt = '%%.%if'%i
722 if 'numpy' in sys.modules:
723 # set numpy precision if it has been imported
724 import numpy
725 numpy.set_printoptions(precision=i)
726 else:
727 # default back to repr
728 fmt = '%r'
729 if 'numpy' in sys.modules:
730 import numpy
731 # numpy default is 8
732 numpy.set_printoptions(precision=8)
733 self.float_format = fmt
735 # Use the default pretty printers from IPython.lib.pretty.
736 @default('singleton_printers')
737 def _singleton_printers_default(self):
738 return pretty._singleton_pprinters.copy()
740 @default('type_printers')
741 def _type_printers_default(self):
742 d = pretty._type_pprinters.copy()
743 d[float] = lambda obj,p,cycle: p.text(self.float_format%obj)
744 # if NumPy is used, set precision for its float64 type
745 if "numpy" in sys.modules:
746 import numpy
748 d[numpy.float64] = lambda obj, p, cycle: p.text(self.float_format % obj)
749 return d
751 @default('deferred_printers')
752 def _deferred_printers_default(self):
753 return pretty._deferred_type_pprinters.copy()
755 #### FormatterABC interface ####
757 @catch_format_error
758 def __call__(self, obj):
759 """Compute the pretty representation of the object."""
760 if not self.pprint:
761 return repr(obj)
762 else:
763 stream = StringIO()
764 printer = pretty.RepresentationPrinter(stream, self.verbose,
765 self.max_width, self.newline,
766 max_seq_length=self.max_seq_length,
767 singleton_pprinters=self.singleton_printers,
768 type_pprinters=self.type_printers,
769 deferred_pprinters=self.deferred_printers)
770 printer.pretty(obj)
771 printer.flush()
772 return stream.getvalue()
775class HTMLFormatter(BaseFormatter):
776 """An HTML formatter.
778 To define the callables that compute the HTML representation of your
779 objects, define a :meth:`_repr_html_` method or use the :meth:`for_type`
780 or :meth:`for_type_by_name` methods to register functions that handle
781 this.
783 The return value of this formatter should be a valid HTML snippet that
784 could be injected into an existing DOM. It should *not* include the
785 ```<html>`` or ```<body>`` tags.
786 """
787 format_type = Unicode('text/html')
789 print_method = ObjectName('_repr_html_')
792class MarkdownFormatter(BaseFormatter):
793 """A Markdown formatter.
795 To define the callables that compute the Markdown representation of your
796 objects, define a :meth:`_repr_markdown_` method or use the :meth:`for_type`
797 or :meth:`for_type_by_name` methods to register functions that handle
798 this.
800 The return value of this formatter should be a valid Markdown.
801 """
802 format_type = Unicode('text/markdown')
804 print_method = ObjectName('_repr_markdown_')
806class SVGFormatter(BaseFormatter):
807 """An SVG formatter.
809 To define the callables that compute the SVG representation of your
810 objects, define a :meth:`_repr_svg_` method or use the :meth:`for_type`
811 or :meth:`for_type_by_name` methods to register functions that handle
812 this.
814 The return value of this formatter should be valid SVG enclosed in
815 ```<svg>``` tags, that could be injected into an existing DOM. It should
816 *not* include the ```<html>`` or ```<body>`` tags.
817 """
818 format_type = Unicode('image/svg+xml')
820 print_method = ObjectName('_repr_svg_')
823class PNGFormatter(BaseFormatter):
824 """A PNG formatter.
826 To define the callables that compute the PNG representation of your
827 objects, define a :meth:`_repr_png_` method or use the :meth:`for_type`
828 or :meth:`for_type_by_name` methods to register functions that handle
829 this.
831 The return value of this formatter should be raw PNG data, *not*
832 base64 encoded.
833 """
834 format_type = Unicode('image/png')
836 print_method = ObjectName('_repr_png_')
838 _return_type = (bytes, str)
841class JPEGFormatter(BaseFormatter):
842 """A JPEG formatter.
844 To define the callables that compute the JPEG representation of your
845 objects, define a :meth:`_repr_jpeg_` method or use the :meth:`for_type`
846 or :meth:`for_type_by_name` methods to register functions that handle
847 this.
849 The return value of this formatter should be raw JPEG data, *not*
850 base64 encoded.
851 """
852 format_type = Unicode('image/jpeg')
854 print_method = ObjectName('_repr_jpeg_')
856 _return_type = (bytes, str)
859class LatexFormatter(BaseFormatter):
860 """A LaTeX formatter.
862 To define the callables that compute the LaTeX representation of your
863 objects, define a :meth:`_repr_latex_` method or use the :meth:`for_type`
864 or :meth:`for_type_by_name` methods to register functions that handle
865 this.
867 The return value of this formatter should be a valid LaTeX equation,
868 enclosed in either ```$```, ```$$``` or another LaTeX equation
869 environment.
870 """
871 format_type = Unicode('text/latex')
873 print_method = ObjectName('_repr_latex_')
876class JSONFormatter(BaseFormatter):
877 """A JSON string formatter.
879 To define the callables that compute the JSONable representation of
880 your objects, define a :meth:`_repr_json_` method or use the :meth:`for_type`
881 or :meth:`for_type_by_name` methods to register functions that handle
882 this.
884 The return value of this formatter should be a JSONable list or dict.
885 JSON scalars (None, number, string) are not allowed, only dict or list containers.
886 """
887 format_type = Unicode('application/json')
888 _return_type = (list, dict)
890 print_method = ObjectName('_repr_json_')
892 def _check_return(self, r, obj):
893 """Check that a return value is appropriate
895 Return the value if so, None otherwise, warning if invalid.
896 """
897 if r is None:
898 return
899 md = None
900 if isinstance(r, tuple):
901 # unpack data, metadata tuple for type checking on first element
902 r, md = r
904 assert not isinstance(
905 r, str
906 ), "JSON-as-string has been deprecated since IPython < 3"
908 if md is not None:
909 # put the tuple back together
910 r = (r, md)
911 return super(JSONFormatter, self)._check_return(r, obj)
914class JavascriptFormatter(BaseFormatter):
915 """A Javascript formatter.
917 To define the callables that compute the Javascript representation of
918 your objects, define a :meth:`_repr_javascript_` method or use the
919 :meth:`for_type` or :meth:`for_type_by_name` methods to register functions
920 that handle this.
922 The return value of this formatter should be valid Javascript code and
923 should *not* be enclosed in ```<script>``` tags.
924 """
925 format_type = Unicode('application/javascript')
927 print_method = ObjectName('_repr_javascript_')
930class PDFFormatter(BaseFormatter):
931 """A PDF formatter.
933 To define the callables that compute the PDF representation of your
934 objects, define a :meth:`_repr_pdf_` method or use the :meth:`for_type`
935 or :meth:`for_type_by_name` methods to register functions that handle
936 this.
938 The return value of this formatter should be raw PDF data, *not*
939 base64 encoded.
940 """
941 format_type = Unicode('application/pdf')
943 print_method = ObjectName('_repr_pdf_')
945 _return_type = (bytes, str)
947class IPythonDisplayFormatter(BaseFormatter):
948 """An escape-hatch Formatter for objects that know how to display themselves.
950 To define the callables that compute the representation of your
951 objects, define a :meth:`_ipython_display_` method or use the :meth:`for_type`
952 or :meth:`for_type_by_name` methods to register functions that handle
953 this. Unlike mime-type displays, this method should not return anything,
954 instead calling any appropriate display methods itself.
956 This display formatter has highest priority.
957 If it fires, no other display formatter will be called.
959 Prior to IPython 6.1, `_ipython_display_` was the only way to display custom mime-types
960 without registering a new Formatter.
962 IPython 6.1 introduces `_repr_mimebundle_` for displaying custom mime-types,
963 so `_ipython_display_` should only be used for objects that require unusual
964 display patterns, such as multiple display calls.
965 """
966 print_method = ObjectName('_ipython_display_')
967 _return_type = (type(None), bool)
969 @catch_format_error
970 def __call__(self, obj):
971 """Compute the format for an object."""
972 if self.enabled:
973 # lookup registered printer
974 try:
975 printer = self.lookup(obj)
976 except KeyError:
977 pass
978 else:
979 printer(obj)
980 return True
981 # Finally look for special method names
982 method = get_real_method(obj, self.print_method)
983 if method is not None:
984 method()
985 return True
988class MimeBundleFormatter(BaseFormatter):
989 """A Formatter for arbitrary mime-types.
991 Unlike other `_repr_<mimetype>_` methods,
992 `_repr_mimebundle_` should return mime-bundle data,
993 either the mime-keyed `data` dictionary or the tuple `(data, metadata)`.
994 Any mime-type is valid.
996 To define the callables that compute the mime-bundle representation of your
997 objects, define a :meth:`_repr_mimebundle_` method or use the :meth:`for_type`
998 or :meth:`for_type_by_name` methods to register functions that handle
999 this.
1001 .. versionadded:: 6.1
1002 """
1003 print_method = ObjectName('_repr_mimebundle_')
1004 _return_type = dict
1006 def _check_return(self, r, obj):
1007 r = super(MimeBundleFormatter, self)._check_return(r, obj)
1008 # always return (data, metadata):
1009 if r is None:
1010 return {}, {}
1011 if not isinstance(r, tuple):
1012 return r, {}
1013 return r
1015 @catch_format_error
1016 def __call__(self, obj, include=None, exclude=None):
1017 """Compute the format for an object.
1019 Identical to parent's method but we pass extra parameters to the method.
1021 Unlike other _repr_*_ `_repr_mimebundle_` should allow extra kwargs, in
1022 particular `include` and `exclude`.
1023 """
1024 if self.enabled:
1025 # lookup registered printer
1026 try:
1027 printer = self.lookup(obj)
1028 except KeyError:
1029 pass
1030 else:
1031 return printer(obj)
1032 # Finally look for special method names
1033 method = get_real_method(obj, self.print_method)
1035 if method is not None:
1036 return method(include=include, exclude=exclude)
1037 return None
1038 else:
1039 return None
1042FormatterABC.register(BaseFormatter)
1043FormatterABC.register(PlainTextFormatter)
1044FormatterABC.register(HTMLFormatter)
1045FormatterABC.register(MarkdownFormatter)
1046FormatterABC.register(SVGFormatter)
1047FormatterABC.register(PNGFormatter)
1048FormatterABC.register(PDFFormatter)
1049FormatterABC.register(JPEGFormatter)
1050FormatterABC.register(LatexFormatter)
1051FormatterABC.register(JSONFormatter)
1052FormatterABC.register(JavascriptFormatter)
1053FormatterABC.register(IPythonDisplayFormatter)
1054FormatterABC.register(MimeBundleFormatter)
1057def format_display_data(obj, include=None, exclude=None):
1058 """Return a format data dict for an object.
1060 By default all format types will be computed.
1062 Parameters
1063 ----------
1064 obj : object
1065 The Python object whose format data will be computed.
1067 Returns
1068 -------
1069 format_dict : dict
1070 A dictionary of key/value pairs, one or each format that was
1071 generated for the object. The keys are the format types, which
1072 will usually be MIME type strings and the values and JSON'able
1073 data structure containing the raw data for the representation in
1074 that format.
1075 include : list or tuple, optional
1076 A list of format type strings (MIME types) to include in the
1077 format data dict. If this is set *only* the format types included
1078 in this list will be computed.
1079 exclude : list or tuple, optional
1080 A list of format type string (MIME types) to exclude in the format
1081 data dict. If this is set all format types will be computed,
1082 except for those included in this argument.
1083 """
1084 from .interactiveshell import InteractiveShell
1086 return InteractiveShell.instance().display_formatter.format(
1087 obj,
1088 include,
1089 exclude
1090 )