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 thebuilt-indir()
You can also customise key completions for your objects, e.g. pressing tab afterobj["a. To do so, define a method_ipython_key_completions_(), whichreturns a list of objects which are possible keys in a subscript expressionobj[key].
Added in version 5.0:Custom key completions
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.
Format | REPL | Notebook | Qt Console |
|---|---|---|---|
| yes | yes | yes |
| no | yes | yes |
| no | yes | yes |
| no | yes | yes |
| no | yes | no |
| no | yes | no |
| no | yes | no |
| no | yes | no |
| no | ? | ? |
If the methods don’t exist, the standardrepr() is used.If a method exists and returnsNone, 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 theDisplayFormatter, or configuration.
_repr_*_ methods shouldreturn data of the expected format and have no side effects.For example,_repr_html_ should return HTML as astr and_repr_png_ should return PNG data asbytes.
If you wish to take control of display via your own side effects, use_ipython_display_().
For example:
classShout(object):def__init__(self,text):self.text=textdef_repr_html_(self):return"<h1>"+self.text+"</h1>"
Special methods
Pretty printing
To customize how your object is pretty-printed, add a_repr_pretty_ methodto the class.The method should accept a pretty printer, and a boolean that indicates whetherthe printer detected a cycle.The method should act on the printer to produce your customized pretty output.Here is an example:
classMyObject(object):def_repr_pretty_(self,p,cycle):ifcycle:p.text('MyObject(...)')else:p.text('MyObject[...]')
For details on how to use the pretty printer, seeIPython.lib.pretty.
More powerful methods
- classMyObject
- _repr_mimebundle_(include=None,exclude=None)
Should return a dictionary of multiple formats, keyed by mimetype, or a tupleof two dictionaries:data, metadata (seeDistribution metadata).If this returns something, other
_repr_*_methods are ignored.The method should take keyword argumentsincludeandexclude, thoughit is not required to respect them.
- _ipython_display_()
Displays the object as a side effect; the return value is ignored. If thisis defined, all other display methods are ignored.
Metadata
We often want to provide frontends with guidance on how to display the data. Tosupport this,_repr_*_() methods (except_repr_pretty_?) can also return a(data,metadata)tuple wheremetadata is a dictionary containing arbitrary key-value pairs forthe frontend to interpret. An example use case is_repr_jpeg_(), which canbe set to return a jpeg image and a{'height':400,'width':600} dictionaryto 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:
frombar.bazimportFoodeffoo_html(obj):return'<marquee>Foo object%s</marquee>'%obj.namehtml_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 anexception. To do this, define the custom traceback using_render_traceback_(self) method which returns a list of strings, one stringfor each line of the traceback. For example, theipyparallel a parallel computing framework forIPython, does this to display errors from multiple engines.
Please be conservative in using this feature; by replacing the default tracebackyou may hide important information from the user.