Skip to content

Backport PR #19863 on branch v3.4.x (Cleanup docstrings related to interactive mode) #19877

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 7, 2021
Merged

Backport PR #19863 on branch v3.4.x (Cleanup docstrings related to interactive mode) #19877

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions doc/devel/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -354,9 +354,7 @@ The definition of the pylab text function is a simple pass-through to

# in pylab.py
def text(*args, **kwargs):
ret = gca().text(*args, **kwargs)
draw_if_interactive()
return ret
return gca().text(*args, **kwargs)

`~matplotlib.axes.Axes.text` in simplified form looks like this, i.e., it just
passes all ``args`` and ``kwargs`` on to ``matplotlib.text.Text.__init__``::
Expand Down
9 changes: 8 additions & 1 deletion lib/matplotlib/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1112,7 +1112,14 @@ def interactive(b):


def is_interactive():
"""Return whether to redraw after every plotting command."""
"""
Return whether to redraw after every plotting command.

.. note::

This function is only intended for use in backends. End users should
use `.pyplot.isinteractive` instead.
"""
return rcParams['interactive']


Expand Down
57 changes: 35 additions & 22 deletions lib/matplotlib/pyplot.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,14 @@ def new_figure_manager(*args, **kwargs):

# This function's signature is rewritten upon backend-load by switch_backend.
def draw_if_interactive(*args, **kwargs):
"""
Redraw the current figure if in interactive mode.

.. warning::

End users will typically not have to call this function because the
the interactive mode takes care of this.
"""
return _backend_mod.draw_if_interactive(*args, **kwargs)


Expand Down Expand Up @@ -356,27 +364,30 @@ def show(*args, **kwargs):

def isinteractive():
"""
Return if pyplot is in "interactive mode" or not.
Return whether plots are updated after every plotting command.

The interactive mode is mainly useful if you build plots from the command
line and want to see the effect of each command while you are building the
figure.

If in interactive mode then:
In interactive mode:

- newly created figures will be shown immediately;
- figures will automatically redraw on change;
- `.pyplot.show` will not block by default.

If not in interactive mode then:
In non-interactive mode:

- newly created figures and changes to figures will not be reflected until
explicitly asked to be;
- `.pyplot.show` will block by default.

See Also
--------
ion : enable interactive mode
ioff : disable interactive mode

show : show windows (and maybe block)
pause : show windows, run GUI event loop, and block for a time
ion : Enable interactive mode.
ioff : Disable interactive mode.
show : Show all figures (and maybe block).
pause : Show all figures, and block for a time.
"""
return matplotlib.is_interactive()

Expand Down Expand Up @@ -435,15 +446,16 @@ def __exit__(self, exc_type, exc_value, traceback):

def ioff():
"""
Turn interactive mode off.
Disable interactive mode.

See `.pyplot.isinteractive` for more details.

See Also
--------
ion : enable interactive mode
isinteractive : query current state

show : show windows (and maybe block)
pause : show windows, run GUI event loop, and block for a time
ion : Enable interactive mode.
isinteractive : Whether interactive mode is enabled.
show : Show all figures (and maybe block).
pause : Show all figures, and block for a time.

Notes
-----
Expand All @@ -470,15 +482,16 @@ def ioff():

def ion():
"""
Turn interactive mode on.
Enable interactive mode.

See `.pyplot.isinteractive` for more details.

See Also
--------
ioff : disable interactive mode
isinteractive : query current state

show : show windows (and maybe block)
pause : show windows, run GUI event loop, and block for a time
ioff : Disable interactive mode.
isinteractive : Whether interactive mode is enabled.
show : Show all figures (and maybe block).
pause : Show all figures, and block for a time.

Notes
-----
Expand Down Expand Up @@ -517,8 +530,8 @@ def pause(interval):

See Also
--------
matplotlib.animation : Complex animation
show : show figures and optional block forever
matplotlib.animation : Proper animations
show : Show all figures and optional block until all figures are closed.
"""
manager = _pylab_helpers.Gcf.get_active()
if manager is not None:
Expand Down