##// END OF EJS Templates
add a little detail to custom repr method docs...
Min RK -
Show More
@@ -26,15 +26,17 b' Rich display'
26 26
27 27 Custom methods
28 28 ----------------------
29
29 30 IPython can display richer representations of objects.
30 To do this, you can define ``_ipython_display_()``, or any of a number of
31 ``_repr_*_()`` methods.
31 To do this, you can define ``_ipython_display_()``, or any of a number of
32 ``_repr_*_()`` methods.
32 33 Note that these are surrounded by single, not double underscores.
33 34
35
34 36 .. list-table:: Supported ``_repr_*_`` methods
35 37 :widths: 20 15 15 15
36 38 :header-rows: 1
37
39
38 40 * - Format
39 41 - REPL
40 42 - Notebook
@@ -76,14 +78,24 b' Note that these are surrounded by single, not double underscores.'
76 78 - ?
77 79 - ?
78 80
79 If the methods don't exist, or return ``None``, the standard ``repr()`` is used.
81 If the methods don't exist, the standard ``repr()`` is used.
82 If a method exists and returns ``None``, it is treated the same as if it does not exist.
83 In general, *all* available formatters will be called when an object is displayed,
84 and it is up to the UI to select which to display.
85 A given formatter should not generally change its output based on what other formats are available -
86 that should be handled at a different level, such as the :class:`~.DisplayFormatter`, or configuration.
87
88 ``_repr_*_`` methods should *return* data of the expected format and have no side effects.
89 For example, ``_repr_html_`` should return HTML as a `str` and ``_repr_png_`` should return PNG data as `bytes`.
90
91 If you wish to take control of display via your own side effects, use ``_ipython_display_()``.
80 92
81 93 For example::
82 94
83 95 class Shout(object):
84 96 def __init__(self, text):
85 97 self.text = text
86
98
87 99 def _repr_html_(self):
88 100 return "<h1>" + self.text + "</h1>"
89 101
@@ -95,7 +107,7 b' Pretty printing'
95 107 """""""""""""""
96 108
97 109 To customize how your object is pretty-printed, add a ``_repr_pretty_`` method
98 to the class.
110 to the class.
99 111 The method should accept a pretty printer, and a boolean that indicates whether
100 112 the printer detected a cycle.
101 113 The method should act on the printer to produce your customized pretty output.
@@ -121,7 +133,7 b' More powerful methods'
121 133 Should return a dictionary of multiple formats, keyed by mimetype, or a tuple
122 134 of two dictionaries: *data, metadata* (see :ref:`Metadata`).
123 135 If this returns something, other ``_repr_*_`` methods are ignored.
124 The method should take keyword arguments ``include`` and ``exclude``, though
136 The method should take keyword arguments ``include`` and ``exclude``, though
125 137 it is not required to respect them.
126 138
127 139 .. method:: _ipython_display_()
General Comments 0
You need to be logged in to leave comments. Login now