From 1dc063dbc79d60a0ebd96ee6b4fa4ed537540f13 2017-05-29 02:38:16 From: Matthias Bussonnier Date: 2017-05-29 02:38:16 Subject: [PATCH] Document that display is there by default --- diff --git a/IPython/core/display.py b/IPython/core/display.py index a75fd05..96015de 100644 --- a/IPython/core/display.py +++ b/IPython/core/display.py @@ -145,7 +145,7 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di By default all representations will be computed and sent to the frontends. Frontends can decide which representation is used and how. - In terminal IPython this will be similar to using `print`, for use in richer + In terminal IPython this will be similar to using :func:`print`, for use in richer frontends see Jupyter notebook examples with rich display logic. Parameters @@ -155,11 +155,11 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di raw : bool, optional Are the objects to be displayed already mimetype-keyed dicts of raw display data, or Python objects that need to be formatted before display? [default: False] - include : list or tuple, optional + include : list, tuple or set, optional A list of format type strings (MIME types) to include in the format data dict. If this is set *only* the format types included in this list will be computed. - exclude : list or tuple, optional + exclude : list, tuple or set, optional A list of format type strings (MIME types) to exclude in the format data dict. If this is set all format types will be computed, except for those included in this argument. @@ -170,10 +170,10 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di transient : dict, optional A dictionary of transient data to associate with the output. Data in this dict should not be persisted to files (e.g. notebooks). - display_id : str, optional + display_id : str, bool optional Set an id for the display. This id can be used for updating this display area later via update_display. - If given as True, generate a new display_id + If given as `True`, generate a new `display_id` kwargs: additional keyword-args, optional Additional keyword-arguments are passed through to the display publisher. @@ -181,8 +181,9 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di ------- handle: DisplayHandle - Returns a handle on updatable displays, if display_id is given. - Returns None if no display_id is given (default). + Returns a handle on updatable displays for use with :func:`update_display`, + if `display_id` is given. Returns :any:`None` if no `display_id` is given + (default). Examples -------- @@ -226,7 +227,7 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di See Also -------- - `update_display` + :func:`update_display` Notes ----- @@ -266,9 +267,12 @@ def display(*objs, include=None, exclude=None, metadata=None, transient=None, di You can refer to the documentation on IPython display formatters in order to register custom formatters for already existing types. - Since IPython 5.4 and 6.1 display is automatically made available to the - user without import. If you are using display in a document that might be - used in a pure python context or with older version of IPython, use the + .. versionadded:: 5.4 display available without import + .. versionadded:: 6.1 display available without import + + Since IPython 5.4 and 6.1 :func:`display` is automatically made available to + the user without import. If you are using display in a document that might + be used in a pure python context or with older version of IPython, use the following import at the top of your file:: from IPython.display import display @@ -318,6 +322,11 @@ def update_display(obj, *, display_id, **kwargs): The object with which to update the display display_id: keyword-only The id of the display to update + + See Also + -------- + + :func:`display` """ kwargs['update'] = True display(obj, display_id=display_id, **kwargs) @@ -326,10 +335,16 @@ def update_display(obj, *, display_id, **kwargs): class DisplayHandle(object): """A handle on an updatable display - Call .update(obj) to display a new object. + Call `.update(obj)` to display a new object. - Call .display(obj) to add a new instance of this display, + Call `.display(obj`) to add a new instance of this display, and update existing instances. + + See Also + -------- + + :func:`display`, :func:`update_display` + """ def __init__(self, display_id=None): diff --git a/docs/source/interactive/plotting.rst b/docs/source/interactive/plotting.rst index 8d243d8..2bf67b4 100644 --- a/docs/source/interactive/plotting.rst +++ b/docs/source/interactive/plotting.rst @@ -1,7 +1,32 @@ .. _plotting: +Rich Outputs +------------ + +One of the main feature of IPython when used as a kernel is its ability to +show rich output. This means that object that can be representing as image, +sounds, animation, (etc...) can be shown this way if the frontend support it. + +In order for this to be possible, you need to use the ``display()`` function, +that should be available by default on IPython 5.4+ and 6.1+, or that you can +import with ``from IPython.display import display``. Then use ``display()`` instead of ``print()``, and if possible your object will be displayed +with a richer representation. In the terminal of course, there wont be much +difference as object are most of the time represented by text, but in notebook +and similar interface you will get richer outputs. + + Plotting -------- + +.. note:: + + Starting with IPython 5.0 and matplotlib 2.0 you can avoid the use of + IPython's specific magic and use + ``matplotlib.pyplot.ion()``/``matplotlib.pyplot.ioff()`` which have the + advantages of working outside of IPython as well. + + One major feature of the IPython kernel is the ability to display plots that are the output of running code cells. The IPython kernel is designed to work seamlessly with the matplotlib_ plotting library to provide this functionality. diff --git a/docs/source/whatsnew/version5.rst b/docs/source/whatsnew/version5.rst index 3a4169e..b11115e 100644 --- a/docs/source/whatsnew/version5.rst +++ b/docs/source/whatsnew/version5.rst @@ -53,6 +53,19 @@ Implement display id and ability to update a given display. This should greatly simplify a lot of code by removing the need for widgets and allow other frontend to implement things like progress-bars. See :ghpull:`10048` +Display function +---------------- + +The :func:`display() ` function is now available by +default in an IPython session, meaning users can call it on any object to see +their rich representation. This should allow for better interactivity both at +the REPL and in notebook environment. + +Scripts and library that rely on display and may be run outside of IPython still +need to import the display function using ``from IPython.display import +display``. See :ghpull:`10596` + + Miscs -----