From 29190f6339019a8f89a9317162c8b20c86435177 2023-02-21 13:15:08 From: Matthias Bussonnier Date: 2023-02-21 13:15:08 Subject: [PATCH] add a little detail to custom repr method docs (#13945) These docs are a bit sparse, so I added a couple details that might help implementers: - explicitly state the return type, rather than only via example - give some examples of PNG, HTML - note that formatters shouldn't be sensitive to other formats related to https://github.com/Textualize/rich/pull/2806 which didn't follow the spec, in part I think because the docs weren't explicit enough about exactly what a formatter should do. --- diff --git a/docs/source/config/integrating.rst b/docs/source/config/integrating.rst index 23cc1e5..4e6f9d9 100644 --- a/docs/source/config/integrating.rst +++ b/docs/source/config/integrating.rst @@ -26,15 +26,17 @@ 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. +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 @@ -76,14 +78,24 @@ Note that these are surrounded by single, not double underscores. - ? - ? -If the methods don't exist, or return ``None``, the standard ``repr()`` is used. +If the methods don't exist, the standard ``repr()`` is used. +If a method exists and returns ``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 "

" + self.text + "

" @@ -95,7 +107,7 @@ Pretty printing """"""""""""""" To customize how your object is pretty-printed, add a ``_repr_pretty_`` method -to the class. +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. @@ -121,7 +133,7 @@ More powerful methods 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 + The method should take keyword arguments ``include`` and ``exclude``, though it is not required to respect them. .. method:: _ipython_display_()