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