.. _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 `dir() function `_. 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, or return ``None``, the standard ``repr()`` is used. For example:: class Shout(object): def __init__(self, text): self.text = text def _repr_html_(self): return "

" + self.text + "

" 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. 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 'Foo object %s' % 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 `__ 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.