Show More
@@ -1,95 +1,110 b'' | |||
|
1 | 1 | .. _integrating: |
|
2 | 2 | |
|
3 | 3 | ===================================== |
|
4 | 4 | Integrating your objects with IPython |
|
5 | 5 | ===================================== |
|
6 | 6 | |
|
7 | 7 | Tab completion |
|
8 | 8 | ============== |
|
9 | 9 | |
|
10 | 10 | To change the attributes displayed by tab-completing your object, define a |
|
11 | 11 | ``__dir__(self)`` method for it. For more details, see the documentation of the |
|
12 | 12 | built-in `dir() function <http://docs.python.org/library/functions.html#dir>`_. |
|
13 | 13 | |
|
14 | 14 | You can also customise key completions for your objects, e.g. pressing tab after |
|
15 | 15 | ``obj["a``. To do so, define a method ``_ipython_key_completions_()``, which |
|
16 | 16 | returns a list of objects which are possible keys in a subscript expression |
|
17 | 17 | ``obj[key]``. |
|
18 | 18 | |
|
19 | 19 | .. versionadded:: 5.0 |
|
20 | 20 | Custom key completions |
|
21 | 21 | |
|
22 | 22 | .. _integrating_rich_display: |
|
23 | 23 | |
|
24 | 24 | Rich display |
|
25 | 25 | ============ |
|
26 | 26 | |
|
27 | 27 | The notebook and the Qt console can display richer representations of objects. |
|
28 | 28 | To use this, you can define any of a number of ``_repr_*_()`` methods. Note that |
|
29 | 29 | these are surrounded by single, not double underscores. |
|
30 | 30 | |
|
31 | 31 | Both the notebook and the Qt console can display ``svg``, ``png`` and ``jpeg`` |
|
32 | 32 | representations. The notebook can also display ``html``, ``javascript``, |
|
33 | 33 | ``markdown`` and ``latex``. If the methods don't exist, or return ``None``, it |
|
34 | 34 | falls back to a standard ``repr()``. |
|
35 | 35 | |
|
36 | 36 | For example:: |
|
37 | 37 | |
|
38 | 38 | class Shout(object): |
|
39 | 39 | def __init__(self, text): |
|
40 | 40 | self.text = text |
|
41 | 41 | |
|
42 | 42 | def _repr_html_(self): |
|
43 | 43 | return "<h1>" + self.text + "</h1>" |
|
44 | 44 | |
|
45 | 45 | We often want to provide frontends with guidance on how to display the data. To |
|
46 | 46 | support this, ``_repr_*_()`` methods can also return a ``(data, metadata)`` |
|
47 | 47 | tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for |
|
48 | 48 | the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can |
|
49 | 49 | be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary |
|
50 | 50 | to inform the frontend how to size the image. |
|
51 | 51 | |
|
52 | 52 | There are also two more powerful display methods: |
|
53 | 53 | |
|
54 | 54 | .. class:: MyObject |
|
55 | 55 | |
|
56 | 56 | .. method:: _repr_mimebundle_(include=None, exclude=None) |
|
57 | 57 | |
|
58 | 58 | Should return a dictionary of multiple formats, keyed by mimetype, or a tuple |
|
59 | 59 | of two dictionaries: *data, metadata*. If this returns something, other |
|
60 | 60 | ``_repr_*_`` methods are ignored. The method should take keyword arguments |
|
61 | 61 | ``include`` and ``exclude``, though it is not required to respect them. |
|
62 | 62 | |
|
63 | 63 | .. method:: _ipython_display_() |
|
64 | 64 | |
|
65 | 65 | Displays the object as a side effect; the return value is ignored. If this |
|
66 | 66 | is defined, all other display methods are ignored. |
|
67 | 67 | |
|
68 | To customize how the REPL pretty-prints your object, add a `_repr_pretty_` | |
|
69 | method to the class. The method should accept a pretty printer, and a boolean | |
|
70 | that indicates whether the printer detected a cycle. The method should act on | |
|
71 | the printer to produce your customized pretty output. Here is an example:: | |
|
72 | ||
|
73 | class MyObject(object): | |
|
74 | ||
|
75 | def _repr_pretty_(self, p, cycle): | |
|
76 | if cycle: | |
|
77 | p.text('MyObject(...)') | |
|
78 | else: | |
|
79 | p.text('MyObject[...]') | |
|
80 | ||
|
81 | For details, see :py:mod:`IPython.lib.pretty`. | |
|
82 | ||
|
68 | 83 | Formatters for third-party types |
|
69 | 84 | -------------------------------- |
|
70 | 85 | |
|
71 | 86 | The user can also register formatters for types without modifying the class:: |
|
72 | 87 | |
|
73 | 88 | from bar import Foo |
|
74 | 89 | |
|
75 | 90 | def foo_html(obj): |
|
76 | 91 | return '<marquee>Foo object %s</marquee>' % obj.name |
|
77 | 92 | |
|
78 | 93 | html_formatter = get_ipython().display_formatter.formatters['text/html'] |
|
79 | 94 | html_formatter.for_type(Foo, foo_html) |
|
80 | 95 | |
|
81 | 96 | # Or register a type without importing it - this does the same as above: |
|
82 | 97 | html_formatter.for_type_by_name('bar.Foo', foo_html) |
|
83 | 98 | |
|
84 | 99 | Custom exception tracebacks |
|
85 | 100 | =========================== |
|
86 | 101 | |
|
87 | 102 | Rarely, you might want to display a custom traceback when reporting an |
|
88 | 103 | exception. To do this, define the custom traceback using |
|
89 | 104 | `_render_traceback_(self)` method which returns a list of strings, one string |
|
90 | 105 | for each line of the traceback. For example, the `ipyparallel |
|
91 | 106 | <http://ipyparallel.readthedocs.io/>`__ a parallel computing framework for |
|
92 | 107 | IPython, does this to display errors from multiple engines. |
|
93 | 108 | |
|
94 | 109 | Please be conservative in using this feature; by replacing the default traceback |
|
95 | 110 | you may hide important information from the user. |
General Comments 0
You need to be logged in to leave comments.
Login now