Show More
@@ -145,6 +145,9 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
145 | By default all representations will be computed and sent to the frontends. |
|
145 | By default all representations will be computed and sent to the frontends. | |
146 | Frontends can decide which representation is used and how. |
|
146 | Frontends can decide which representation is used and how. | |
147 |
|
147 | |||
|
148 | In terminal IPython this will be similar to using :func:`print`, for use in richer | |||
|
149 | frontends see Jupyter notebook examples with rich display logic. | |||
|
150 | ||||
148 | Parameters |
|
151 | Parameters | |
149 | ---------- |
|
152 | ---------- | |
150 | objs : tuple of objects |
|
153 | objs : tuple of objects | |
@@ -152,11 +155,11 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
152 | raw : bool, optional |
|
155 | raw : bool, optional | |
153 | Are the objects to be displayed already mimetype-keyed dicts of raw display data, |
|
156 | Are the objects to be displayed already mimetype-keyed dicts of raw display data, | |
154 | or Python objects that need to be formatted before display? [default: False] |
|
157 | or Python objects that need to be formatted before display? [default: False] | |
155 |
include : list |
|
158 | include : list, tuple or set, optional | |
156 | A list of format type strings (MIME types) to include in the |
|
159 | A list of format type strings (MIME types) to include in the | |
157 | format data dict. If this is set *only* the format types included |
|
160 | format data dict. If this is set *only* the format types included | |
158 | in this list will be computed. |
|
161 | in this list will be computed. | |
159 |
exclude : list |
|
162 | exclude : list, tuple or set, optional | |
160 | A list of format type strings (MIME types) to exclude in the format |
|
163 | A list of format type strings (MIME types) to exclude in the format | |
161 | data dict. If this is set all format types will be computed, |
|
164 | data dict. If this is set all format types will be computed, | |
162 | except for those included in this argument. |
|
165 | except for those included in this argument. | |
@@ -167,25 +170,119 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
167 | transient : dict, optional |
|
170 | transient : dict, optional | |
168 | A dictionary of transient data to associate with the output. |
|
171 | A dictionary of transient data to associate with the output. | |
169 | Data in this dict should not be persisted to files (e.g. notebooks). |
|
172 | Data in this dict should not be persisted to files (e.g. notebooks). | |
170 | display_id : str, optional |
|
173 | display_id : str, bool optional | |
171 | Set an id for the display. |
|
174 | Set an id for the display. | |
172 | This id can be used for updating this display area later via update_display. |
|
175 | This id can be used for updating this display area later via update_display. | |
173 | If given as True, generate a new display_id |
|
176 | If given as `True`, generate a new `display_id` | |
174 | kwargs: additional keyword-args, optional |
|
177 | kwargs: additional keyword-args, optional | |
175 | Additional keyword-arguments are passed through to the display publisher. |
|
178 | Additional keyword-arguments are passed through to the display publisher. | |
176 |
|
179 | |||
177 | Returns |
|
180 | Returns | |
178 | ------- |
|
181 | ------- | |
179 |
|
182 | |||
180 | handle: DisplayHandle |
|
183 | handle: DisplayHandle | |
181 |
Returns a handle on updatable displays |
|
184 | Returns a handle on updatable displays for use with :func:`update_display`, | |
182 | Returns None if no display_id is given (default). |
|
185 | if `display_id` is given. Returns :any:`None` if no `display_id` is given | |
|
186 | (default). | |||
|
187 | ||||
|
188 | Examples | |||
|
189 | -------- | |||
|
190 | ||||
|
191 | >>> class Json(object): | |||
|
192 | ... def __init__(self, json): | |||
|
193 | ... self.json = json | |||
|
194 | ... def _repr_pretty_(self, pp, cycle): | |||
|
195 | ... import json | |||
|
196 | ... pp.text(json.dumps(self.json, indent=2)) | |||
|
197 | ... def __repr__(self): | |||
|
198 | ... return str(self.json) | |||
|
199 | ... | |||
|
200 | ||||
|
201 | >>> d = Json({1:2, 3: {4:5}}) | |||
|
202 | ||||
|
203 | >>> print(d) | |||
|
204 | {1: 2, 3: {4: 5}} | |||
|
205 | ||||
|
206 | >>> display(d) | |||
|
207 | { | |||
|
208 | "1": 2, | |||
|
209 | "3": { | |||
|
210 | "4": 5 | |||
|
211 | } | |||
|
212 | } | |||
|
213 | ||||
|
214 | >>> def int_formatter(integer, pp, cycle): | |||
|
215 | ... pp.text('I'*integer) | |||
|
216 | ||||
|
217 | >>> plain = get_ipython().display_formatter.formatters['text/plain'] | |||
|
218 | >>> plain.for_type(int, int_formatter) | |||
|
219 | <function _repr_pprint at 0x...> | |||
|
220 | >>> display(7-5) | |||
|
221 | II | |||
|
222 | ||||
|
223 | >>> del plain.type_printers[int] | |||
|
224 | >>> display(7-5) | |||
|
225 | 2 | |||
|
226 | ||||
|
227 | See Also | |||
|
228 | -------- | |||
|
229 | ||||
|
230 | :func:`update_display` | |||
|
231 | ||||
|
232 | Notes | |||
|
233 | ----- | |||
|
234 | ||||
|
235 | In Python, objects can declare their textual representation using the | |||
|
236 | `__repr__` method. IPython expands on this idea and allows objects to declare | |||
|
237 | other, rich representations including: | |||
|
238 | ||||
|
239 | - HTML | |||
|
240 | - JSON | |||
|
241 | - PNG | |||
|
242 | - JPEG | |||
|
243 | - SVG | |||
|
244 | - LaTeX | |||
|
245 | ||||
|
246 | A single object can declare some or all of these representations; all are | |||
|
247 | handled by IPython's display system. | |||
|
248 | ||||
|
249 | The main idea of the first approach is that you have to implement special | |||
|
250 | display methods when you define your class, one for each representation you | |||
|
251 | want to use. Here is a list of the names of the special methods and the | |||
|
252 | values they must return: | |||
|
253 | ||||
|
254 | - `_repr_html_`: return raw HTML as a string | |||
|
255 | - `_repr_json_`: return a JSONable dict | |||
|
256 | - `_repr_jpeg_`: return raw JPEG data | |||
|
257 | - `_repr_png_`: return raw PNG data | |||
|
258 | - `_repr_svg_`: return raw SVG data as a string | |||
|
259 | - `_repr_latex_`: return LaTeX commands in a string surrounded by "$". | |||
|
260 | - `_repr_mimebundle_`: return a full mimebundle containing the mapping | |||
|
261 | from all mimetypes to data | |||
|
262 | ||||
|
263 | When you are directly writing your own classes, you can adapt them for | |||
|
264 | display in IPython by following the above approach. But in practice, you | |||
|
265 | often need to work with existing classes that you can't easily modify. | |||
|
266 | ||||
|
267 | You can refer to the documentation on IPython display formatters in order to | |||
|
268 | register custom formatters for already existing types. | |||
|
269 | ||||
|
270 | .. versionadded:: 5.4 display available without import | |||
|
271 | .. versionadded:: 6.1 display available without import | |||
|
272 | ||||
|
273 | Since IPython 5.4 and 6.1 :func:`display` is automatically made available to | |||
|
274 | the user without import. If you are using display in a document that might | |||
|
275 | be used in a pure python context or with older version of IPython, use the | |||
|
276 | following import at the top of your file:: | |||
|
277 | ||||
|
278 | from IPython.display import display | |||
|
279 | ||||
183 | """ |
|
280 | """ | |
184 | raw = kwargs.pop('raw', False) |
|
281 | raw = kwargs.pop('raw', False) | |
185 | if transient is None: |
|
282 | if transient is None: | |
186 | transient = {} |
|
283 | transient = {} | |
187 | if display_id: |
|
284 | if display_id: | |
188 |
if display_id |
|
285 | if display_id is True: | |
189 | display_id = _new_id() |
|
286 | display_id = _new_id() | |
190 | transient['display_id'] = display_id |
|
287 | transient['display_id'] = display_id | |
191 | if kwargs.get('update') and 'display_id' not in transient: |
|
288 | if kwargs.get('update') and 'display_id' not in transient: | |
@@ -225,6 +322,11 b' def update_display(obj, *, display_id, **kwargs):' | |||||
225 | The object with which to update the display |
|
322 | The object with which to update the display | |
226 | display_id: keyword-only |
|
323 | display_id: keyword-only | |
227 | The id of the display to update |
|
324 | The id of the display to update | |
|
325 | ||||
|
326 | See Also | |||
|
327 | -------- | |||
|
328 | ||||
|
329 | :func:`display` | |||
228 | """ |
|
330 | """ | |
229 | kwargs['update'] = True |
|
331 | kwargs['update'] = True | |
230 | display(obj, display_id=display_id, **kwargs) |
|
332 | display(obj, display_id=display_id, **kwargs) | |
@@ -233,10 +335,16 b' def update_display(obj, *, display_id, **kwargs):' | |||||
233 | class DisplayHandle(object): |
|
335 | class DisplayHandle(object): | |
234 | """A handle on an updatable display |
|
336 | """A handle on an updatable display | |
235 |
|
337 | |||
236 | Call .update(obj) to display a new object. |
|
338 | Call `.update(obj)` to display a new object. | |
237 |
|
339 | |||
238 | Call .display(obj) to add a new instance of this display, |
|
340 | Call `.display(obj`) to add a new instance of this display, | |
239 | and update existing instances. |
|
341 | and update existing instances. | |
|
342 | ||||
|
343 | See Also | |||
|
344 | -------- | |||
|
345 | ||||
|
346 | :func:`display`, :func:`update_display` | |||
|
347 | ||||
240 | """ |
|
348 | """ | |
241 |
|
349 | |||
242 | def __init__(self, display_id=None): |
|
350 | def __init__(self, display_id=None): |
@@ -55,6 +55,7 b' from IPython.core.payload import PayloadManager' | |||||
55 | from IPython.core.prefilter import PrefilterManager |
|
55 | from IPython.core.prefilter import PrefilterManager | |
56 | from IPython.core.profiledir import ProfileDir |
|
56 | from IPython.core.profiledir import ProfileDir | |
57 | from IPython.core.usage import default_banner |
|
57 | from IPython.core.usage import default_banner | |
|
58 | from IPython.display import display | |||
58 | from IPython.testing.skipdoctest import skip_doctest |
|
59 | from IPython.testing.skipdoctest import skip_doctest | |
59 | from IPython.utils import PyColorize |
|
60 | from IPython.utils import PyColorize | |
60 | from IPython.utils import io |
|
61 | from IPython.utils import io | |
@@ -617,6 +618,7 b' class InteractiveShell(SingletonConfigurable):' | |||||
617 | # removing on exit or representing the existence of more than one |
|
618 | # removing on exit or representing the existence of more than one | |
618 | # IPython at a time. |
|
619 | # IPython at a time. | |
619 | builtin_mod.__dict__['__IPYTHON__'] = True |
|
620 | builtin_mod.__dict__['__IPYTHON__'] = True | |
|
621 | builtin_mod.__dict__['display'] = display | |||
620 |
|
622 | |||
621 | self.builtin_trap = BuiltinTrap(shell=self) |
|
623 | self.builtin_trap = BuiltinTrap(shell=self) | |
622 |
|
624 |
@@ -13,6 +13,7 b' from IPython.core import display' | |||||
13 | from IPython.core.getipython import get_ipython |
|
13 | from IPython.core.getipython import get_ipython | |
14 | from IPython.utils.tempdir import NamedFileInTemporaryDirectory |
|
14 | from IPython.utils.tempdir import NamedFileInTemporaryDirectory | |
15 | from IPython import paths as ipath |
|
15 | from IPython import paths as ipath | |
|
16 | from IPython.testing.tools import AssertPrints, AssertNotPrints | |||
16 |
|
17 | |||
17 | import IPython.testing.decorators as dec |
|
18 | import IPython.testing.decorators as dec | |
18 |
|
19 | |||
@@ -141,6 +142,25 b' def test_set_matplotlib_formats_kwargs():' | |||||
141 | expected.update(cfg.print_figure_kwargs) |
|
142 | expected.update(cfg.print_figure_kwargs) | |
142 | nt.assert_equal(cell, expected) |
|
143 | nt.assert_equal(cell, expected) | |
143 |
|
144 | |||
|
145 | def test_display_available(): | |||
|
146 | """ | |||
|
147 | Test that display is available without import | |||
|
148 | ||||
|
149 | We don't really care if it's in builtin or anything else, but it should | |||
|
150 | always be available. | |||
|
151 | """ | |||
|
152 | ip = get_ipython() | |||
|
153 | with AssertNotPrints('NameError'): | |||
|
154 | ip.run_cell('display') | |||
|
155 | try: | |||
|
156 | ip.run_cell('del display') | |||
|
157 | except NameError: | |||
|
158 | pass # it's ok, it might be in builtins | |||
|
159 | # even if deleted it should be back | |||
|
160 | with AssertNotPrints('NameError'): | |||
|
161 | ip.run_cell('display') | |||
|
162 | ||||
|
163 | ||||
144 | def test_displayobject_repr(): |
|
164 | def test_displayobject_repr(): | |
145 | h = display.HTML('<br />') |
|
165 | h = display.HTML('<br />') | |
146 | nt.assert_equal(repr(h), '<IPython.core.display.HTML object>') |
|
166 | nt.assert_equal(repr(h), '<IPython.core.display.HTML object>') |
@@ -1,7 +1,32 b'' | |||||
1 | .. _plotting: |
|
1 | .. _plotting: | |
2 |
|
2 | |||
|
3 | Rich Outputs | |||
|
4 | ------------ | |||
|
5 | ||||
|
6 | One of the main feature of IPython when used as a kernel is its ability to | |||
|
7 | show rich output. This means that object that can be representing as image, | |||
|
8 | sounds, animation, (etc...) can be shown this way if the frontend support it. | |||
|
9 | ||||
|
10 | In order for this to be possible, you need to use the ``display()`` function, | |||
|
11 | that should be available by default on IPython 5.4+ and 6.1+, or that you can | |||
|
12 | import with ``from IPython.display import display``. Then use ``display(<your | |||
|
13 | object>)`` instead of ``print()``, and if possible your object will be displayed | |||
|
14 | with a richer representation. In the terminal of course, there wont be much | |||
|
15 | difference as object are most of the time represented by text, but in notebook | |||
|
16 | and similar interface you will get richer outputs. | |||
|
17 | ||||
|
18 | ||||
3 | Plotting |
|
19 | Plotting | |
4 | -------- |
|
20 | -------- | |
|
21 | ||||
|
22 | .. note:: | |||
|
23 | ||||
|
24 | Starting with IPython 5.0 and matplotlib 2.0 you can avoid the use of | |||
|
25 | IPython's specific magic and use | |||
|
26 | ``matplotlib.pyplot.ion()``/``matplotlib.pyplot.ioff()`` which have the | |||
|
27 | advantages of working outside of IPython as well. | |||
|
28 | ||||
|
29 | ||||
5 | One major feature of the IPython kernel is the ability to display plots that |
|
30 | One major feature of the IPython kernel is the ability to display plots that | |
6 | are the output of running code cells. The IPython kernel is designed to work |
|
31 | are the output of running code cells. The IPython kernel is designed to work | |
7 | seamlessly with the matplotlib_ plotting library to provide this functionality. |
|
32 | seamlessly with the matplotlib_ plotting library to provide this functionality. |
@@ -53,6 +53,19 b' Implement display id and ability to update a given display. This should greatly' | |||||
53 | simplify a lot of code by removing the need for widgets and allow other frontend |
|
53 | simplify a lot of code by removing the need for widgets and allow other frontend | |
54 | to implement things like progress-bars. See :ghpull:`10048` |
|
54 | to implement things like progress-bars. See :ghpull:`10048` | |
55 |
|
55 | |||
|
56 | Display function | |||
|
57 | ---------------- | |||
|
58 | ||||
|
59 | The :func:`display() <IPython.display.display>` function is now available by | |||
|
60 | default in an IPython session, meaning users can call it on any object to see | |||
|
61 | their rich representation. This should allow for better interactivity both at | |||
|
62 | the REPL and in notebook environment. | |||
|
63 | ||||
|
64 | Scripts and library that rely on display and may be run outside of IPython still | |||
|
65 | need to import the display function using ``from IPython.display import | |||
|
66 | display``. See :ghpull:`10596` | |||
|
67 | ||||
|
68 | ||||
56 | Miscs |
|
69 | Miscs | |
57 | ----- |
|
70 | ----- | |
58 |
|
71 |
General Comments 0
You need to be logged in to leave comments.
Login now