##// END OF EJS Templates
Fix #9227: add documentation to integration tutorial
Fix #9227: add documentation to integration tutorial

File last commit:

r24620:19c262a9
r24620:19c262a9
Show More
integrating.rst
110 lines | 4.1 KiB | text/x-rst | RstLexer
Thomas Kluyver
Document ways of integrating objects with IPython.
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
built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_.
Thomas Kluyver
Document custom key completions
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
Cross-link rich display docs from display() docstring
r24041 .. _integrating_rich_display:
Thomas Kluyver
Document ways of integrating objects with IPython.
r8083 Rich display
============
The notebook and the Qt console can display richer representations of objects.
Zi Chong Kao
Document that _repr_*_() can return metadata...
r24307 To use this, you can define any of a number of ``_repr_*_()`` methods. Note that
Thomas Kluyver
Document ways of integrating objects with IPython.
r8083 these are surrounded by single, not double underscores.
Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg``
representations. The notebook can also display ``html``, ``javascript``,
Thomas Kluyver
Extend docs on customising object display
r24036 ``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it
falls back to a standard ``repr()``.
Thomas Kluyver
Document ways of integrating objects with IPython.
r8083
For example::
class Shout(object):
def __init__(self, text):
self.text = text
def _repr_html_(self):
return "<h1>" + self.text + "</h1>"
Zi Chong Kao
Document that _repr_*_() can return metadata
r24302 We often want to provide frontends with guidance on how to display the data. To
Zi Chong Kao
Document that _repr_*_() can return metadata...
r24307 support this, ``_repr_*_()`` methods 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.
Zi Chong Kao
Document that _repr_*_() can return metadata
r24302
Thomas Kluyver
Extend docs on customising object display
r24036 There are also two more powerful display 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*. 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.
Michael Penkov
Fix #9227: add documentation to integration tutorial
r24620 To customize how the REPL pretty-prints your object, 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, see :py:mod:`IPython.lib.pretty`.
Thomas Kluyver
Extend docs on customising object display
r24036 Formatters for third-party types
--------------------------------
The user can also register formatters for types without modifying the class::
from bar import Foo
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:
html_formatter.for_type_by_name('bar.Foo', foo_html)
Thomas Kluyver
Document ways of integrating objects with IPython.
r8083 Custom exception tracebacks
===========================
Matthias Bussonnier
Remove most of the ipyparallel info in the documentation.
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
<http://ipyparallel.readthedocs.io/>`__ a parallel computing framework for
IPython, does this to display errors from multiple engines.
Thomas Kluyver
Document ways of integrating objects with IPython.
r8083
Please be conservative in using this feature; by replacing the default traceback
you may hide important information from the user.