Show More
@@ -1,173 +1,173 | |||
|
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 | Custom methods |
|
28 | 28 | ---------------------- |
|
29 | 29 | IPython can display richer representations of objects. |
|
30 | 30 | To do this, you can define ``_ipython_display_()``, or any of a number of |
|
31 | 31 | ``_repr_*_()`` methods. |
|
32 | 32 | Note that these are surrounded by single, not double underscores. |
|
33 | 33 | |
|
34 | 34 | .. list-table:: Supported ``_repr_*_`` methods |
|
35 | 35 | :widths: 20 15 15 15 |
|
36 | 36 | :header-rows: 1 |
|
37 | 37 | |
|
38 | 38 | * - Format |
|
39 | 39 | - REPL |
|
40 | 40 | - Notebook |
|
41 | 41 | - Qt Console |
|
42 | 42 | * - ``_repr_pretty_`` |
|
43 | 43 | - yes |
|
44 | 44 | - yes |
|
45 | 45 | - yes |
|
46 | 46 | * - ``_repr_svg_`` |
|
47 | 47 | - no |
|
48 | 48 | - yes |
|
49 | 49 | - yes |
|
50 | 50 | * - ``_repr_png_`` |
|
51 | 51 | - no |
|
52 | 52 | - yes |
|
53 | 53 | - yes |
|
54 | 54 | * - ``_repr_jpeg_`` |
|
55 | 55 | - no |
|
56 | 56 | - yes |
|
57 | 57 | - yes |
|
58 | 58 | * - ``_repr_html_`` |
|
59 | 59 | - no |
|
60 | 60 | - yes |
|
61 | 61 | - no |
|
62 | 62 | * - ``_repr_javascript_`` |
|
63 | 63 | - no |
|
64 | 64 | - yes |
|
65 | 65 | - no |
|
66 | 66 | * - ``_repr_markdown_`` |
|
67 | 67 | - no |
|
68 | 68 | - yes |
|
69 | 69 | - no |
|
70 | 70 | * - ``_repr_latex_`` |
|
71 | 71 | - no |
|
72 | 72 | - yes |
|
73 | 73 | - no |
|
74 | 74 | * - ``_repr_mimebundle_`` |
|
75 | 75 | - no |
|
76 | 76 | - ? |
|
77 | 77 | - ? |
|
78 | 78 | |
|
79 | 79 | If the methods don't exist, or return ``None``, the standard ``repr()`` is used. |
|
80 | 80 | |
|
81 | 81 | For example:: |
|
82 | 82 | |
|
83 | 83 | class Shout(object): |
|
84 | 84 | def __init__(self, text): |
|
85 | 85 | self.text = text |
|
86 | 86 | |
|
87 | 87 | def _repr_html_(self): |
|
88 | 88 | return "<h1>" + self.text + "</h1>" |
|
89 | 89 | |
|
90 | 90 | |
|
91 | 91 | Special methods |
|
92 | 92 | ^^^^^^^^^^^^^^^ |
|
93 | 93 | |
|
94 | 94 | Pretty printing |
|
95 | 95 | """"""""""""""" |
|
96 | 96 | |
|
97 | To customize how your object is pretty-printed, add a `_repr_pretty_` method | |
|
97 | To customize how your object is pretty-printed, add a ``_repr_pretty_`` method | |
|
98 | 98 | to the class. |
|
99 | 99 | The method should accept a pretty printer, and a boolean that indicates whether |
|
100 | 100 | the printer detected a cycle. |
|
101 | 101 | The method should act on the printer to produce your customized pretty output. |
|
102 | 102 | Here is an example:: |
|
103 | 103 | |
|
104 | 104 | class MyObject(object): |
|
105 | 105 | |
|
106 | 106 | def _repr_pretty_(self, p, cycle): |
|
107 | 107 | if cycle: |
|
108 | 108 | p.text('MyObject(...)') |
|
109 | 109 | else: |
|
110 | 110 | p.text('MyObject[...]') |
|
111 | 111 | |
|
112 | 112 | For details on how to use the pretty printer, see :py:mod:`IPython.lib.pretty`. |
|
113 | 113 | |
|
114 | 114 | More powerful methods |
|
115 | 115 | """"""""""""""""""""" |
|
116 | 116 | |
|
117 | 117 | .. class:: MyObject |
|
118 | 118 | |
|
119 | 119 | .. method:: _repr_mimebundle_(include=None, exclude=None) |
|
120 | 120 | |
|
121 | 121 | Should return a dictionary of multiple formats, keyed by mimetype, or a tuple |
|
122 | 122 | of two dictionaries: *data, metadata* (see :ref:`Metadata`). |
|
123 | 123 | If this returns something, other ``_repr_*_`` methods are ignored. |
|
124 | 124 | The method should take keyword arguments ``include`` and ``exclude``, though |
|
125 | 125 | it is not required to respect them. |
|
126 | 126 | |
|
127 | 127 | .. method:: _ipython_display_() |
|
128 | 128 | |
|
129 | 129 | Displays the object as a side effect; the return value is ignored. If this |
|
130 | 130 | is defined, all other display methods are ignored. |
|
131 | 131 | This method is ignored in the REPL. |
|
132 | 132 | |
|
133 | 133 | |
|
134 | 134 | Metadata |
|
135 | 135 | ^^^^^^^^ |
|
136 | 136 | |
|
137 | 137 | We often want to provide frontends with guidance on how to display the data. To |
|
138 | 138 | support this, ``_repr_*_()`` methods (except `_repr_pretty_``?) can also return a ``(data, metadata)`` |
|
139 | 139 | tuple where ``metadata`` is a dictionary containing arbitrary key-value pairs for |
|
140 | 140 | the frontend to interpret. An example use case is ``_repr_jpeg_()``, which can |
|
141 | 141 | be set to return a jpeg image and a ``{'height': 400, 'width': 600}`` dictionary |
|
142 | 142 | to inform the frontend how to size the image. |
|
143 | 143 | |
|
144 | 144 | |
|
145 | 145 | |
|
146 | 146 | Formatters for third-party types |
|
147 | 147 | -------------------------------- |
|
148 | 148 | |
|
149 | 149 | The user can also register formatters for types without modifying the class:: |
|
150 | 150 | |
|
151 | 151 | from bar.baz import Foo |
|
152 | 152 | |
|
153 | 153 | def foo_html(obj): |
|
154 | 154 | return '<marquee>Foo object %s</marquee>' % obj.name |
|
155 | 155 | |
|
156 | 156 | html_formatter = get_ipython().display_formatter.formatters['text/html'] |
|
157 | 157 | html_formatter.for_type(Foo, foo_html) |
|
158 | 158 | |
|
159 | 159 | # Or register a type without importing it - this does the same as above: |
|
160 | 160 | html_formatter.for_type_by_name('bar.baz', 'Foo', foo_html) |
|
161 | 161 | |
|
162 | 162 | Custom exception tracebacks |
|
163 | 163 | =========================== |
|
164 | 164 | |
|
165 | 165 | Rarely, you might want to display a custom traceback when reporting an |
|
166 | 166 | exception. To do this, define the custom traceback using |
|
167 | 167 | `_render_traceback_(self)` method which returns a list of strings, one string |
|
168 | 168 | for each line of the traceback. For example, the `ipyparallel |
|
169 | 169 | <https://ipyparallel.readthedocs.io/>`__ a parallel computing framework for |
|
170 | 170 | IPython, does this to display errors from multiple engines. |
|
171 | 171 | |
|
172 | 172 | Please be conservative in using this feature; by replacing the default traceback |
|
173 | 173 | you may hide important information from the user. |
General Comments 0
You need to be logged in to leave comments.
Login now