##// END OF EJS Templates
Apply suggestions from code review
Matthias Bussonnier -
Show More
@@ -1,173 +1,173 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 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 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 131 This method is ignored in the REPL.
132 132
133 133
134 134 Metadata
135 135 ^^^^^^^^
136 136
137 137 We often want to provide frontends with guidance on how to display the data. To
138 138 support this, ``_repr_*_()`` methods (except `_repr_pretty_``?) can also return a ``(data, metadata)``
139 139 tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for
140 140 the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can
141 141 be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary
142 142 to inform the frontend how to size the image.
143 143
144 144
145 145
146 146 Formatters for third-party types
147 147 --------------------------------
148 148
149 149 The user can also register formatters for types without modifying the class::
150 150
151 151 from bar.baz import Foo
152 152
153 153 def foo_html(obj):
154 154 return '<marquee>Foo object %s</marquee>' % obj.name
155 155
156 156 html_formatter = get_ipython().display_formatter.formatters['text/html']
157 157 html_formatter.for_type(Foo, foo_html)
158 158
159 159 # Or register a type without importing it - this does the same as above:
160 160 html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html)
161 161
162 162 Custom exception tracebacks
163 163 ===========================
164 164
165 165 Rarely, you might want to display a custom traceback when reporting an
166 166 exception. To do this, define the custom traceback using
167 167 `_render_traceback_(self)` method which returns a list of strings, one string
168 168 for each line of the traceback. For example, the `ipyparallel
169 169 <https://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
170 170 IPython, does this to display errors from multiple engines.
171 171
172 172 Please be conservative in using this feature; by replacing the default traceback
173 173 you may hide important information from the user.
General Comments 0
You need to be logged in to leave comments. Login now