From b1afef3a0567cd2831a18c584973bc99a68a6244 2018-10-01 13:41:54 From: Michael Penkov Date: 2018-10-01 13:41:54 Subject: [PATCH] Fix #10973: improve documentation for _repr_ functions --- diff --git a/IPython/core/display.py b/IPython/core/display.py index ca5c3aa..8cecd71 100644 --- a/IPython/core/display.py +++ b/IPython/core/display.py @@ -238,16 +238,22 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di want to use. Here is a list of the names of the special methods and the values they must return: - - `_repr_html_`: return raw HTML as a string - - `_repr_json_`: return a JSONable dict - - `_repr_jpeg_`: return raw JPEG data - - `_repr_png_`: return raw PNG data - - `_repr_svg_`: return raw SVG data as a string - - `_repr_latex_`: return LaTeX commands in a string surrounded by "$". + - `_repr_html_`: return raw HTML as a string, or a tuple (see below). + - `_repr_json_`: return a JSONable dict, or a tuple (see below). + - `_repr_jpeg_`: return raw JPEG data, or a tuple (see below). + - `_repr_png_`: return raw PNG data, or a tuple (see below). + - `_repr_svg_`: return raw SVG data as a string, or a tuple (see below). + - `_repr_latex_`: return LaTeX commands in a string surrounded by "$", + or a tuple (see below). - `_repr_mimebundle_`: return a full mimebundle containing the mapping from all mimetypes to data. Use this for any mime-type not listed above. + The above functions may also return the object's metadata alonside the + data. If the metadata is available, the functions will return a tuple + containing the data and metadata, in that order. If there is no metadata + available, then the functions will return the data only. + When you are directly writing your own classes, you can adapt them for display in IPython by following the above approach. But in practice, you often need to work with existing classes that you can't easily modify.