integrating.rst
186 lines
| 5.4 KiB
| text/x-rst
|
RstLexer
Thomas Kluyver
|
r8083 | .. _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 | ||||
M Bussonnier
|
r28959 | built-in :external+python:py:func:`dir` | ||
Thomas Kluyver
|
r8083 | |||
Thomas Kluyver
|
r22147 | 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 | ||||
Thomas Kluyver
|
r24041 | .. _integrating_rich_display: | ||
Thomas Kluyver
|
r8083 | Rich display | ||
============ | ||||
Terry Davis
|
r26580 | Custom methods | ||
M Bussonnier
|
r28959 | -------------- | ||
Min RK
|
r28119 | |||
Terry Davis
|
r26580 | IPython can display richer representations of objects. | ||
Min RK
|
r28119 | To do this, you can define ``_ipython_display_()``, or any of a number of | ||
``_repr_*_()`` methods. | ||||
Terry Davis
|
r26580 | Note that these are surrounded by single, not double underscores. | ||
Min RK
|
r28119 | |||
Terry Davis
|
r26580 | .. list-table:: Supported ``_repr_*_`` methods | ||
:widths: 20 15 15 15 | ||||
:header-rows: 1 | ||||
Min RK
|
r28119 | |||
Terry Davis
|
r26580 | * - 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 | ||||
- ? | ||||
- ? | ||||
Min RK
|
r28119 | 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_()``. | ||||
Thomas Kluyver
|
r8083 | |||
For example:: | ||||
class Shout(object): | ||||
def __init__(self, text): | ||||
self.text = text | ||||
Min RK
|
r28119 | |||
Thomas Kluyver
|
r8083 | def _repr_html_(self): | ||
return "<h1>" + self.text + "</h1>" | ||||
Zi Chong Kao
|
r24302 | |||
Terry Davis
|
r26580 | Special methods | ||
^^^^^^^^^^^^^^^ | ||||
Pretty printing | ||||
""""""""""""""" | ||||
Matthias Bussonnier
|
r26581 | To customize how your object is pretty-printed, add a ``_repr_pretty_`` method | ||
Min RK
|
r28119 | to the class. | ||
Terry Davis
|
r26580 | 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 | ||||
""""""""""""""""""""" | ||||
Thomas Kluyver
|
r24036 | |||
.. class:: MyObject | ||||
.. method:: _repr_mimebundle_(include=None, exclude=None) | ||||
Should return a dictionary of multiple formats, keyed by mimetype, or a tuple | ||||
Terry Davis
|
r26580 | of two dictionaries: *data, metadata* (see :ref:`Metadata`). | ||
If this returns something, other ``_repr_*_`` methods are ignored. | ||||
Min RK
|
r28119 | The method should take keyword arguments ``include`` and ``exclude``, though | ||
Terry Davis
|
r26580 | it is not required to respect them. | ||
Thomas Kluyver
|
r24036 | |||
.. 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. | ||||
Michael Penkov
|
r24620 | |||
Terry Davis
|
r26580 | Metadata | ||
^^^^^^^^ | ||||
We often want to provide frontends with guidance on how to display the data. To | ||||
Matthias Bussonnier
|
r27637 | support this, ``_repr_*_()`` methods (except ``_repr_pretty_``?) can also return a ``(data, metadata)`` | ||
Terry Davis
|
r26580 | 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. | ||||
Michael Penkov
|
r24620 | |||
M Bussonnier
|
r28959 | .. _third_party_formatting: | ||
Thomas Kluyver
|
r24036 | Formatters for third-party types | ||
-------------------------------- | ||||
The user can also register formatters for types without modifying the class:: | ||||
Dan Allan
|
r25165 | from bar.baz import Foo | ||
Thomas Kluyver
|
r24036 | |||
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: | ||||
Dan Allan
|
r25165 | html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html) | ||
Thomas Kluyver
|
r24036 | |||
Thomas Kluyver
|
r8083 | Custom exception tracebacks | ||
=========================== | ||||
Matthias Bussonnier
|
r22788 | 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 | ||||
谭九鼎
|
r26565 | <https://ipyparallel.readthedocs.io/>`__ a parallel computing framework for | ||
Matthias Bussonnier
|
r22788 | IPython, does this to display errors from multiple engines. | ||
Thomas Kluyver
|
r8083 | |||
Please be conservative in using this feature; by replacing the default traceback | ||||
you may hide important information from the user. | ||||