##// END OF EJS Templates
docs: remove mention of `_ipython_display_` being ignored in the REPL
Angus Hollands -
Show More
@@ -1,173 +1,172 b''
1 1 .. _integrating:
2 2
3 3 =====================================
4 4 Integrating your objects with IPython
5 5 =====================================
6 6
7 7 Tab completion
8 8 ==============
9 9
10 10 To change the attributes displayed by tab-completing your object, define a
11 11 ``__dir__(self)`` method for it. For more details, see the documentation of the
12 12 built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
13 13
14 14 You can also customise key completions for your objects, e.g. pressing tab after
15 15 ``obj["a``. To do so, define a method ``_ipython_key_completions_()``, which
16 16 returns a list of objects which are possible keys in a subscript expression
17 17 ``obj[key]``.
18 18
19 19 .. versionadded:: 5.0
20 20 Custom key completions
21 21
22 22 .. _integrating_rich_display:
23 23
24 24 Rich display
25 25 ============
26 26
27 27 Custom methods
28 28 ----------------------
29 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 31 ``_repr_*_()`` methods.
32 32 Note that these are surrounded by single, not double underscores.
33 33
34 34 .. list-table:: Supported ``_repr_*_`` methods
35 35 :widths: 20 15 15 15
36 36 :header-rows: 1
37 37
38 38 * - Format
39 39 - REPL
40 40 - Notebook
41 41 - Qt Console
42 42 * - ``_repr_pretty_``
43 43 - yes
44 44 - yes
45 45 - yes
46 46 * - ``_repr_svg_``
47 47 - no
48 48 - yes
49 49 - yes
50 50 * - ``_repr_png_``
51 51 - no
52 52 - yes
53 53 - yes
54 54 * - ``_repr_jpeg_``
55 55 - no
56 56 - yes
57 57 - yes
58 58 * - ``_repr_html_``
59 59 - no
60 60 - yes
61 61 - no
62 62 * - ``_repr_javascript_``
63 63 - no
64 64 - yes
65 65 - no
66 66 * - ``_repr_markdown_``
67 67 - no
68 68 - yes
69 69 - no
70 70 * - ``_repr_latex_``
71 71 - no
72 72 - yes
73 73 - no
74 74 * - ``_repr_mimebundle_``
75 75 - no
76 76 - ?
77 77 - ?
78 78
79 79 If the methods don't exist, or return ``None``, the standard ``repr()`` is used.
80 80
81 81 For example::
82 82
83 83 class Shout(object):
84 84 def __init__(self, text):
85 85 self.text = text
86 86
87 87 def _repr_html_(self):
88 88 return "<h1>" + self.text + "</h1>"
89 89
90 90
91 91 Special methods
92 92 ^^^^^^^^^^^^^^^
93 93
94 94 Pretty printing
95 95 """""""""""""""
96 96
97 97 To customize how your object is pretty-printed, add a ``_repr_pretty_`` method
98 98 to the class.
99 99 The method should accept a pretty printer, and a boolean that indicates whether
100 100 the printer detected a cycle.
101 101 The method should act on the printer to produce your customized pretty output.
102 102 Here is an example::
103 103
104 104 class MyObject(object):
105 105
106 106 def _repr_pretty_(self, p, cycle):
107 107 if cycle:
108 108 p.text('MyObject(...)')
109 109 else:
110 110 p.text('MyObject[...]')
111 111
112 112 For details on how to use the pretty printer, see :py:mod:`IPython.lib.pretty`.
113 113
114 114 More powerful methods
115 115 """""""""""""""""""""
116 116
117 117 .. class:: MyObject
118 118
119 119 .. method:: _repr_mimebundle_(include=None, exclude=None)
120 120
121 121 Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
122 122 of two dictionaries: *data, metadata* (see :ref:`Metadata`).
123 123 If this returns something, other ``_repr_*_`` methods are ignored.
124 124 The method should take keyword arguments ``include`` and ``exclude``, though
125 125 it is not required to respect them.
126 126
127 127 .. method:: _ipython_display_()
128 128
129 129 Displays the object as a side effect; the return value is ignored. If this
130 130 is defined, all other display methods are ignored.
131 This method is ignored in the REPL.
132 131
133 132
134 133 Metadata
135 134 ^^^^^^^^
136 135
137 136 We often want to provide frontends with guidance on how to display the data. To
138 137 support this, ``_repr_*_()`` methods (except ``_repr_pretty_``?) can also return a ``(data, metadata)``
139 138 tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
140 139 the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
141 140 be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
142 141 to inform the frontend how to size the image.
143 142
144 143
145 144
146 145 Formatters for third-party types
147 146 --------------------------------
148 147
149 148 The user can also register formatters for types without modifying the class::
150 149
151 150 from bar.baz import Foo
152 151
153 152 def foo_html(obj):
154 153 return '<marquee>Foo object %s</marquee>' % obj.name
155 154
156 155 html_formatter = get_ipython().display_formatter.formatters['text/html']
157 156 html_formatter.for_type(Foo, foo_html)
158 157
159 158 # Or register a type without importing it - this does the same as above:
160 159 html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html)
161 160
162 161 Custom exception tracebacks
163 162 ===========================
164 163
165 164 Rarely, you might want to display a custom traceback when reporting an
166 165 exception. To do this, define the custom traceback using
167 166 `_render_traceback_(self)` method which returns a list of strings, one string
168 167 for each line of the traceback. For example, the `ipyparallel
169 168 <https://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
170 169 IPython, does this to display errors from multiple engines.
171 170
172 171 Please be conservative in using this feature; by replacing the default traceback
173 172 you may hide important information from the user.
General Comments 0
You need to be logged in to leave comments. Login now