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