##// END OF EJS Templates
Clarify rich display docs, tabulate reprs...
Terry Davis -
Show More
@@ -24,14 +24,59 b' returns a list of objects which are possible keys in a subscript expression'
24 Rich display
24 Rich display
25 ============
25 ============
26
26
27 The notebook and the Qt console can display richer representations of objects.
27 Custom methods
28 To use this, you can define any of a number of ``_repr_*_()`` methods. Note that
28 ----------------------
29 these are surrounded by single, not double underscores.
29 IPython can display richer representations of objects.
30
30 To do this, you can define ``_ipython_display_()``, or any of a number of
31 Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg``
31 ``_repr_*_()`` methods.
32 representations. The notebook can also display ``html``, ``javascript``,
32 Note that these are surrounded by single, not double underscores.
33 ``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it
33
34 falls back to a standard ``repr()``.
34 .. list-table:: Supported ``_repr_*_`` methods
35 :widths: 20 15 15 15
36 :header-rows: 1
37
38 * - Format
39 - REPL
40 - Notebook
41 - Qt Console
42 * - ``_repr_pretty_``
43 - yes
44 - yes
45 - yes
46 * - ``_repr_svg_``
47 - no
48 - yes
49 - yes
50 * - ``_repr_png_``
51 - no
52 - yes
53 - yes
54 * - ``_repr_jpeg_``
55 - no
56 - yes
57 - yes
58 * - ``_repr_html_``
59 - no
60 - yes
61 - no
62 * - ``_repr_javascript_``
63 - no
64 - yes
65 - no
66 * - ``_repr_markdown_``
67 - no
68 - yes
69 - no
70 * - ``_repr_latex_``
71 - no
72 - yes
73 - no
74 * - ``_repr_mimebundle_``
75 - no
76 - ?
77 - ?
78
79 If the methods don't exist, or return ``None``, the standard ``repr()`` is used.
35
80
36 For example::
81 For example::
37
82
@@ -42,43 +87,61 b' For example::'
42 def _repr_html_(self):
87 def _repr_html_(self):
43 return "<h1>" + self.text + "</h1>"
88 return "<h1>" + self.text + "</h1>"
44
89
45 We often want to provide frontends with guidance on how to display the data. To
46 support this, ``_repr_*_()`` methods can also return a ``(data, metadata)``
47 tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
48 the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
49 be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
50 to inform the frontend how to size the image.
51
90
52 There are also two more powerful display methods:
91 Special methods
92 ^^^^^^^^^^^^^^^
93
94 Pretty printing
95 """""""""""""""
96
97 To customize how your object is pretty-printed, add a `_repr_pretty_` method
98 to the class.
99 The method should accept a pretty printer, and a boolean that indicates whether
100 the printer detected a cycle.
101 The method should act on the printer to produce your customized pretty output.
102 Here is an example::
103
104 class MyObject(object):
105
106 def _repr_pretty_(self, p, cycle):
107 if cycle:
108 p.text('MyObject(...)')
109 else:
110 p.text('MyObject[...]')
111
112 For details on how to use the pretty printer, see :py:mod:`IPython.lib.pretty`.
113
114 More powerful methods
115 """""""""""""""""""""
53
116
54 .. class:: MyObject
117 .. class:: MyObject
55
118
56 .. method:: _repr_mimebundle_(include=None, exclude=None)
119 .. method:: _repr_mimebundle_(include=None, exclude=None)
57
120
58 Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
121 Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
59 of two dictionaries: *data, metadata*. If this returns something, other
122 of two dictionaries: *data, metadata* (see :ref:`Metadata`).
60 ``_repr_*_`` methods are ignored. The method should take keyword arguments
123 If this returns something, other ``_repr_*_`` methods are ignored.
61 ``include`` and ``exclude``, though it is not required to respect them.
124 The method should take keyword arguments ``include`` and ``exclude``, though
125 it is not required to respect them.
62
126
63 .. method:: _ipython_display_()
127 .. method:: _ipython_display_()
64
128
65 Displays the object as a side effect; the return value is ignored. If this
129 Displays the object as a side effect; the return value is ignored. If this
66 is defined, all other display methods are ignored.
130 is defined, all other display methods are ignored.
131 This method is ignored in the REPL.
67
132
68 To customize how the REPL pretty-prints your object, add a `_repr_pretty_`
69 method to the class. The method should accept a pretty printer, and a boolean
70 that indicates whether the printer detected a cycle. The method should act on
71 the printer to produce your customized pretty output. Here is an example::
72
133
73 class MyObject(object):
134 Metadata
135 ^^^^^^^^
136
137 We often want to provide frontends with guidance on how to display the data. To
138 support this, ``_repr_*_()`` methods (except `_repr_pretty_``?) can also return a ``(data, metadata)``
139 tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
140 the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
141 be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
142 to inform the frontend how to size the image.
74
143
75 def _repr_pretty_(self, p, cycle):
76 if cycle:
77 p.text('MyObject(...)')
78 else:
79 p.text('MyObject[...]')
80
144
81 For details, see :py:mod:`IPython.lib.pretty`.
82
145
83 Formatters for third-party types
146 Formatters for third-party types
84 --------------------------------
147 --------------------------------
General Comments 0
You need to be logged in to leave comments. Login now