##// END OF EJS Templates
back to dev
back to dev

File last commit:

r27637:9f3065cb
r27898:3f0bf05f
Show More
integrating.rst
173 lines | 4.8 KiB | text/x-rst | RstLexer

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].

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.

Supported _repr_*_ methods
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 "<h1>" + self.text + "</h1>"

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

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 '<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.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.