@@ -230,24 +230,51 @@ def switch_backend(newbackend):
230230_backend_mod ,new_figure_manager ,draw_if_interactive ,_show = pylab_setup ()
231231
232232
233- def show (* args , ** kw ):
233+ def show (block = None ):
234234"""
235- Display a figure.
236- When running in ipython with its pylab mode, display all
237- figures and return to the ipython prompt.
235+ Draw and display all figures.
238236
239- In non-interactive mode, display all figures and block until
240- the figures have been closed; in interactive mode it has no
241- effect unless figures were created prior to a change from
242- non-interactive to interactive mode (not recommended). In
243- that case it displays the figures but does not block.
237+ Mainly used in non-interactive mode to draw and display
238+ the figures. It usually does nothing in interactive mode.
244239
245- A single experimental keyword argument, *block*, may be
246- set to True or False to override the blocking behavior
247- described above.
240+ Parameters
241+ ----------
242+
243+ block : bool or None
244+ True means that the execution is blocked until the figures are closed
245+ and False means that the python execution continues after the figures
246+ are displayed.
247+
248+ The default behavior is different in interactive and non-interactive
249+ mode and whether or not `%matplotlib`_ is used in IPython. The default
250+ is False in interactive mode and True in non-interactive mode except
251+ when `%matplotlib`_ has been used in IPython, it is False in that case.
252+
253+ Notes
254+ -----
255+ Blocking is necessary when running ``python script.py`` to be able to see
256+ the figures before the python session finish but blocking is often not the
257+ expected behavior when running Python interactively.
258+
259+ The difference between non-interactive and interactive mode is that the
260+ figures are drawn and updated automatically after each plot command in
261+ interactive mode.
262+
263+ Interactive mode can be set on and off with `.pyplot.ion` and
264+ `.pyplot.ioff` in both vanilla Python and IPython and set to on with
265+ `%matplotlib`_ in IPython.
266+
267+ .. _`%matplotlib`:
268+ http://ipython.readthedocs.io/en/stable/interactive/plotting.html#id1
269+
270+ See Also
271+ --------
272+ .pyplot.ion
273+ .pyplot.ioff
274+ .pyplot.isinteractive
248275 """
249276global _show
250- return _show (* args , ** kw )
277+ return _show (block = block )
251278
252279
253280def isinteractive ():