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