##// END OF EJS Templates
Adjust %matplotlib docstring re: matplotlib_inline....
Antony Lee -
Show More
@@ -1,169 +1,169 b''
1 """Implementation of magic functions for matplotlib/pylab support.
1 """Implementation of magic functions for matplotlib/pylab support.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 # Our own packages
15 # Our own packages
16 from traitlets.config.application import Application
16 from traitlets.config.application import Application
17 from IPython.core import magic_arguments
17 from IPython.core import magic_arguments
18 from IPython.core.magic import Magics, magics_class, line_magic
18 from IPython.core.magic import Magics, magics_class, line_magic
19 from IPython.testing.skipdoctest import skip_doctest
19 from IPython.testing.skipdoctest import skip_doctest
20 from warnings import warn
20 from warnings import warn
21 from IPython.core.pylabtools import backends
21 from IPython.core.pylabtools import backends
22
22
23 #-----------------------------------------------------------------------------
23 #-----------------------------------------------------------------------------
24 # Magic implementation classes
24 # Magic implementation classes
25 #-----------------------------------------------------------------------------
25 #-----------------------------------------------------------------------------
26
26
27 magic_gui_arg = magic_arguments.argument(
27 magic_gui_arg = magic_arguments.argument(
28 'gui', nargs='?',
28 'gui', nargs='?',
29 help="""Name of the matplotlib backend to use %s.
29 help="""Name of the matplotlib backend to use %s.
30 If given, the corresponding matplotlib backend is used,
30 If given, the corresponding matplotlib backend is used,
31 otherwise it will be matplotlib's default
31 otherwise it will be matplotlib's default
32 (which you can set in your matplotlib config file).
32 (which you can set in your matplotlib config file).
33 """ % str(tuple(sorted(backends.keys())))
33 """ % str(tuple(sorted(backends.keys())))
34 )
34 )
35
35
36
36
37 @magics_class
37 @magics_class
38 class PylabMagics(Magics):
38 class PylabMagics(Magics):
39 """Magics related to matplotlib's pylab support"""
39 """Magics related to matplotlib's pylab support"""
40
40
41 @skip_doctest
41 @skip_doctest
42 @line_magic
42 @line_magic
43 @magic_arguments.magic_arguments()
43 @magic_arguments.magic_arguments()
44 @magic_arguments.argument('-l', '--list', action='store_true',
44 @magic_arguments.argument('-l', '--list', action='store_true',
45 help='Show available matplotlib backends')
45 help='Show available matplotlib backends')
46 @magic_gui_arg
46 @magic_gui_arg
47 def matplotlib(self, line=''):
47 def matplotlib(self, line=''):
48 """Set up matplotlib to work interactively.
48 """Set up matplotlib to work interactively.
49
49
50 This function lets you activate matplotlib interactive support
50 This function lets you activate matplotlib interactive support
51 at any point during an IPython session. It does not import anything
51 at any point during an IPython session. It does not import anything
52 into the interactive namespace.
52 into the interactive namespace.
53
53
54 If you are using the inline matplotlib backend in the IPython Notebook
54 If you are using the inline matplotlib backend in the IPython Notebook
55 you can set which figure formats are enabled using the following::
55 you can set which figure formats are enabled using the following::
56
56
57 In [1]: from IPython.display import set_matplotlib_formats
57 In [1]: from matplotlib_inline.backend_inline import set_matplotlib_formats
58
58
59 In [2]: set_matplotlib_formats('pdf', 'svg')
59 In [2]: set_matplotlib_formats('pdf', 'svg')
60
60
61 The default for inline figures sets `bbox_inches` to 'tight'. This can
61 The default for inline figures sets `bbox_inches` to 'tight'. This can
62 cause discrepancies between the displayed image and the identical
62 cause discrepancies between the displayed image and the identical
63 image created using `savefig`. This behavior can be disabled using the
63 image created using `savefig`. This behavior can be disabled using the
64 `%config` magic::
64 `%config` magic::
65
65
66 In [3]: %config InlineBackend.print_figure_kwargs = {'bbox_inches':None}
66 In [3]: %config InlineBackend.print_figure_kwargs = {'bbox_inches':None}
67
67
68 In addition, see the docstring of
68 In addition, see the docstrings of
69 `IPython.display.set_matplotlib_formats` and
69 `matplotlib_inline.backend_inline.set_matplotlib_formats` and
70 `IPython.display.set_matplotlib_close` for more information on
70 `matplotlib_inline.backend_inline.set_matplotlib_close` for more information on
71 changing additional behaviors of the inline backend.
71 changing additional behaviors of the inline backend.
72
72
73 Examples
73 Examples
74 --------
74 --------
75 To enable the inline backend for usage with the IPython Notebook::
75 To enable the inline backend for usage with the IPython Notebook::
76
76
77 In [1]: %matplotlib inline
77 In [1]: %matplotlib inline
78
78
79 In this case, where the matplotlib default is TkAgg::
79 In this case, where the matplotlib default is TkAgg::
80
80
81 In [2]: %matplotlib
81 In [2]: %matplotlib
82 Using matplotlib backend: TkAgg
82 Using matplotlib backend: TkAgg
83
83
84 But you can explicitly request a different GUI backend::
84 But you can explicitly request a different GUI backend::
85
85
86 In [3]: %matplotlib qt
86 In [3]: %matplotlib qt
87
87
88 You can list the available backends using the -l/--list option::
88 You can list the available backends using the -l/--list option::
89
89
90 In [4]: %matplotlib --list
90 In [4]: %matplotlib --list
91 Available matplotlib backends: ['osx', 'qt4', 'qt5', 'gtk3', 'gtk4', 'notebook', 'wx', 'qt', 'nbagg',
91 Available matplotlib backends: ['osx', 'qt4', 'qt5', 'gtk3', 'gtk4', 'notebook', 'wx', 'qt', 'nbagg',
92 'gtk', 'tk', 'inline']
92 'gtk', 'tk', 'inline']
93 """
93 """
94 args = magic_arguments.parse_argstring(self.matplotlib, line)
94 args = magic_arguments.parse_argstring(self.matplotlib, line)
95 if args.list:
95 if args.list:
96 backends_list = list(backends.keys())
96 backends_list = list(backends.keys())
97 print("Available matplotlib backends: %s" % backends_list)
97 print("Available matplotlib backends: %s" % backends_list)
98 else:
98 else:
99 gui, backend = self.shell.enable_matplotlib(args.gui.lower() if isinstance(args.gui, str) else args.gui)
99 gui, backend = self.shell.enable_matplotlib(args.gui.lower() if isinstance(args.gui, str) else args.gui)
100 self._show_matplotlib_backend(args.gui, backend)
100 self._show_matplotlib_backend(args.gui, backend)
101
101
102 @skip_doctest
102 @skip_doctest
103 @line_magic
103 @line_magic
104 @magic_arguments.magic_arguments()
104 @magic_arguments.magic_arguments()
105 @magic_arguments.argument(
105 @magic_arguments.argument(
106 '--no-import-all', action='store_true', default=None,
106 '--no-import-all', action='store_true', default=None,
107 help="""Prevent IPython from performing ``import *`` into the interactive namespace.
107 help="""Prevent IPython from performing ``import *`` into the interactive namespace.
108
108
109 You can govern the default behavior of this flag with the
109 You can govern the default behavior of this flag with the
110 InteractiveShellApp.pylab_import_all configurable.
110 InteractiveShellApp.pylab_import_all configurable.
111 """
111 """
112 )
112 )
113 @magic_gui_arg
113 @magic_gui_arg
114 def pylab(self, line=''):
114 def pylab(self, line=''):
115 """Load numpy and matplotlib to work interactively.
115 """Load numpy and matplotlib to work interactively.
116
116
117 This function lets you activate pylab (matplotlib, numpy and
117 This function lets you activate pylab (matplotlib, numpy and
118 interactive support) at any point during an IPython session.
118 interactive support) at any point during an IPython session.
119
119
120 %pylab makes the following imports::
120 %pylab makes the following imports::
121
121
122 import numpy
122 import numpy
123 import matplotlib
123 import matplotlib
124 from matplotlib import pylab, mlab, pyplot
124 from matplotlib import pylab, mlab, pyplot
125 np = numpy
125 np = numpy
126 plt = pyplot
126 plt = pyplot
127
127
128 from IPython.display import display
128 from IPython.display import display
129 from IPython.core.pylabtools import figsize, getfigs
129 from IPython.core.pylabtools import figsize, getfigs
130
130
131 from pylab import *
131 from pylab import *
132 from numpy import *
132 from numpy import *
133
133
134 If you pass `--no-import-all`, the last two `*` imports will be excluded.
134 If you pass `--no-import-all`, the last two `*` imports will be excluded.
135
135
136 See the %matplotlib magic for more details about activating matplotlib
136 See the %matplotlib magic for more details about activating matplotlib
137 without affecting the interactive namespace.
137 without affecting the interactive namespace.
138 """
138 """
139 args = magic_arguments.parse_argstring(self.pylab, line)
139 args = magic_arguments.parse_argstring(self.pylab, line)
140 if args.no_import_all is None:
140 if args.no_import_all is None:
141 # get default from Application
141 # get default from Application
142 if Application.initialized():
142 if Application.initialized():
143 app = Application.instance()
143 app = Application.instance()
144 try:
144 try:
145 import_all = app.pylab_import_all
145 import_all = app.pylab_import_all
146 except AttributeError:
146 except AttributeError:
147 import_all = True
147 import_all = True
148 else:
148 else:
149 # nothing specified, no app - default True
149 # nothing specified, no app - default True
150 import_all = True
150 import_all = True
151 else:
151 else:
152 # invert no-import flag
152 # invert no-import flag
153 import_all = not args.no_import_all
153 import_all = not args.no_import_all
154
154
155 gui, backend, clobbered = self.shell.enable_pylab(args.gui, import_all=import_all)
155 gui, backend, clobbered = self.shell.enable_pylab(args.gui, import_all=import_all)
156 self._show_matplotlib_backend(args.gui, backend)
156 self._show_matplotlib_backend(args.gui, backend)
157 print(
157 print(
158 "%pylab is deprecated, use %matplotlib inline and import the required libraries."
158 "%pylab is deprecated, use %matplotlib inline and import the required libraries."
159 )
159 )
160 print("Populating the interactive namespace from numpy and matplotlib")
160 print("Populating the interactive namespace from numpy and matplotlib")
161 if clobbered:
161 if clobbered:
162 warn("pylab import has clobbered these variables: %s" % clobbered +
162 warn("pylab import has clobbered these variables: %s" % clobbered +
163 "\n`%matplotlib` prevents importing * from pylab and numpy"
163 "\n`%matplotlib` prevents importing * from pylab and numpy"
164 )
164 )
165
165
166 def _show_matplotlib_backend(self, gui, backend):
166 def _show_matplotlib_backend(self, gui, backend):
167 """show matplotlib message backend message"""
167 """show matplotlib message backend message"""
168 if not gui or gui == 'auto':
168 if not gui or gui == 'auto':
169 print("Using matplotlib backend: %s" % backend)
169 print("Using matplotlib backend: %s" % backend)
General Comments 0
You need to be logged in to leave comments. Login now