Show More
@@ -145,7 +145,7 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 `print`, for use in richer |
|
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. |
|
149 | frontends see Jupyter notebook examples with rich display logic. | |
150 |
|
150 | |||
151 | Parameters |
|
151 | Parameters | |
@@ -155,11 +155,11 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
155 | raw : bool, optional |
|
155 | raw : bool, optional | |
156 | 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, | |
157 | 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] | |
158 |
include : list |
|
158 | include : list, tuple or set, optional | |
159 | 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 | |
160 | 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 | |
161 | in this list will be computed. |
|
161 | in this list will be computed. | |
162 |
exclude : list |
|
162 | exclude : list, tuple or set, optional | |
163 | 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 | |
164 | 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, | |
165 | except for those included in this argument. |
|
165 | except for those included in this argument. | |
@@ -170,10 +170,10 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
170 | transient : dict, optional |
|
170 | transient : dict, optional | |
171 | A dictionary of transient data to associate with the output. |
|
171 | A dictionary of transient data to associate with the output. | |
172 | 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). | |
173 | display_id : str, optional |
|
173 | display_id : str, bool optional | |
174 | Set an id for the display. |
|
174 | Set an id for the display. | |
175 | 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. | |
176 | If given as True, generate a new display_id |
|
176 | If given as `True`, generate a new `display_id` | |
177 | kwargs: additional keyword-args, optional |
|
177 | kwargs: additional keyword-args, optional | |
178 | Additional keyword-arguments are passed through to the display publisher. |
|
178 | Additional keyword-arguments are passed through to the display publisher. | |
179 |
|
179 | |||
@@ -181,8 +181,9 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
181 | ------- |
|
181 | ------- | |
182 |
|
182 | |||
183 | handle: DisplayHandle |
|
183 | handle: DisplayHandle | |
184 |
Returns a handle on updatable displays |
|
184 | Returns a handle on updatable displays for use with :func:`update_display`, | |
185 | 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). | |||
186 |
|
187 | |||
187 | Examples |
|
188 | Examples | |
188 | -------- |
|
189 | -------- | |
@@ -226,7 +227,7 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
226 | See Also |
|
227 | See Also | |
227 | -------- |
|
228 | -------- | |
228 |
|
229 | |||
229 | `update_display` |
|
230 | :func:`update_display` | |
230 |
|
231 | |||
231 | Notes |
|
232 | Notes | |
232 | ----- |
|
233 | ----- | |
@@ -266,9 +267,12 b' def display(*objs, include=None, exclude=None, metadata=None, transient=None, di' | |||||
266 | You can refer to the documentation on IPython display formatters in order to |
|
267 | You can refer to the documentation on IPython display formatters in order to | |
267 | register custom formatters for already existing types. |
|
268 | register custom formatters for already existing types. | |
268 |
|
269 | |||
269 | Since IPython 5.4 and 6.1 display is automatically made available to the |
|
270 | .. versionadded:: 5.4 display available without import | |
270 | user without import. If you are using display in a document that might be |
|
271 | .. versionadded:: 6.1 display available without import | |
271 | used in a pure python context or with older version of IPython, use the |
|
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 | |||
272 | following import at the top of your file:: |
|
276 | following import at the top of your file:: | |
273 |
|
277 | |||
274 | from IPython.display import display |
|
278 | from IPython.display import display | |
@@ -318,6 +322,11 b' def update_display(obj, *, display_id, **kwargs):' | |||||
318 | The object with which to update the display |
|
322 | The object with which to update the display | |
319 | display_id: keyword-only |
|
323 | display_id: keyword-only | |
320 | The id of the display to update |
|
324 | The id of the display to update | |
|
325 | ||||
|
326 | See Also | |||
|
327 | -------- | |||
|
328 | ||||
|
329 | :func:`display` | |||
321 | """ |
|
330 | """ | |
322 | kwargs['update'] = True |
|
331 | kwargs['update'] = True | |
323 | display(obj, display_id=display_id, **kwargs) |
|
332 | display(obj, display_id=display_id, **kwargs) | |
@@ -326,10 +335,16 b' def update_display(obj, *, display_id, **kwargs):' | |||||
326 | class DisplayHandle(object): |
|
335 | class DisplayHandle(object): | |
327 | """A handle on an updatable display |
|
336 | """A handle on an updatable display | |
328 |
|
337 | |||
329 | Call .update(obj) to display a new object. |
|
338 | Call `.update(obj)` to display a new object. | |
330 |
|
339 | |||
331 | Call .display(obj) to add a new instance of this display, |
|
340 | Call `.display(obj`) to add a new instance of this display, | |
332 | and update existing instances. |
|
341 | and update existing instances. | |
|
342 | ||||
|
343 | See Also | |||
|
344 | -------- | |||
|
345 | ||||
|
346 | :func:`display`, :func:`update_display` | |||
|
347 | ||||
333 | """ |
|
348 | """ | |
334 |
|
349 | |||
335 | def __init__(self, display_id=None): |
|
350 | def __init__(self, display_id=None): |
@@ -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