##// END OF EJS Templates
Clarify rich display docs, tabulate reprs...
Terry Davis -
Show More
@@ -1,110 +1,173 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 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
38 class Shout(object):
83 class Shout(object):
39 def __init__(self, text):
84 def __init__(self, text):
40 self.text = text
85 self.text = text
41
86
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 --------------------------------
85
148
86 The user can also register formatters for types without modifying the class::
149 The user can also register formatters for types without modifying the class::
87
150
88 from bar.baz import Foo
151 from bar.baz import Foo
89
152
90 def foo_html(obj):
153 def foo_html(obj):
91 return '<marquee>Foo object %s</marquee>' % obj.name
154 return '<marquee>Foo object %s</marquee>' % obj.name
92
155
93 html_formatter = get_ipython().display_formatter.formatters['text/html']
156 html_formatter = get_ipython().display_formatter.formatters['text/html']
94 html_formatter.for_type(Foo, foo_html)
157 html_formatter.for_type(Foo, foo_html)
95
158
96 # Or register a type without importing it - this does the same as above:
159 # Or register a type without importing it - this does the same as above:
97 html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html)
160 html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html)
98
161
99 Custom exception tracebacks
162 Custom exception tracebacks
100 ===========================
163 ===========================
101
164
102 Rarely, you might want to display a custom traceback when reporting an
165 Rarely, you might want to display a custom traceback when reporting an
103 exception. To do this, define the custom traceback using
166 exception. To do this, define the custom traceback using
104 `_render_traceback_(self)` method which returns a list of strings, one string
167 `_render_traceback_(self)` method which returns a list of strings, one string
105 for each line of the traceback. For example, the `ipyparallel
168 for each line of the traceback. For example, the `ipyparallel
106 <https://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
169 <https://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
107 IPython, does this to display errors from multiple engines.
170 IPython, does this to display errors from multiple engines.
108
171
109 Please be conservative in using this feature; by replacing the default traceback
172 Please be conservative in using this feature; by replacing the default traceback
110 you may hide important information from the user.
173 you may hide important information from the user.
General Comments 0
You need to be logged in to leave comments. Login now