##// END OF EJS Templates
Make running PYTHONSTARTUP optional...
Thomas Kluyver -
Show More
@@ -1,419 +1,424 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 A mixin for :class:`~IPython.core.application.Application` classes that
3 A mixin for :class:`~IPython.core.application.Application` classes that
4 launch InteractiveShell instances, load extensions, etc.
4 launch InteractiveShell instances, load extensions, etc.
5
5
6 Authors
6 Authors
7 -------
7 -------
8
8
9 * Min Ragan-Kelley
9 * Min Ragan-Kelley
10 """
10 """
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Copyright (C) 2008-2011 The IPython Development Team
13 # Copyright (C) 2008-2011 The IPython Development Team
14 #
14 #
15 # Distributed under the terms of the BSD License. The full license is in
15 # Distributed under the terms of the BSD License. The full license is in
16 # the file COPYING, distributed as part of this software.
16 # the file COPYING, distributed as part of this software.
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18
18
19 #-----------------------------------------------------------------------------
19 #-----------------------------------------------------------------------------
20 # Imports
20 # Imports
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 from __future__ import absolute_import
23 from __future__ import absolute_import
24 from __future__ import print_function
24 from __future__ import print_function
25
25
26 import glob
26 import glob
27 import os
27 import os
28 import sys
28 import sys
29
29
30 from IPython.config.application import boolean_flag
30 from IPython.config.application import boolean_flag
31 from IPython.config.configurable import Configurable
31 from IPython.config.configurable import Configurable
32 from IPython.config.loader import Config
32 from IPython.config.loader import Config
33 from IPython.core import pylabtools
33 from IPython.core import pylabtools
34 from IPython.utils import py3compat
34 from IPython.utils import py3compat
35 from IPython.utils.contexts import preserve_keys
35 from IPython.utils.contexts import preserve_keys
36 from IPython.utils.path import filefind
36 from IPython.utils.path import filefind
37 from IPython.utils.traitlets import (
37 from IPython.utils.traitlets import (
38 Unicode, Instance, List, Bool, CaselessStrEnum, Dict
38 Unicode, Instance, List, Bool, CaselessStrEnum, Dict
39 )
39 )
40 from IPython.lib.inputhook import guis
40 from IPython.lib.inputhook import guis
41
41
42 #-----------------------------------------------------------------------------
42 #-----------------------------------------------------------------------------
43 # Aliases and Flags
43 # Aliases and Flags
44 #-----------------------------------------------------------------------------
44 #-----------------------------------------------------------------------------
45
45
46 gui_keys = tuple(sorted([ key for key in guis if key is not None ]))
46 gui_keys = tuple(sorted([ key for key in guis if key is not None ]))
47
47
48 backend_keys = sorted(pylabtools.backends.keys())
48 backend_keys = sorted(pylabtools.backends.keys())
49 backend_keys.insert(0, 'auto')
49 backend_keys.insert(0, 'auto')
50
50
51 shell_flags = {}
51 shell_flags = {}
52
52
53 addflag = lambda *args: shell_flags.update(boolean_flag(*args))
53 addflag = lambda *args: shell_flags.update(boolean_flag(*args))
54 addflag('autoindent', 'InteractiveShell.autoindent',
54 addflag('autoindent', 'InteractiveShell.autoindent',
55 'Turn on autoindenting.', 'Turn off autoindenting.'
55 'Turn on autoindenting.', 'Turn off autoindenting.'
56 )
56 )
57 addflag('automagic', 'InteractiveShell.automagic',
57 addflag('automagic', 'InteractiveShell.automagic',
58 """Turn on the auto calling of magic commands. Type %%magic at the
58 """Turn on the auto calling of magic commands. Type %%magic at the
59 IPython prompt for more information.""",
59 IPython prompt for more information.""",
60 'Turn off the auto calling of magic commands.'
60 'Turn off the auto calling of magic commands.'
61 )
61 )
62 addflag('pdb', 'InteractiveShell.pdb',
62 addflag('pdb', 'InteractiveShell.pdb',
63 "Enable auto calling the pdb debugger after every exception.",
63 "Enable auto calling the pdb debugger after every exception.",
64 "Disable auto calling the pdb debugger after every exception."
64 "Disable auto calling the pdb debugger after every exception."
65 )
65 )
66 # pydb flag doesn't do any config, as core.debugger switches on import,
66 # pydb flag doesn't do any config, as core.debugger switches on import,
67 # which is before parsing. This just allows the flag to be passed.
67 # which is before parsing. This just allows the flag to be passed.
68 shell_flags.update(dict(
68 shell_flags.update(dict(
69 pydb = ({},
69 pydb = ({},
70 """Use the third party 'pydb' package as debugger, instead of pdb.
70 """Use the third party 'pydb' package as debugger, instead of pdb.
71 Requires that pydb is installed."""
71 Requires that pydb is installed."""
72 )
72 )
73 ))
73 ))
74 addflag('pprint', 'PlainTextFormatter.pprint',
74 addflag('pprint', 'PlainTextFormatter.pprint',
75 "Enable auto pretty printing of results.",
75 "Enable auto pretty printing of results.",
76 "Disable auto pretty printing of results."
76 "Disable auto pretty printing of results."
77 )
77 )
78 addflag('color-info', 'InteractiveShell.color_info',
78 addflag('color-info', 'InteractiveShell.color_info',
79 """IPython can display information about objects via a set of func-
79 """IPython can display information about objects via a set of func-
80 tions, and optionally can use colors for this, syntax highlighting
80 tions, and optionally can use colors for this, syntax highlighting
81 source code and various other elements. However, because this
81 source code and various other elements. However, because this
82 information is passed through a pager (like 'less') and many pagers get
82 information is passed through a pager (like 'less') and many pagers get
83 confused with color codes, this option is off by default. You can test
83 confused with color codes, this option is off by default. You can test
84 it and turn it on permanently in your ipython_config.py file if it
84 it and turn it on permanently in your ipython_config.py file if it
85 works for you. Test it and turn it on permanently if it works with
85 works for you. Test it and turn it on permanently if it works with
86 your system. The magic function %%color_info allows you to toggle this
86 your system. The magic function %%color_info allows you to toggle this
87 interactively for testing.""",
87 interactively for testing.""",
88 "Disable using colors for info related things."
88 "Disable using colors for info related things."
89 )
89 )
90 addflag('deep-reload', 'InteractiveShell.deep_reload',
90 addflag('deep-reload', 'InteractiveShell.deep_reload',
91 """Enable deep (recursive) reloading by default. IPython can use the
91 """Enable deep (recursive) reloading by default. IPython can use the
92 deep_reload module which reloads changes in modules recursively (it
92 deep_reload module which reloads changes in modules recursively (it
93 replaces the reload() function, so you don't need to change anything to
93 replaces the reload() function, so you don't need to change anything to
94 use it). deep_reload() forces a full reload of modules whose code may
94 use it). deep_reload() forces a full reload of modules whose code may
95 have changed, which the default reload() function does not. When
95 have changed, which the default reload() function does not. When
96 deep_reload is off, IPython will use the normal reload(), but
96 deep_reload is off, IPython will use the normal reload(), but
97 deep_reload will still be available as dreload(). This feature is off
97 deep_reload will still be available as dreload(). This feature is off
98 by default [which means that you have both normal reload() and
98 by default [which means that you have both normal reload() and
99 dreload()].""",
99 dreload()].""",
100 "Disable deep (recursive) reloading by default."
100 "Disable deep (recursive) reloading by default."
101 )
101 )
102 nosep_config = Config()
102 nosep_config = Config()
103 nosep_config.InteractiveShell.separate_in = ''
103 nosep_config.InteractiveShell.separate_in = ''
104 nosep_config.InteractiveShell.separate_out = ''
104 nosep_config.InteractiveShell.separate_out = ''
105 nosep_config.InteractiveShell.separate_out2 = ''
105 nosep_config.InteractiveShell.separate_out2 = ''
106
106
107 shell_flags['nosep']=(nosep_config, "Eliminate all spacing between prompts.")
107 shell_flags['nosep']=(nosep_config, "Eliminate all spacing between prompts.")
108 shell_flags['pylab'] = (
108 shell_flags['pylab'] = (
109 {'InteractiveShellApp' : {'pylab' : 'auto'}},
109 {'InteractiveShellApp' : {'pylab' : 'auto'}},
110 """Pre-load matplotlib and numpy for interactive use with
110 """Pre-load matplotlib and numpy for interactive use with
111 the default matplotlib backend."""
111 the default matplotlib backend."""
112 )
112 )
113 shell_flags['matplotlib'] = (
113 shell_flags['matplotlib'] = (
114 {'InteractiveShellApp' : {'matplotlib' : 'auto'}},
114 {'InteractiveShellApp' : {'matplotlib' : 'auto'}},
115 """Configure matplotlib for interactive use with
115 """Configure matplotlib for interactive use with
116 the default matplotlib backend."""
116 the default matplotlib backend."""
117 )
117 )
118
118
119 # it's possible we don't want short aliases for *all* of these:
119 # it's possible we don't want short aliases for *all* of these:
120 shell_aliases = dict(
120 shell_aliases = dict(
121 autocall='InteractiveShell.autocall',
121 autocall='InteractiveShell.autocall',
122 colors='InteractiveShell.colors',
122 colors='InteractiveShell.colors',
123 logfile='InteractiveShell.logfile',
123 logfile='InteractiveShell.logfile',
124 logappend='InteractiveShell.logappend',
124 logappend='InteractiveShell.logappend',
125 c='InteractiveShellApp.code_to_run',
125 c='InteractiveShellApp.code_to_run',
126 m='InteractiveShellApp.module_to_run',
126 m='InteractiveShellApp.module_to_run',
127 ext='InteractiveShellApp.extra_extension',
127 ext='InteractiveShellApp.extra_extension',
128 gui='InteractiveShellApp.gui',
128 gui='InteractiveShellApp.gui',
129 pylab='InteractiveShellApp.pylab',
129 pylab='InteractiveShellApp.pylab',
130 matplotlib='InteractiveShellApp.matplotlib',
130 matplotlib='InteractiveShellApp.matplotlib',
131 )
131 )
132 shell_aliases['cache-size'] = 'InteractiveShell.cache_size'
132 shell_aliases['cache-size'] = 'InteractiveShell.cache_size'
133
133
134 #-----------------------------------------------------------------------------
134 #-----------------------------------------------------------------------------
135 # Main classes and functions
135 # Main classes and functions
136 #-----------------------------------------------------------------------------
136 #-----------------------------------------------------------------------------
137
137
138 class InteractiveShellApp(Configurable):
138 class InteractiveShellApp(Configurable):
139 """A Mixin for applications that start InteractiveShell instances.
139 """A Mixin for applications that start InteractiveShell instances.
140
140
141 Provides configurables for loading extensions and executing files
141 Provides configurables for loading extensions and executing files
142 as part of configuring a Shell environment.
142 as part of configuring a Shell environment.
143
143
144 The following methods should be called by the :meth:`initialize` method
144 The following methods should be called by the :meth:`initialize` method
145 of the subclass:
145 of the subclass:
146
146
147 - :meth:`init_path`
147 - :meth:`init_path`
148 - :meth:`init_shell` (to be implemented by the subclass)
148 - :meth:`init_shell` (to be implemented by the subclass)
149 - :meth:`init_gui_pylab`
149 - :meth:`init_gui_pylab`
150 - :meth:`init_extensions`
150 - :meth:`init_extensions`
151 - :meth:`init_code`
151 - :meth:`init_code`
152 """
152 """
153 extensions = List(Unicode, config=True,
153 extensions = List(Unicode, config=True,
154 help="A list of dotted module names of IPython extensions to load."
154 help="A list of dotted module names of IPython extensions to load."
155 )
155 )
156 extra_extension = Unicode('', config=True,
156 extra_extension = Unicode('', config=True,
157 help="dotted module name of an IPython extension to load."
157 help="dotted module name of an IPython extension to load."
158 )
158 )
159 def _extra_extension_changed(self, name, old, new):
159 def _extra_extension_changed(self, name, old, new):
160 if new:
160 if new:
161 # add to self.extensions
161 # add to self.extensions
162 self.extensions.append(new)
162 self.extensions.append(new)
163
163
164 # Extensions that are always loaded (not configurable)
164 # Extensions that are always loaded (not configurable)
165 default_extensions = List(Unicode, [u'storemagic'], config=False)
165 default_extensions = List(Unicode, [u'storemagic'], config=False)
166
166
167 hide_initial_ns = Bool(True, config=True,
167 hide_initial_ns = Bool(True, config=True,
168 help="""Should variables loaded at startup (by startup files, exec_lines, etc.)
168 help="""Should variables loaded at startup (by startup files, exec_lines, etc.)
169 be hidden from tools like %who?"""
169 be hidden from tools like %who?"""
170 )
170 )
171
171
172 exec_files = List(Unicode, config=True,
172 exec_files = List(Unicode, config=True,
173 help="""List of files to run at IPython startup."""
173 help="""List of files to run at IPython startup."""
174 )
174 )
175 exec_PYTHONSTARTUP = Bool(True, config=True,
176 help="""Run the file referenced by the PYTHONSTARTUP environment
177 variable at IPython startup."""
178 )
175 file_to_run = Unicode('', config=True,
179 file_to_run = Unicode('', config=True,
176 help="""A file to be run""")
180 help="""A file to be run""")
177
181
178 exec_lines = List(Unicode, config=True,
182 exec_lines = List(Unicode, config=True,
179 help="""lines of code to run at IPython startup."""
183 help="""lines of code to run at IPython startup."""
180 )
184 )
181 code_to_run = Unicode('', config=True,
185 code_to_run = Unicode('', config=True,
182 help="Execute the given command string."
186 help="Execute the given command string."
183 )
187 )
184 module_to_run = Unicode('', config=True,
188 module_to_run = Unicode('', config=True,
185 help="Run the module as a script."
189 help="Run the module as a script."
186 )
190 )
187 gui = CaselessStrEnum(gui_keys, config=True,
191 gui = CaselessStrEnum(gui_keys, config=True,
188 help="Enable GUI event loop integration with any of {0}.".format(gui_keys)
192 help="Enable GUI event loop integration with any of {0}.".format(gui_keys)
189 )
193 )
190 matplotlib = CaselessStrEnum(backend_keys,
194 matplotlib = CaselessStrEnum(backend_keys,
191 config=True,
195 config=True,
192 help="""Configure matplotlib for interactive use with
196 help="""Configure matplotlib for interactive use with
193 the default matplotlib backend."""
197 the default matplotlib backend."""
194 )
198 )
195 pylab = CaselessStrEnum(backend_keys,
199 pylab = CaselessStrEnum(backend_keys,
196 config=True,
200 config=True,
197 help="""Pre-load matplotlib and numpy for interactive use,
201 help="""Pre-load matplotlib and numpy for interactive use,
198 selecting a particular matplotlib backend and loop integration.
202 selecting a particular matplotlib backend and loop integration.
199 """
203 """
200 )
204 )
201 pylab_import_all = Bool(True, config=True,
205 pylab_import_all = Bool(True, config=True,
202 help="""If true, IPython will populate the user namespace with numpy, pylab, etc.
206 help="""If true, IPython will populate the user namespace with numpy, pylab, etc.
203 and an ``import *`` is done from numpy and pylab, when using pylab mode.
207 and an ``import *`` is done from numpy and pylab, when using pylab mode.
204
208
205 When False, pylab mode should not import any names into the user namespace.
209 When False, pylab mode should not import any names into the user namespace.
206 """
210 """
207 )
211 )
208 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
212 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
209
213
210 user_ns = Instance(dict, args=None, allow_none=True)
214 user_ns = Instance(dict, args=None, allow_none=True)
211 def _user_ns_changed(self, name, old, new):
215 def _user_ns_changed(self, name, old, new):
212 if self.shell is not None:
216 if self.shell is not None:
213 self.shell.user_ns = new
217 self.shell.user_ns = new
214 self.shell.init_user_ns()
218 self.shell.init_user_ns()
215
219
216 def init_path(self):
220 def init_path(self):
217 """Add current working directory, '', to sys.path"""
221 """Add current working directory, '', to sys.path"""
218 if sys.path[0] != '':
222 if sys.path[0] != '':
219 sys.path.insert(0, '')
223 sys.path.insert(0, '')
220
224
221 def init_shell(self):
225 def init_shell(self):
222 raise NotImplementedError("Override in subclasses")
226 raise NotImplementedError("Override in subclasses")
223
227
224 def init_gui_pylab(self):
228 def init_gui_pylab(self):
225 """Enable GUI event loop integration, taking pylab into account."""
229 """Enable GUI event loop integration, taking pylab into account."""
226 enable = False
230 enable = False
227 shell = self.shell
231 shell = self.shell
228 if self.pylab:
232 if self.pylab:
229 enable = lambda key: shell.enable_pylab(key, import_all=self.pylab_import_all)
233 enable = lambda key: shell.enable_pylab(key, import_all=self.pylab_import_all)
230 key = self.pylab
234 key = self.pylab
231 elif self.matplotlib:
235 elif self.matplotlib:
232 enable = shell.enable_matplotlib
236 enable = shell.enable_matplotlib
233 key = self.matplotlib
237 key = self.matplotlib
234 elif self.gui:
238 elif self.gui:
235 enable = shell.enable_gui
239 enable = shell.enable_gui
236 key = self.gui
240 key = self.gui
237
241
238 if not enable:
242 if not enable:
239 return
243 return
240
244
241 try:
245 try:
242 r = enable(key)
246 r = enable(key)
243 except ImportError:
247 except ImportError:
244 self.log.warn("Eventloop or matplotlib integration failed. Is matplotlib installed?")
248 self.log.warn("Eventloop or matplotlib integration failed. Is matplotlib installed?")
245 self.shell.showtraceback()
249 self.shell.showtraceback()
246 return
250 return
247 except Exception:
251 except Exception:
248 self.log.warn("GUI event loop or pylab initialization failed")
252 self.log.warn("GUI event loop or pylab initialization failed")
249 self.shell.showtraceback()
253 self.shell.showtraceback()
250 return
254 return
251
255
252 if isinstance(r, tuple):
256 if isinstance(r, tuple):
253 gui, backend = r[:2]
257 gui, backend = r[:2]
254 self.log.info("Enabling GUI event loop integration, "
258 self.log.info("Enabling GUI event loop integration, "
255 "eventloop=%s, matplotlib=%s", gui, backend)
259 "eventloop=%s, matplotlib=%s", gui, backend)
256 if key == "auto":
260 if key == "auto":
257 print("Using matplotlib backend: %s" % backend)
261 print("Using matplotlib backend: %s" % backend)
258 else:
262 else:
259 gui = r
263 gui = r
260 self.log.info("Enabling GUI event loop integration, "
264 self.log.info("Enabling GUI event loop integration, "
261 "eventloop=%s", gui)
265 "eventloop=%s", gui)
262
266
263 def init_extensions(self):
267 def init_extensions(self):
264 """Load all IPython extensions in IPythonApp.extensions.
268 """Load all IPython extensions in IPythonApp.extensions.
265
269
266 This uses the :meth:`ExtensionManager.load_extensions` to load all
270 This uses the :meth:`ExtensionManager.load_extensions` to load all
267 the extensions listed in ``self.extensions``.
271 the extensions listed in ``self.extensions``.
268 """
272 """
269 try:
273 try:
270 self.log.debug("Loading IPython extensions...")
274 self.log.debug("Loading IPython extensions...")
271 extensions = self.default_extensions + self.extensions
275 extensions = self.default_extensions + self.extensions
272 for ext in extensions:
276 for ext in extensions:
273 try:
277 try:
274 self.log.info("Loading IPython extension: %s" % ext)
278 self.log.info("Loading IPython extension: %s" % ext)
275 self.shell.extension_manager.load_extension(ext)
279 self.shell.extension_manager.load_extension(ext)
276 except:
280 except:
277 self.log.warn("Error in loading extension: %s" % ext +
281 self.log.warn("Error in loading extension: %s" % ext +
278 "\nCheck your config files in %s" % self.profile_dir.location
282 "\nCheck your config files in %s" % self.profile_dir.location
279 )
283 )
280 self.shell.showtraceback()
284 self.shell.showtraceback()
281 except:
285 except:
282 self.log.warn("Unknown error in loading extensions:")
286 self.log.warn("Unknown error in loading extensions:")
283 self.shell.showtraceback()
287 self.shell.showtraceback()
284
288
285 def init_code(self):
289 def init_code(self):
286 """run the pre-flight code, specified via exec_lines"""
290 """run the pre-flight code, specified via exec_lines"""
287 self._run_startup_files()
291 self._run_startup_files()
288 self._run_exec_lines()
292 self._run_exec_lines()
289 self._run_exec_files()
293 self._run_exec_files()
290
294
291 # Hide variables defined here from %who etc.
295 # Hide variables defined here from %who etc.
292 if self.hide_initial_ns:
296 if self.hide_initial_ns:
293 self.shell.user_ns_hidden.update(self.shell.user_ns)
297 self.shell.user_ns_hidden.update(self.shell.user_ns)
294
298
295 # command-line execution (ipython -i script.py, ipython -m module)
299 # command-line execution (ipython -i script.py, ipython -m module)
296 # should *not* be excluded from %whos
300 # should *not* be excluded from %whos
297 self._run_cmd_line_code()
301 self._run_cmd_line_code()
298 self._run_module()
302 self._run_module()
299
303
300 # flush output, so itwon't be attached to the first cell
304 # flush output, so itwon't be attached to the first cell
301 sys.stdout.flush()
305 sys.stdout.flush()
302 sys.stderr.flush()
306 sys.stderr.flush()
303
307
304 def _run_exec_lines(self):
308 def _run_exec_lines(self):
305 """Run lines of code in IPythonApp.exec_lines in the user's namespace."""
309 """Run lines of code in IPythonApp.exec_lines in the user's namespace."""
306 if not self.exec_lines:
310 if not self.exec_lines:
307 return
311 return
308 try:
312 try:
309 self.log.debug("Running code from IPythonApp.exec_lines...")
313 self.log.debug("Running code from IPythonApp.exec_lines...")
310 for line in self.exec_lines:
314 for line in self.exec_lines:
311 try:
315 try:
312 self.log.info("Running code in user namespace: %s" %
316 self.log.info("Running code in user namespace: %s" %
313 line)
317 line)
314 self.shell.run_cell(line, store_history=False)
318 self.shell.run_cell(line, store_history=False)
315 except:
319 except:
316 self.log.warn("Error in executing line in user "
320 self.log.warn("Error in executing line in user "
317 "namespace: %s" % line)
321 "namespace: %s" % line)
318 self.shell.showtraceback()
322 self.shell.showtraceback()
319 except:
323 except:
320 self.log.warn("Unknown error in handling IPythonApp.exec_lines:")
324 self.log.warn("Unknown error in handling IPythonApp.exec_lines:")
321 self.shell.showtraceback()
325 self.shell.showtraceback()
322
326
323 def _exec_file(self, fname):
327 def _exec_file(self, fname):
324 try:
328 try:
325 full_filename = filefind(fname, [u'.', self.ipython_dir])
329 full_filename = filefind(fname, [u'.', self.ipython_dir])
326 except IOError as e:
330 except IOError as e:
327 self.log.warn("File not found: %r"%fname)
331 self.log.warn("File not found: %r"%fname)
328 return
332 return
329 # Make sure that the running script gets a proper sys.argv as if it
333 # Make sure that the running script gets a proper sys.argv as if it
330 # were run from a system shell.
334 # were run from a system shell.
331 save_argv = sys.argv
335 save_argv = sys.argv
332 sys.argv = [full_filename] + self.extra_args[1:]
336 sys.argv = [full_filename] + self.extra_args[1:]
333 # protect sys.argv from potential unicode strings on Python 2:
337 # protect sys.argv from potential unicode strings on Python 2:
334 if not py3compat.PY3:
338 if not py3compat.PY3:
335 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
339 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
336 try:
340 try:
337 if os.path.isfile(full_filename):
341 if os.path.isfile(full_filename):
338 self.log.info("Running file in user namespace: %s" %
342 self.log.info("Running file in user namespace: %s" %
339 full_filename)
343 full_filename)
340 # Ensure that __file__ is always defined to match Python
344 # Ensure that __file__ is always defined to match Python
341 # behavior.
345 # behavior.
342 with preserve_keys(self.shell.user_ns, '__file__'):
346 with preserve_keys(self.shell.user_ns, '__file__'):
343 self.shell.user_ns['__file__'] = fname
347 self.shell.user_ns['__file__'] = fname
344 if full_filename.endswith('.ipy'):
348 if full_filename.endswith('.ipy'):
345 self.shell.safe_execfile_ipy(full_filename)
349 self.shell.safe_execfile_ipy(full_filename)
346 else:
350 else:
347 # default to python, even without extension
351 # default to python, even without extension
348 self.shell.safe_execfile(full_filename,
352 self.shell.safe_execfile(full_filename,
349 self.shell.user_ns)
353 self.shell.user_ns)
350 finally:
354 finally:
351 sys.argv = save_argv
355 sys.argv = save_argv
352
356
353 def _run_startup_files(self):
357 def _run_startup_files(self):
354 """Run files from profile startup directory"""
358 """Run files from profile startup directory"""
355 startup_dir = self.profile_dir.startup_dir
359 startup_dir = self.profile_dir.startup_dir
356 startup_files = []
360 startup_files = []
357 if os.environ.get('PYTHONSTARTUP', False):
361 if self.exec_PYTHONSTARTUP:
358 startup_files.append(os.environ['PYTHONSTARTUP'])
362 if os.environ.get('PYTHONSTARTUP', False):
363 startup_files.append(os.environ['PYTHONSTARTUP'])
359 startup_files += glob.glob(os.path.join(startup_dir, '*.py'))
364 startup_files += glob.glob(os.path.join(startup_dir, '*.py'))
360 startup_files += glob.glob(os.path.join(startup_dir, '*.ipy'))
365 startup_files += glob.glob(os.path.join(startup_dir, '*.ipy'))
361 if not startup_files:
366 if not startup_files:
362 return
367 return
363
368
364 self.log.debug("Running startup files from %s...", startup_dir)
369 self.log.debug("Running startup files from %s...", startup_dir)
365 try:
370 try:
366 for fname in sorted(startup_files):
371 for fname in sorted(startup_files):
367 self._exec_file(fname)
372 self._exec_file(fname)
368 except:
373 except:
369 self.log.warn("Unknown error in handling startup files:")
374 self.log.warn("Unknown error in handling startup files:")
370 self.shell.showtraceback()
375 self.shell.showtraceback()
371
376
372 def _run_exec_files(self):
377 def _run_exec_files(self):
373 """Run files from IPythonApp.exec_files"""
378 """Run files from IPythonApp.exec_files"""
374 if not self.exec_files:
379 if not self.exec_files:
375 return
380 return
376
381
377 self.log.debug("Running files in IPythonApp.exec_files...")
382 self.log.debug("Running files in IPythonApp.exec_files...")
378 try:
383 try:
379 for fname in self.exec_files:
384 for fname in self.exec_files:
380 self._exec_file(fname)
385 self._exec_file(fname)
381 except:
386 except:
382 self.log.warn("Unknown error in handling IPythonApp.exec_files:")
387 self.log.warn("Unknown error in handling IPythonApp.exec_files:")
383 self.shell.showtraceback()
388 self.shell.showtraceback()
384
389
385 def _run_cmd_line_code(self):
390 def _run_cmd_line_code(self):
386 """Run code or file specified at the command-line"""
391 """Run code or file specified at the command-line"""
387 if self.code_to_run:
392 if self.code_to_run:
388 line = self.code_to_run
393 line = self.code_to_run
389 try:
394 try:
390 self.log.info("Running code given at command line (c=): %s" %
395 self.log.info("Running code given at command line (c=): %s" %
391 line)
396 line)
392 self.shell.run_cell(line, store_history=False)
397 self.shell.run_cell(line, store_history=False)
393 except:
398 except:
394 self.log.warn("Error in executing line in user namespace: %s" %
399 self.log.warn("Error in executing line in user namespace: %s" %
395 line)
400 line)
396 self.shell.showtraceback()
401 self.shell.showtraceback()
397
402
398 # Like Python itself, ignore the second if the first of these is present
403 # Like Python itself, ignore the second if the first of these is present
399 elif self.file_to_run:
404 elif self.file_to_run:
400 fname = self.file_to_run
405 fname = self.file_to_run
401 try:
406 try:
402 self._exec_file(fname)
407 self._exec_file(fname)
403 except:
408 except:
404 self.log.warn("Error in executing file in user namespace: %s" %
409 self.log.warn("Error in executing file in user namespace: %s" %
405 fname)
410 fname)
406 self.shell.showtraceback()
411 self.shell.showtraceback()
407
412
408 def _run_module(self):
413 def _run_module(self):
409 """Run module specified at the command-line."""
414 """Run module specified at the command-line."""
410 if self.module_to_run:
415 if self.module_to_run:
411 # Make sure that the module gets a proper sys.argv as if it were
416 # Make sure that the module gets a proper sys.argv as if it were
412 # run using `python -m`.
417 # run using `python -m`.
413 save_argv = sys.argv
418 save_argv = sys.argv
414 sys.argv = [sys.executable] + self.extra_args
419 sys.argv = [sys.executable] + self.extra_args
415 try:
420 try:
416 self.shell.safe_run_module(self.module_to_run,
421 self.shell.safe_run_module(self.module_to_run,
417 self.shell.user_ns)
422 self.shell.user_ns)
418 finally:
423 finally:
419 sys.argv = save_argv
424 sys.argv = save_argv
@@ -1,1164 +1,1169 b''
1 =================
1 =================
2 IPython reference
2 IPython reference
3 =================
3 =================
4
4
5 .. _command_line_options:
5 .. _command_line_options:
6
6
7 Command-line usage
7 Command-line usage
8 ==================
8 ==================
9
9
10 You start IPython with the command::
10 You start IPython with the command::
11
11
12 $ ipython [options] files
12 $ ipython [options] files
13
13
14 .. note::
14 .. note::
15
15
16 For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
16 For IPython on Python 3, use ``ipython3`` in place of ``ipython``.
17
17
18 If invoked with no options, it executes all the files listed in sequence
18 If invoked with no options, it executes all the files listed in sequence
19 and drops you into the interpreter while still acknowledging any options
19 and drops you into the interpreter while still acknowledging any options
20 you may have set in your ipython_config.py. This behavior is different from
20 you may have set in your ipython_config.py. This behavior is different from
21 standard Python, which when called as python -i will only execute one
21 standard Python, which when called as python -i will only execute one
22 file and ignore your configuration setup.
22 file and ignore your configuration setup.
23
23
24 Please note that some of the configuration options are not available at
24 Please note that some of the configuration options are not available at
25 the command line, simply because they are not practical here. Look into
25 the command line, simply because they are not practical here. Look into
26 your configuration files for details on those. There are separate configuration
26 your configuration files for details on those. There are separate configuration
27 files for each profile, and the files look like "ipython_config.py" or
27 files for each profile, and the files look like "ipython_config.py" or
28 "ipython_config_<frontendname>.py". Profile directories look like
28 "ipython_config_<frontendname>.py". Profile directories look like
29 "profile_profilename" and are typically installed in the IPYTHONDIR directory,
29 "profile_profilename" and are typically installed in the IPYTHONDIR directory,
30 which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
30 which defaults to :file:`$HOME/.ipython`. For Windows users, :envvar:`HOME`
31 resolves to :file:`C:\\Documents and Settings\\YourUserName` in most
31 resolves to :file:`C:\\Documents and Settings\\YourUserName` in most
32 instances.
32 instances.
33
33
34
34
35 Eventloop integration
35 Eventloop integration
36 ---------------------
36 ---------------------
37
37
38 Previously IPython had command line options for controlling GUI event loop
38 Previously IPython had command line options for controlling GUI event loop
39 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
39 integration (-gthread, -qthread, -q4thread, -wthread, -pylab). As of IPython
40 version 0.11, these have been removed. Please see the new ``%gui``
40 version 0.11, these have been removed. Please see the new ``%gui``
41 magic command or :ref:`this section <gui_support>` for details on the new
41 magic command or :ref:`this section <gui_support>` for details on the new
42 interface, or specify the gui at the commandline::
42 interface, or specify the gui at the commandline::
43
43
44 $ ipython --gui=qt
44 $ ipython --gui=qt
45
45
46
46
47 Command-line Options
47 Command-line Options
48 --------------------
48 --------------------
49
49
50 To see the options IPython accepts, use ``ipython --help`` (and you probably
50 To see the options IPython accepts, use ``ipython --help`` (and you probably
51 should run the output through a pager such as ``ipython --help | less`` for
51 should run the output through a pager such as ``ipython --help | less`` for
52 more convenient reading). This shows all the options that have a single-word
52 more convenient reading). This shows all the options that have a single-word
53 alias to control them, but IPython lets you configure all of its objects from
53 alias to control them, but IPython lets you configure all of its objects from
54 the command-line by passing the full class name and a corresponding value; type
54 the command-line by passing the full class name and a corresponding value; type
55 ``ipython --help-all`` to see this full list. For example::
55 ``ipython --help-all`` to see this full list. For example::
56
56
57 ipython --matplotlib qt
57 ipython --matplotlib qt
58
58
59 is equivalent to::
59 is equivalent to::
60
60
61 ipython --TerminalIPythonApp.matplotlib='qt'
61 ipython --TerminalIPythonApp.matplotlib='qt'
62
62
63 Note that in the second form, you *must* use the equal sign, as the expression
63 Note that in the second form, you *must* use the equal sign, as the expression
64 is evaluated as an actual Python assignment. While in the above example the
64 is evaluated as an actual Python assignment. While in the above example the
65 short form is more convenient, only the most common options have a short form,
65 short form is more convenient, only the most common options have a short form,
66 while any configurable variable in IPython can be set at the command-line by
66 while any configurable variable in IPython can be set at the command-line by
67 using the long form. This long form is the same syntax used in the
67 using the long form. This long form is the same syntax used in the
68 configuration files, if you want to set these options permanently.
68 configuration files, if you want to set these options permanently.
69
69
70
70
71 Interactive use
71 Interactive use
72 ===============
72 ===============
73
73
74 IPython is meant to work as a drop-in replacement for the standard interactive
74 IPython is meant to work as a drop-in replacement for the standard interactive
75 interpreter. As such, any code which is valid python should execute normally
75 interpreter. As such, any code which is valid python should execute normally
76 under IPython (cases where this is not true should be reported as bugs). It
76 under IPython (cases where this is not true should be reported as bugs). It
77 does, however, offer many features which are not available at a standard python
77 does, however, offer many features which are not available at a standard python
78 prompt. What follows is a list of these.
78 prompt. What follows is a list of these.
79
79
80
80
81 Caution for Windows users
81 Caution for Windows users
82 -------------------------
82 -------------------------
83
83
84 Windows, unfortunately, uses the '\\' character as a path separator. This is a
84 Windows, unfortunately, uses the '\\' character as a path separator. This is a
85 terrible choice, because '\\' also represents the escape character in most
85 terrible choice, because '\\' also represents the escape character in most
86 modern programming languages, including Python. For this reason, using '/'
86 modern programming languages, including Python. For this reason, using '/'
87 character is recommended if you have problems with ``\``. However, in Windows
87 character is recommended if you have problems with ``\``. However, in Windows
88 commands '/' flags options, so you can not use it for the root directory. This
88 commands '/' flags options, so you can not use it for the root directory. This
89 means that paths beginning at the root must be typed in a contrived manner
89 means that paths beginning at the root must be typed in a contrived manner
90 like: ``%copy \opt/foo/bar.txt \tmp``
90 like: ``%copy \opt/foo/bar.txt \tmp``
91
91
92 .. _magic:
92 .. _magic:
93
93
94 Magic command system
94 Magic command system
95 --------------------
95 --------------------
96
96
97 IPython will treat any line whose first character is a % as a special
97 IPython will treat any line whose first character is a % as a special
98 call to a 'magic' function. These allow you to control the behavior of
98 call to a 'magic' function. These allow you to control the behavior of
99 IPython itself, plus a lot of system-type features. They are all
99 IPython itself, plus a lot of system-type features. They are all
100 prefixed with a % character, but parameters are given without
100 prefixed with a % character, but parameters are given without
101 parentheses or quotes.
101 parentheses or quotes.
102
102
103 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
103 Lines that begin with ``%%`` signal a *cell magic*: they take as arguments not
104 only the rest of the current line, but all lines below them as well, in the
104 only the rest of the current line, but all lines below them as well, in the
105 current execution block. Cell magics can in fact make arbitrary modifications
105 current execution block. Cell magics can in fact make arbitrary modifications
106 to the input they receive, which need not even be valid Python code at all.
106 to the input they receive, which need not even be valid Python code at all.
107 They receive the whole block as a single string.
107 They receive the whole block as a single string.
108
108
109 As a line magic example, the ``%cd`` magic works just like the OS command of
109 As a line magic example, the ``%cd`` magic works just like the OS command of
110 the same name::
110 the same name::
111
111
112 In [8]: %cd
112 In [8]: %cd
113 /home/fperez
113 /home/fperez
114
114
115 The following uses the builtin ``timeit`` in cell mode::
115 The following uses the builtin ``timeit`` in cell mode::
116
116
117 In [10]: %%timeit x = range(10000)
117 In [10]: %%timeit x = range(10000)
118 ...: min(x)
118 ...: min(x)
119 ...: max(x)
119 ...: max(x)
120 ...:
120 ...:
121 1000 loops, best of 3: 438 us per loop
121 1000 loops, best of 3: 438 us per loop
122
122
123 In this case, ``x = range(10000)`` is called as the line argument, and the
123 In this case, ``x = range(10000)`` is called as the line argument, and the
124 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
124 block with ``min(x)`` and ``max(x)`` is called as the cell body. The
125 ``timeit`` magic receives both.
125 ``timeit`` magic receives both.
126
126
127 If you have 'automagic' enabled (as it by default), you don't need to type in
127 If you have 'automagic' enabled (as it by default), you don't need to type in
128 the single ``%`` explicitly for line magics; IPython will scan its internal
128 the single ``%`` explicitly for line magics; IPython will scan its internal
129 list of magic functions and call one if it exists. With automagic on you can
129 list of magic functions and call one if it exists. With automagic on you can
130 then just type ``cd mydir`` to go to directory 'mydir'::
130 then just type ``cd mydir`` to go to directory 'mydir'::
131
131
132 In [9]: cd mydir
132 In [9]: cd mydir
133 /home/fperez/mydir
133 /home/fperez/mydir
134
134
135 Note that cell magics *always* require an explicit ``%%`` prefix, automagic
135 Note that cell magics *always* require an explicit ``%%`` prefix, automagic
136 calling only works for line magics.
136 calling only works for line magics.
137
137
138 The automagic system has the lowest possible precedence in name searches, so
138 The automagic system has the lowest possible precedence in name searches, so
139 defining an identifier with the same name as an existing magic function will
139 defining an identifier with the same name as an existing magic function will
140 shadow it for automagic use. You can still access the shadowed magic function
140 shadow it for automagic use. You can still access the shadowed magic function
141 by explicitly using the ``%`` character at the beginning of the line.
141 by explicitly using the ``%`` character at the beginning of the line.
142
142
143 An example (with automagic on) should clarify all this:
143 An example (with automagic on) should clarify all this:
144
144
145 .. sourcecode:: ipython
145 .. sourcecode:: ipython
146
146
147 In [1]: cd ipython # %cd is called by automagic
147 In [1]: cd ipython # %cd is called by automagic
148 /home/fperez/ipython
148 /home/fperez/ipython
149
149
150 In [2]: cd=1 # now cd is just a variable
150 In [2]: cd=1 # now cd is just a variable
151
151
152 In [3]: cd .. # and doesn't work as a function anymore
152 In [3]: cd .. # and doesn't work as a function anymore
153 File "<ipython-input-3-9fedb3aff56c>", line 1
153 File "<ipython-input-3-9fedb3aff56c>", line 1
154 cd ..
154 cd ..
155 ^
155 ^
156 SyntaxError: invalid syntax
156 SyntaxError: invalid syntax
157
157
158
158
159 In [4]: %cd .. # but %cd always works
159 In [4]: %cd .. # but %cd always works
160 /home/fperez
160 /home/fperez
161
161
162 In [5]: del cd # if you remove the cd variable, automagic works again
162 In [5]: del cd # if you remove the cd variable, automagic works again
163
163
164 In [6]: cd ipython
164 In [6]: cd ipython
165
165
166 /home/fperez/ipython
166 /home/fperez/ipython
167
167
168 Defining your own magics
168 Defining your own magics
169 ++++++++++++++++++++++++
169 ++++++++++++++++++++++++
170
170
171 There are two main ways to define your own magic functions: from standalone
171 There are two main ways to define your own magic functions: from standalone
172 functions and by inheriting from a base class provided by IPython:
172 functions and by inheriting from a base class provided by IPython:
173 :class:`IPython.core.magic.Magics`. Below we show code you can place in a file
173 :class:`IPython.core.magic.Magics`. Below we show code you can place in a file
174 that you load from your configuration, such as any file in the ``startup``
174 that you load from your configuration, such as any file in the ``startup``
175 subdirectory of your default IPython profile.
175 subdirectory of your default IPython profile.
176
176
177 First, let us see the simplest case. The following shows how to create a line
177 First, let us see the simplest case. The following shows how to create a line
178 magic, a cell one and one that works in both modes, using just plain functions:
178 magic, a cell one and one that works in both modes, using just plain functions:
179
179
180 .. sourcecode:: python
180 .. sourcecode:: python
181
181
182 from IPython.core.magic import (register_line_magic, register_cell_magic,
182 from IPython.core.magic import (register_line_magic, register_cell_magic,
183 register_line_cell_magic)
183 register_line_cell_magic)
184
184
185 @register_line_magic
185 @register_line_magic
186 def lmagic(line):
186 def lmagic(line):
187 "my line magic"
187 "my line magic"
188 return line
188 return line
189
189
190 @register_cell_magic
190 @register_cell_magic
191 def cmagic(line, cell):
191 def cmagic(line, cell):
192 "my cell magic"
192 "my cell magic"
193 return line, cell
193 return line, cell
194
194
195 @register_line_cell_magic
195 @register_line_cell_magic
196 def lcmagic(line, cell=None):
196 def lcmagic(line, cell=None):
197 "Magic that works both as %lcmagic and as %%lcmagic"
197 "Magic that works both as %lcmagic and as %%lcmagic"
198 if cell is None:
198 if cell is None:
199 print "Called as line magic"
199 print "Called as line magic"
200 return line
200 return line
201 else:
201 else:
202 print "Called as cell magic"
202 print "Called as cell magic"
203 return line, cell
203 return line, cell
204
204
205 # We delete these to avoid name conflicts for automagic to work
205 # We delete these to avoid name conflicts for automagic to work
206 del lmagic, lcmagic
206 del lmagic, lcmagic
207
207
208
208
209 You can also create magics of all three kinds by inheriting from the
209 You can also create magics of all three kinds by inheriting from the
210 :class:`IPython.core.magic.Magics` class. This lets you create magics that can
210 :class:`IPython.core.magic.Magics` class. This lets you create magics that can
211 potentially hold state in between calls, and that have full access to the main
211 potentially hold state in between calls, and that have full access to the main
212 IPython object:
212 IPython object:
213
213
214 .. sourcecode:: python
214 .. sourcecode:: python
215
215
216 # This code can be put in any Python module, it does not require IPython
216 # This code can be put in any Python module, it does not require IPython
217 # itself to be running already. It only creates the magics subclass but
217 # itself to be running already. It only creates the magics subclass but
218 # doesn't instantiate it yet.
218 # doesn't instantiate it yet.
219 from IPython.core.magic import (Magics, magics_class, line_magic,
219 from IPython.core.magic import (Magics, magics_class, line_magic,
220 cell_magic, line_cell_magic)
220 cell_magic, line_cell_magic)
221
221
222 # The class MUST call this class decorator at creation time
222 # The class MUST call this class decorator at creation time
223 @magics_class
223 @magics_class
224 class MyMagics(Magics):
224 class MyMagics(Magics):
225
225
226 @line_magic
226 @line_magic
227 def lmagic(self, line):
227 def lmagic(self, line):
228 "my line magic"
228 "my line magic"
229 print "Full access to the main IPython object:", self.shell
229 print "Full access to the main IPython object:", self.shell
230 print "Variables in the user namespace:", self.shell.user_ns.keys()
230 print "Variables in the user namespace:", self.shell.user_ns.keys()
231 return line
231 return line
232
232
233 @cell_magic
233 @cell_magic
234 def cmagic(self, line, cell):
234 def cmagic(self, line, cell):
235 "my cell magic"
235 "my cell magic"
236 return line, cell
236 return line, cell
237
237
238 @line_cell_magic
238 @line_cell_magic
239 def lcmagic(self, line, cell=None):
239 def lcmagic(self, line, cell=None):
240 "Magic that works both as %lcmagic and as %%lcmagic"
240 "Magic that works both as %lcmagic and as %%lcmagic"
241 if cell is None:
241 if cell is None:
242 print "Called as line magic"
242 print "Called as line magic"
243 return line
243 return line
244 else:
244 else:
245 print "Called as cell magic"
245 print "Called as cell magic"
246 return line, cell
246 return line, cell
247
247
248
248
249 # In order to actually use these magics, you must register them with a
249 # In order to actually use these magics, you must register them with a
250 # running IPython. This code must be placed in a file that is loaded once
250 # running IPython. This code must be placed in a file that is loaded once
251 # IPython is up and running:
251 # IPython is up and running:
252 ip = get_ipython()
252 ip = get_ipython()
253 # You can register the class itself without instantiating it. IPython will
253 # You can register the class itself without instantiating it. IPython will
254 # call the default constructor on it.
254 # call the default constructor on it.
255 ip.register_magics(MyMagics)
255 ip.register_magics(MyMagics)
256
256
257 If you want to create a class with a different constructor that holds
257 If you want to create a class with a different constructor that holds
258 additional state, then you should always call the parent constructor and
258 additional state, then you should always call the parent constructor and
259 instantiate the class yourself before registration:
259 instantiate the class yourself before registration:
260
260
261 .. sourcecode:: python
261 .. sourcecode:: python
262
262
263 @magics_class
263 @magics_class
264 class StatefulMagics(Magics):
264 class StatefulMagics(Magics):
265 "Magics that hold additional state"
265 "Magics that hold additional state"
266
266
267 def __init__(self, shell, data):
267 def __init__(self, shell, data):
268 # You must call the parent constructor
268 # You must call the parent constructor
269 super(StatefulMagics, self).__init__(shell)
269 super(StatefulMagics, self).__init__(shell)
270 self.data = data
270 self.data = data
271
271
272 # etc...
272 # etc...
273
273
274 # This class must then be registered with a manually created instance,
274 # This class must then be registered with a manually created instance,
275 # since its constructor has different arguments from the default:
275 # since its constructor has different arguments from the default:
276 ip = get_ipython()
276 ip = get_ipython()
277 magics = StatefulMagics(ip, some_data)
277 magics = StatefulMagics(ip, some_data)
278 ip.register_magics(magics)
278 ip.register_magics(magics)
279
279
280
280
281 In earlier versions, IPython had an API for the creation of line magics (cell
281 In earlier versions, IPython had an API for the creation of line magics (cell
282 magics did not exist at the time) that required you to create functions with a
282 magics did not exist at the time) that required you to create functions with a
283 method-looking signature and to manually pass both the function and the name.
283 method-looking signature and to manually pass both the function and the name.
284 While this API is no longer recommended, it remains indefinitely supported for
284 While this API is no longer recommended, it remains indefinitely supported for
285 backwards compatibility purposes. With the old API, you'd create a magic as
285 backwards compatibility purposes. With the old API, you'd create a magic as
286 follows:
286 follows:
287
287
288 .. sourcecode:: python
288 .. sourcecode:: python
289
289
290 def func(self, line):
290 def func(self, line):
291 print "Line magic called with line:", line
291 print "Line magic called with line:", line
292 print "IPython object:", self.shell
292 print "IPython object:", self.shell
293
293
294 ip = get_ipython()
294 ip = get_ipython()
295 # Declare this function as the magic %mycommand
295 # Declare this function as the magic %mycommand
296 ip.define_magic('mycommand', func)
296 ip.define_magic('mycommand', func)
297
297
298 Type ``%magic`` for more information, including a list of all available magic
298 Type ``%magic`` for more information, including a list of all available magic
299 functions at any time and their docstrings. You can also type
299 functions at any time and their docstrings. You can also type
300 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
300 ``%magic_function_name?`` (see :ref:`below <dynamic_object_info>` for
301 information on the '?' system) to get information about any particular magic
301 information on the '?' system) to get information about any particular magic
302 function you are interested in.
302 function you are interested in.
303
303
304 The API documentation for the :mod:`IPython.core.magic` module contains the full
304 The API documentation for the :mod:`IPython.core.magic` module contains the full
305 docstrings of all currently available magic commands.
305 docstrings of all currently available magic commands.
306
306
307
307
308 Access to the standard Python help
308 Access to the standard Python help
309 ----------------------------------
309 ----------------------------------
310
310
311 Simply type ``help()`` to access Python's standard help system. You can
311 Simply type ``help()`` to access Python's standard help system. You can
312 also type ``help(object)`` for information about a given object, or
312 also type ``help(object)`` for information about a given object, or
313 ``help('keyword')`` for information on a keyword. You may need to configure your
313 ``help('keyword')`` for information on a keyword. You may need to configure your
314 PYTHONDOCS environment variable for this feature to work correctly.
314 PYTHONDOCS environment variable for this feature to work correctly.
315
315
316 .. _dynamic_object_info:
316 .. _dynamic_object_info:
317
317
318 Dynamic object information
318 Dynamic object information
319 --------------------------
319 --------------------------
320
320
321 Typing ``?word`` or ``word?`` prints detailed information about an object. If
321 Typing ``?word`` or ``word?`` prints detailed information about an object. If
322 certain strings in the object are too long (e.g. function signatures) they get
322 certain strings in the object are too long (e.g. function signatures) they get
323 snipped in the center for brevity. This system gives access variable types and
323 snipped in the center for brevity. This system gives access variable types and
324 values, docstrings, function prototypes and other useful information.
324 values, docstrings, function prototypes and other useful information.
325
325
326 If the information will not fit in the terminal, it is displayed in a pager
326 If the information will not fit in the terminal, it is displayed in a pager
327 (``less`` if available, otherwise a basic internal pager).
327 (``less`` if available, otherwise a basic internal pager).
328
328
329 Typing ``??word`` or ``word??`` gives access to the full information, including
329 Typing ``??word`` or ``word??`` gives access to the full information, including
330 the source code where possible. Long strings are not snipped.
330 the source code where possible. Long strings are not snipped.
331
331
332 The following magic functions are particularly useful for gathering
332 The following magic functions are particularly useful for gathering
333 information about your working environment. You can get more details by
333 information about your working environment. You can get more details by
334 typing ``%magic`` or querying them individually (``%function_name?``);
334 typing ``%magic`` or querying them individually (``%function_name?``);
335 this is just a summary:
335 this is just a summary:
336
336
337 * **%pdoc <object>**: Print (or run through a pager if too long) the
337 * **%pdoc <object>**: Print (or run through a pager if too long) the
338 docstring for an object. If the given object is a class, it will
338 docstring for an object. If the given object is a class, it will
339 print both the class and the constructor docstrings.
339 print both the class and the constructor docstrings.
340 * **%pdef <object>**: Print the call signature for any callable
340 * **%pdef <object>**: Print the call signature for any callable
341 object. If the object is a class, print the constructor information.
341 object. If the object is a class, print the constructor information.
342 * **%psource <object>**: Print (or run through a pager if too long)
342 * **%psource <object>**: Print (or run through a pager if too long)
343 the source code for an object.
343 the source code for an object.
344 * **%pfile <object>**: Show the entire source file where an object was
344 * **%pfile <object>**: Show the entire source file where an object was
345 defined via a pager, opening it at the line where the object
345 defined via a pager, opening it at the line where the object
346 definition begins.
346 definition begins.
347 * **%who/%whos**: These functions give information about identifiers
347 * **%who/%whos**: These functions give information about identifiers
348 you have defined interactively (not things you loaded or defined
348 you have defined interactively (not things you loaded or defined
349 in your configuration files). %who just prints a list of
349 in your configuration files). %who just prints a list of
350 identifiers and %whos prints a table with some basic details about
350 identifiers and %whos prints a table with some basic details about
351 each identifier.
351 each identifier.
352
352
353 Note that the dynamic object information functions (?/??, ``%pdoc``,
353 Note that the dynamic object information functions (?/??, ``%pdoc``,
354 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
354 ``%pfile``, ``%pdef``, ``%psource``) work on object attributes, as well as
355 directly on variables. For example, after doing ``import os``, you can use
355 directly on variables. For example, after doing ``import os``, you can use
356 ``os.path.abspath??``.
356 ``os.path.abspath??``.
357
357
358 .. _readline:
358 .. _readline:
359
359
360 Readline-based features
360 Readline-based features
361 -----------------------
361 -----------------------
362
362
363 These features require the GNU readline library, so they won't work if your
363 These features require the GNU readline library, so they won't work if your
364 Python installation lacks readline support. We will first describe the default
364 Python installation lacks readline support. We will first describe the default
365 behavior IPython uses, and then how to change it to suit your preferences.
365 behavior IPython uses, and then how to change it to suit your preferences.
366
366
367
367
368 Command line completion
368 Command line completion
369 +++++++++++++++++++++++
369 +++++++++++++++++++++++
370
370
371 At any time, hitting TAB will complete any available python commands or
371 At any time, hitting TAB will complete any available python commands or
372 variable names, and show you a list of the possible completions if
372 variable names, and show you a list of the possible completions if
373 there's no unambiguous one. It will also complete filenames in the
373 there's no unambiguous one. It will also complete filenames in the
374 current directory if no python names match what you've typed so far.
374 current directory if no python names match what you've typed so far.
375
375
376
376
377 Search command history
377 Search command history
378 ++++++++++++++++++++++
378 ++++++++++++++++++++++
379
379
380 IPython provides two ways for searching through previous input and thus
380 IPython provides two ways for searching through previous input and thus
381 reduce the need for repetitive typing:
381 reduce the need for repetitive typing:
382
382
383 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
383 1. Start typing, and then use Ctrl-p (previous,up) and Ctrl-n
384 (next,down) to search through only the history items that match
384 (next,down) to search through only the history items that match
385 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
385 what you've typed so far. If you use Ctrl-p/Ctrl-n at a blank
386 prompt, they just behave like normal arrow keys.
386 prompt, they just behave like normal arrow keys.
387 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
387 2. Hit Ctrl-r: opens a search prompt. Begin typing and the system
388 searches your history for lines that contain what you've typed so
388 searches your history for lines that contain what you've typed so
389 far, completing as much as it can.
389 far, completing as much as it can.
390
390
391
391
392 Persistent command history across sessions
392 Persistent command history across sessions
393 ++++++++++++++++++++++++++++++++++++++++++
393 ++++++++++++++++++++++++++++++++++++++++++
394
394
395 IPython will save your input history when it leaves and reload it next
395 IPython will save your input history when it leaves and reload it next
396 time you restart it. By default, the history file is named
396 time you restart it. By default, the history file is named
397 $IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
397 $IPYTHONDIR/profile_<name>/history.sqlite. This allows you to keep
398 separate histories related to various tasks: commands related to
398 separate histories related to various tasks: commands related to
399 numerical work will not be clobbered by a system shell history, for
399 numerical work will not be clobbered by a system shell history, for
400 example.
400 example.
401
401
402
402
403 Autoindent
403 Autoindent
404 ++++++++++
404 ++++++++++
405
405
406 IPython can recognize lines ending in ':' and indent the next line,
406 IPython can recognize lines ending in ':' and indent the next line,
407 while also un-indenting automatically after 'raise' or 'return'.
407 while also un-indenting automatically after 'raise' or 'return'.
408
408
409 This feature uses the readline library, so it will honor your
409 This feature uses the readline library, so it will honor your
410 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
410 :file:`~/.inputrc` configuration (or whatever file your INPUTRC variable points
411 to). Adding the following lines to your :file:`.inputrc` file can make
411 to). Adding the following lines to your :file:`.inputrc` file can make
412 indenting/unindenting more convenient (M-i indents, M-u unindents)::
412 indenting/unindenting more convenient (M-i indents, M-u unindents)::
413
413
414 # if you don't already have a ~/.inputrc file, you need this include:
414 # if you don't already have a ~/.inputrc file, you need this include:
415 $include /etc/inputrc
415 $include /etc/inputrc
416
416
417 $if Python
417 $if Python
418 "\M-i": " "
418 "\M-i": " "
419 "\M-u": "\d\d\d\d"
419 "\M-u": "\d\d\d\d"
420 $endif
420 $endif
421
421
422 Note that there are 4 spaces between the quote marks after "M-i" above.
422 Note that there are 4 spaces between the quote marks after "M-i" above.
423
423
424 .. warning::
424 .. warning::
425
425
426 Setting the above indents will cause problems with unicode text entry in
426 Setting the above indents will cause problems with unicode text entry in
427 the terminal.
427 the terminal.
428
428
429 .. warning::
429 .. warning::
430
430
431 Autoindent is ON by default, but it can cause problems with the pasting of
431 Autoindent is ON by default, but it can cause problems with the pasting of
432 multi-line indented code (the pasted code gets re-indented on each line). A
432 multi-line indented code (the pasted code gets re-indented on each line). A
433 magic function %autoindent allows you to toggle it on/off at runtime. You
433 magic function %autoindent allows you to toggle it on/off at runtime. You
434 can also disable it permanently on in your :file:`ipython_config.py` file
434 can also disable it permanently on in your :file:`ipython_config.py` file
435 (set TerminalInteractiveShell.autoindent=False).
435 (set TerminalInteractiveShell.autoindent=False).
436
436
437 If you want to paste multiple lines in the terminal, it is recommended that
437 If you want to paste multiple lines in the terminal, it is recommended that
438 you use ``%paste``.
438 you use ``%paste``.
439
439
440
440
441 Customizing readline behavior
441 Customizing readline behavior
442 +++++++++++++++++++++++++++++
442 +++++++++++++++++++++++++++++
443
443
444 All these features are based on the GNU readline library, which has an
444 All these features are based on the GNU readline library, which has an
445 extremely customizable interface. Normally, readline is configured via a
445 extremely customizable interface. Normally, readline is configured via a
446 file which defines the behavior of the library; the details of the
446 file which defines the behavior of the library; the details of the
447 syntax for this can be found in the readline documentation available
447 syntax for this can be found in the readline documentation available
448 with your system or on the Internet. IPython doesn't read this file (if
448 with your system or on the Internet. IPython doesn't read this file (if
449 it exists) directly, but it does support passing to readline valid
449 it exists) directly, but it does support passing to readline valid
450 options via a simple interface. In brief, you can customize readline by
450 options via a simple interface. In brief, you can customize readline by
451 setting the following options in your configuration file (note
451 setting the following options in your configuration file (note
452 that these options can not be specified at the command line):
452 that these options can not be specified at the command line):
453
453
454 * **readline_parse_and_bind**: this holds a list of strings to be executed
454 * **readline_parse_and_bind**: this holds a list of strings to be executed
455 via a readline.parse_and_bind() command. The syntax for valid commands
455 via a readline.parse_and_bind() command. The syntax for valid commands
456 of this kind can be found by reading the documentation for the GNU
456 of this kind can be found by reading the documentation for the GNU
457 readline library, as these commands are of the kind which readline
457 readline library, as these commands are of the kind which readline
458 accepts in its configuration file.
458 accepts in its configuration file.
459 * **readline_remove_delims**: a string of characters to be removed
459 * **readline_remove_delims**: a string of characters to be removed
460 from the default word-delimiters list used by readline, so that
460 from the default word-delimiters list used by readline, so that
461 completions may be performed on strings which contain them. Do not
461 completions may be performed on strings which contain them. Do not
462 change the default value unless you know what you're doing.
462 change the default value unless you know what you're doing.
463
463
464 You will find the default values in your configuration file.
464 You will find the default values in your configuration file.
465
465
466
466
467 Session logging and restoring
467 Session logging and restoring
468 -----------------------------
468 -----------------------------
469
469
470 You can log all input from a session either by starting IPython with the
470 You can log all input from a session either by starting IPython with the
471 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
471 command line switch ``--logfile=foo.py`` (see :ref:`here <command_line_options>`)
472 or by activating the logging at any moment with the magic function %logstart.
472 or by activating the logging at any moment with the magic function %logstart.
473
473
474 Log files can later be reloaded by running them as scripts and IPython
474 Log files can later be reloaded by running them as scripts and IPython
475 will attempt to 'replay' the log by executing all the lines in it, thus
475 will attempt to 'replay' the log by executing all the lines in it, thus
476 restoring the state of a previous session. This feature is not quite
476 restoring the state of a previous session. This feature is not quite
477 perfect, but can still be useful in many cases.
477 perfect, but can still be useful in many cases.
478
478
479 The log files can also be used as a way to have a permanent record of
479 The log files can also be used as a way to have a permanent record of
480 any code you wrote while experimenting. Log files are regular text files
480 any code you wrote while experimenting. Log files are regular text files
481 which you can later open in your favorite text editor to extract code or
481 which you can later open in your favorite text editor to extract code or
482 to 'clean them up' before using them to replay a session.
482 to 'clean them up' before using them to replay a session.
483
483
484 The `%logstart` function for activating logging in mid-session is used as
484 The `%logstart` function for activating logging in mid-session is used as
485 follows::
485 follows::
486
486
487 %logstart [log_name [log_mode]]
487 %logstart [log_name [log_mode]]
488
488
489 If no name is given, it defaults to a file named 'ipython_log.py' in your
489 If no name is given, it defaults to a file named 'ipython_log.py' in your
490 current working directory, in 'rotate' mode (see below).
490 current working directory, in 'rotate' mode (see below).
491
491
492 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
492 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
493 history up to that point and then continues logging.
493 history up to that point and then continues logging.
494
494
495 %logstart takes a second optional parameter: logging mode. This can be
495 %logstart takes a second optional parameter: logging mode. This can be
496 one of (note that the modes are given unquoted):
496 one of (note that the modes are given unquoted):
497
497
498 * [over:] overwrite existing log_name.
498 * [over:] overwrite existing log_name.
499 * [backup:] rename (if exists) to log_name~ and start log_name.
499 * [backup:] rename (if exists) to log_name~ and start log_name.
500 * [append:] well, that says it.
500 * [append:] well, that says it.
501 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
501 * [rotate:] create rotating logs log_name.1~, log_name.2~, etc.
502
502
503 The %logoff and %logon functions allow you to temporarily stop and
503 The %logoff and %logon functions allow you to temporarily stop and
504 resume logging to a file which had previously been started with
504 resume logging to a file which had previously been started with
505 %logstart. They will fail (with an explanation) if you try to use them
505 %logstart. They will fail (with an explanation) if you try to use them
506 before logging has been started.
506 before logging has been started.
507
507
508 .. _system_shell_access:
508 .. _system_shell_access:
509
509
510 System shell access
510 System shell access
511 -------------------
511 -------------------
512
512
513 Any input line beginning with a ! character is passed verbatim (minus
513 Any input line beginning with a ! character is passed verbatim (minus
514 the !, of course) to the underlying operating system. For example,
514 the !, of course) to the underlying operating system. For example,
515 typing ``!ls`` will run 'ls' in the current directory.
515 typing ``!ls`` will run 'ls' in the current directory.
516
516
517 Manual capture of command output
517 Manual capture of command output
518 --------------------------------
518 --------------------------------
519
519
520 You can assign the result of a system command to a Python variable with the
520 You can assign the result of a system command to a Python variable with the
521 syntax ``myfiles = !ls``. This gets machine readable output from stdout
521 syntax ``myfiles = !ls``. This gets machine readable output from stdout
522 (e.g. without colours), and splits on newlines. To explicitly get this sort of
522 (e.g. without colours), and splits on newlines. To explicitly get this sort of
523 output without assigning to a variable, use two exclamation marks (``!!ls``) or
523 output without assigning to a variable, use two exclamation marks (``!!ls``) or
524 the ``%sx`` magic command.
524 the ``%sx`` magic command.
525
525
526 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
526 The captured list has some convenience features. ``myfiles.n`` or ``myfiles.s``
527 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
527 returns a string delimited by newlines or spaces, respectively. ``myfiles.p``
528 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
528 produces `path objects <http://pypi.python.org/pypi/path.py>`_ from the list items.
529 See :ref:`string_lists` for details.
529 See :ref:`string_lists` for details.
530
530
531 IPython also allows you to expand the value of python variables when
531 IPython also allows you to expand the value of python variables when
532 making system calls. Wrap variables or expressions in {braces}::
532 making system calls. Wrap variables or expressions in {braces}::
533
533
534 In [1]: pyvar = 'Hello world'
534 In [1]: pyvar = 'Hello world'
535 In [2]: !echo "A python variable: {pyvar}"
535 In [2]: !echo "A python variable: {pyvar}"
536 A python variable: Hello world
536 A python variable: Hello world
537 In [3]: import math
537 In [3]: import math
538 In [4]: x = 8
538 In [4]: x = 8
539 In [5]: !echo {math.factorial(x)}
539 In [5]: !echo {math.factorial(x)}
540 40320
540 40320
541
541
542 For simple cases, you can alternatively prepend $ to a variable name::
542 For simple cases, you can alternatively prepend $ to a variable name::
543
543
544 In [6]: !echo $sys.argv
544 In [6]: !echo $sys.argv
545 [/home/fperez/usr/bin/ipython]
545 [/home/fperez/usr/bin/ipython]
546 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
546 In [7]: !echo "A system variable: $$HOME" # Use $$ for literal $
547 A system variable: /home/fperez
547 A system variable: /home/fperez
548
548
549 System command aliases
549 System command aliases
550 ----------------------
550 ----------------------
551
551
552 The %alias magic function allows you to define magic functions which are in fact
552 The %alias magic function allows you to define magic functions which are in fact
553 system shell commands. These aliases can have parameters.
553 system shell commands. These aliases can have parameters.
554
554
555 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
555 ``%alias alias_name cmd`` defines 'alias_name' as an alias for 'cmd'
556
556
557 Then, typing ``alias_name params`` will execute the system command 'cmd
557 Then, typing ``alias_name params`` will execute the system command 'cmd
558 params' (from your underlying operating system).
558 params' (from your underlying operating system).
559
559
560 You can also define aliases with parameters using %s specifiers (one per
560 You can also define aliases with parameters using %s specifiers (one per
561 parameter). The following example defines the parts function as an
561 parameter). The following example defines the parts function as an
562 alias to the command 'echo first %s second %s' where each %s will be
562 alias to the command 'echo first %s second %s' where each %s will be
563 replaced by a positional parameter to the call to %parts::
563 replaced by a positional parameter to the call to %parts::
564
564
565 In [1]: %alias parts echo first %s second %s
565 In [1]: %alias parts echo first %s second %s
566 In [2]: parts A B
566 In [2]: parts A B
567 first A second B
567 first A second B
568 In [3]: parts A
568 In [3]: parts A
569 ERROR: Alias <parts> requires 2 arguments, 1 given.
569 ERROR: Alias <parts> requires 2 arguments, 1 given.
570
570
571 If called with no parameters, %alias prints the table of currently
571 If called with no parameters, %alias prints the table of currently
572 defined aliases.
572 defined aliases.
573
573
574 The %rehashx magic allows you to load your entire $PATH as
574 The %rehashx magic allows you to load your entire $PATH as
575 ipython aliases. See its docstring for further details.
575 ipython aliases. See its docstring for further details.
576
576
577
577
578 .. _dreload:
578 .. _dreload:
579
579
580 Recursive reload
580 Recursive reload
581 ----------------
581 ----------------
582
582
583 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
583 The :mod:`IPython.lib.deepreload` module allows you to recursively reload a
584 module: changes made to any of its dependencies will be reloaded without
584 module: changes made to any of its dependencies will be reloaded without
585 having to exit. To start using it, do::
585 having to exit. To start using it, do::
586
586
587 from IPython.lib.deepreload import reload as dreload
587 from IPython.lib.deepreload import reload as dreload
588
588
589
589
590 Verbose and colored exception traceback printouts
590 Verbose and colored exception traceback printouts
591 -------------------------------------------------
591 -------------------------------------------------
592
592
593 IPython provides the option to see very detailed exception tracebacks,
593 IPython provides the option to see very detailed exception tracebacks,
594 which can be especially useful when debugging large programs. You can
594 which can be especially useful when debugging large programs. You can
595 run any Python file with the %run function to benefit from these
595 run any Python file with the %run function to benefit from these
596 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
596 detailed tracebacks. Furthermore, both normal and verbose tracebacks can
597 be colored (if your terminal supports it) which makes them much easier
597 be colored (if your terminal supports it) which makes them much easier
598 to parse visually.
598 to parse visually.
599
599
600 See the magic xmode and colors functions for details (just type %magic).
600 See the magic xmode and colors functions for details (just type %magic).
601
601
602 These features are basically a terminal version of Ka-Ping Yee's cgitb
602 These features are basically a terminal version of Ka-Ping Yee's cgitb
603 module, now part of the standard Python library.
603 module, now part of the standard Python library.
604
604
605
605
606 .. _input_caching:
606 .. _input_caching:
607
607
608 Input caching system
608 Input caching system
609 --------------------
609 --------------------
610
610
611 IPython offers numbered prompts (In/Out) with input and output caching
611 IPython offers numbered prompts (In/Out) with input and output caching
612 (also referred to as 'input history'). All input is saved and can be
612 (also referred to as 'input history'). All input is saved and can be
613 retrieved as variables (besides the usual arrow key recall), in
613 retrieved as variables (besides the usual arrow key recall), in
614 addition to the %rep magic command that brings a history entry
614 addition to the %rep magic command that brings a history entry
615 up for editing on the next command line.
615 up for editing on the next command line.
616
616
617 The following GLOBAL variables always exist (so don't overwrite them!):
617 The following GLOBAL variables always exist (so don't overwrite them!):
618
618
619 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
619 * _i, _ii, _iii: store previous, next previous and next-next previous inputs.
620 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
620 * In, _ih : a list of all inputs; _ih[n] is the input from line n. If you
621 overwrite In with a variable of your own, you can remake the assignment to the
621 overwrite In with a variable of your own, you can remake the assignment to the
622 internal list with a simple ``In=_ih``.
622 internal list with a simple ``In=_ih``.
623
623
624 Additionally, global variables named _i<n> are dynamically created (<n>
624 Additionally, global variables named _i<n> are dynamically created (<n>
625 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
625 being the prompt counter), so ``_i<n> == _ih[<n>] == In[<n>]``.
626
626
627 For example, what you typed at prompt 14 is available as _i14, _ih[14]
627 For example, what you typed at prompt 14 is available as _i14, _ih[14]
628 and In[14].
628 and In[14].
629
629
630 This allows you to easily cut and paste multi line interactive prompts
630 This allows you to easily cut and paste multi line interactive prompts
631 by printing them out: they print like a clean string, without prompt
631 by printing them out: they print like a clean string, without prompt
632 characters. You can also manipulate them like regular variables (they
632 characters. You can also manipulate them like regular variables (they
633 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
633 are strings), modify or exec them (typing ``exec _i9`` will re-execute the
634 contents of input prompt 9.
634 contents of input prompt 9.
635
635
636 You can also re-execute multiple lines of input easily by using the
636 You can also re-execute multiple lines of input easily by using the
637 magic %rerun or %macro functions. The macro system also allows you to re-execute
637 magic %rerun or %macro functions. The macro system also allows you to re-execute
638 previous lines which include magic function calls (which require special
638 previous lines which include magic function calls (which require special
639 processing). Type %macro? for more details on the macro system.
639 processing). Type %macro? for more details on the macro system.
640
640
641 A history function %hist allows you to see any part of your input
641 A history function %hist allows you to see any part of your input
642 history by printing a range of the _i variables.
642 history by printing a range of the _i variables.
643
643
644 You can also search ('grep') through your history by typing
644 You can also search ('grep') through your history by typing
645 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
645 ``%hist -g somestring``. This is handy for searching for URLs, IP addresses,
646 etc. You can bring history entries listed by '%hist -g' up for editing
646 etc. You can bring history entries listed by '%hist -g' up for editing
647 with the %recall command, or run them immediately with %rerun.
647 with the %recall command, or run them immediately with %rerun.
648
648
649 .. _output_caching:
649 .. _output_caching:
650
650
651 Output caching system
651 Output caching system
652 ---------------------
652 ---------------------
653
653
654 For output that is returned from actions, a system similar to the input
654 For output that is returned from actions, a system similar to the input
655 cache exists but using _ instead of _i. Only actions that produce a
655 cache exists but using _ instead of _i. Only actions that produce a
656 result (NOT assignments, for example) are cached. If you are familiar
656 result (NOT assignments, for example) are cached. If you are familiar
657 with Mathematica, IPython's _ variables behave exactly like
657 with Mathematica, IPython's _ variables behave exactly like
658 Mathematica's % variables.
658 Mathematica's % variables.
659
659
660 The following GLOBAL variables always exist (so don't overwrite them!):
660 The following GLOBAL variables always exist (so don't overwrite them!):
661
661
662 * [_] (a single underscore) : stores previous output, like Python's
662 * [_] (a single underscore) : stores previous output, like Python's
663 default interpreter.
663 default interpreter.
664 * [__] (two underscores): next previous.
664 * [__] (two underscores): next previous.
665 * [___] (three underscores): next-next previous.
665 * [___] (three underscores): next-next previous.
666
666
667 Additionally, global variables named _<n> are dynamically created (<n>
667 Additionally, global variables named _<n> are dynamically created (<n>
668 being the prompt counter), such that the result of output <n> is always
668 being the prompt counter), such that the result of output <n> is always
669 available as _<n> (don't use the angle brackets, just the number, e.g.
669 available as _<n> (don't use the angle brackets, just the number, e.g.
670 _21).
670 _21).
671
671
672 These variables are also stored in a global dictionary (not a
672 These variables are also stored in a global dictionary (not a
673 list, since it only has entries for lines which returned a result)
673 list, since it only has entries for lines which returned a result)
674 available under the names _oh and Out (similar to _ih and In). So the
674 available under the names _oh and Out (similar to _ih and In). So the
675 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
675 output from line 12 can be obtained as _12, Out[12] or _oh[12]. If you
676 accidentally overwrite the Out variable you can recover it by typing
676 accidentally overwrite the Out variable you can recover it by typing
677 'Out=_oh' at the prompt.
677 'Out=_oh' at the prompt.
678
678
679 This system obviously can potentially put heavy memory demands on your
679 This system obviously can potentially put heavy memory demands on your
680 system, since it prevents Python's garbage collector from removing any
680 system, since it prevents Python's garbage collector from removing any
681 previously computed results. You can control how many results are kept
681 previously computed results. You can control how many results are kept
682 in memory with the option (at the command line or in your configuration
682 in memory with the option (at the command line or in your configuration
683 file) cache_size. If you set it to 0, the whole system is completely
683 file) cache_size. If you set it to 0, the whole system is completely
684 disabled and the prompts revert to the classic '>>>' of normal Python.
684 disabled and the prompts revert to the classic '>>>' of normal Python.
685
685
686
686
687 Directory history
687 Directory history
688 -----------------
688 -----------------
689
689
690 Your history of visited directories is kept in the global list _dh, and
690 Your history of visited directories is kept in the global list _dh, and
691 the magic %cd command can be used to go to any entry in that list. The
691 the magic %cd command can be used to go to any entry in that list. The
692 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
692 %dhist command allows you to view this history. Do ``cd -<TAB>`` to
693 conveniently view the directory history.
693 conveniently view the directory history.
694
694
695
695
696 Automatic parentheses and quotes
696 Automatic parentheses and quotes
697 --------------------------------
697 --------------------------------
698
698
699 These features were adapted from Nathan Gray's LazyPython. They are
699 These features were adapted from Nathan Gray's LazyPython. They are
700 meant to allow less typing for common situations.
700 meant to allow less typing for common situations.
701
701
702
702
703 Automatic parentheses
703 Automatic parentheses
704 +++++++++++++++++++++
704 +++++++++++++++++++++
705
705
706 Callable objects (i.e. functions, methods, etc) can be invoked like this
706 Callable objects (i.e. functions, methods, etc) can be invoked like this
707 (notice the commas between the arguments)::
707 (notice the commas between the arguments)::
708
708
709 In [1]: callable_ob arg1, arg2, arg3
709 In [1]: callable_ob arg1, arg2, arg3
710 ------> callable_ob(arg1, arg2, arg3)
710 ------> callable_ob(arg1, arg2, arg3)
711
711
712 You can force automatic parentheses by using '/' as the first character
712 You can force automatic parentheses by using '/' as the first character
713 of a line. For example::
713 of a line. For example::
714
714
715 In [2]: /globals # becomes 'globals()'
715 In [2]: /globals # becomes 'globals()'
716
716
717 Note that the '/' MUST be the first character on the line! This won't work::
717 Note that the '/' MUST be the first character on the line! This won't work::
718
718
719 In [3]: print /globals # syntax error
719 In [3]: print /globals # syntax error
720
720
721 In most cases the automatic algorithm should work, so you should rarely
721 In most cases the automatic algorithm should work, so you should rarely
722 need to explicitly invoke /. One notable exception is if you are trying
722 need to explicitly invoke /. One notable exception is if you are trying
723 to call a function with a list of tuples as arguments (the parenthesis
723 to call a function with a list of tuples as arguments (the parenthesis
724 will confuse IPython)::
724 will confuse IPython)::
725
725
726 In [4]: zip (1,2,3),(4,5,6) # won't work
726 In [4]: zip (1,2,3),(4,5,6) # won't work
727
727
728 but this will work::
728 but this will work::
729
729
730 In [5]: /zip (1,2,3),(4,5,6)
730 In [5]: /zip (1,2,3),(4,5,6)
731 ------> zip ((1,2,3),(4,5,6))
731 ------> zip ((1,2,3),(4,5,6))
732 Out[5]: [(1, 4), (2, 5), (3, 6)]
732 Out[5]: [(1, 4), (2, 5), (3, 6)]
733
733
734 IPython tells you that it has altered your command line by displaying
734 IPython tells you that it has altered your command line by displaying
735 the new command line preceded by ->. e.g.::
735 the new command line preceded by ->. e.g.::
736
736
737 In [6]: callable list
737 In [6]: callable list
738 ------> callable(list)
738 ------> callable(list)
739
739
740
740
741 Automatic quoting
741 Automatic quoting
742 +++++++++++++++++
742 +++++++++++++++++
743
743
744 You can force automatic quoting of a function's arguments by using ','
744 You can force automatic quoting of a function's arguments by using ','
745 or ';' as the first character of a line. For example::
745 or ';' as the first character of a line. For example::
746
746
747 In [1]: ,my_function /home/me # becomes my_function("/home/me")
747 In [1]: ,my_function /home/me # becomes my_function("/home/me")
748
748
749 If you use ';' the whole argument is quoted as a single string, while ',' splits
749 If you use ';' the whole argument is quoted as a single string, while ',' splits
750 on whitespace::
750 on whitespace::
751
751
752 In [2]: ,my_function a b c # becomes my_function("a","b","c")
752 In [2]: ,my_function a b c # becomes my_function("a","b","c")
753
753
754 In [3]: ;my_function a b c # becomes my_function("a b c")
754 In [3]: ;my_function a b c # becomes my_function("a b c")
755
755
756 Note that the ',' or ';' MUST be the first character on the line! This
756 Note that the ',' or ';' MUST be the first character on the line! This
757 won't work::
757 won't work::
758
758
759 In [4]: x = ,my_function /home/me # syntax error
759 In [4]: x = ,my_function /home/me # syntax error
760
760
761 IPython as your default Python environment
761 IPython as your default Python environment
762 ==========================================
762 ==========================================
763
763
764 Python honors the environment variable PYTHONSTARTUP and will execute at
764 Python honors the environment variable :envvar:`PYTHONSTARTUP` and will
765 startup the file referenced by this variable. If you put the following code at
765 execute at startup the file referenced by this variable. If you put the
766 the end of that file, then IPython will be your working environment anytime you
766 following code at the end of that file, then IPython will be your working
767 start Python::
767 environment anytime you start Python::
768
768
769 from IPython.frontend.terminal.ipapp import launch_new_instance
769 from IPython.frontend.terminal.ipapp import launch_new_instance
770 launch_new_instance()
770 launch_new_instance()
771 raise SystemExit
771 raise SystemExit
772
772
773 The ``raise SystemExit`` is needed to exit Python when
773 The ``raise SystemExit`` is needed to exit Python when
774 it finishes, otherwise you'll be back at the normal Python '>>>'
774 it finishes, otherwise you'll be back at the normal Python '>>>'
775 prompt.
775 prompt.
776
776
777 You'll also need to set the config option
778 ``InteractiveShellApp.exec_PYTHONSTARTUP = False``, otherwise IPython
779 will try to run :envvar:`PYTHONSTARTUP` again, sending it into an
780 infinite loop.
781
777 This is probably useful to developers who manage multiple Python
782 This is probably useful to developers who manage multiple Python
778 versions and don't want to have correspondingly multiple IPython
783 versions and don't want to have correspondingly multiple IPython
779 versions. Note that in this mode, there is no way to pass IPython any
784 versions. Note that in this mode, there is no way to pass IPython any
780 command-line options, as those are trapped first by Python itself.
785 command-line options, as those are trapped first by Python itself.
781
786
782 .. _Embedding:
787 .. _Embedding:
783
788
784 Embedding IPython
789 Embedding IPython
785 =================
790 =================
786
791
787 You can start a regular IPython session with
792 You can start a regular IPython session with
788
793
789 .. sourcecode:: python
794 .. sourcecode:: python
790
795
791 import IPython
796 import IPython
792 IPython.start_ipython()
797 IPython.start_ipython()
793
798
794 at any point in your program. This will load IPython configuration,
799 at any point in your program. This will load IPython configuration,
795 startup files, and everything, just as if it were a normal IPython session.
800 startup files, and everything, just as if it were a normal IPython session.
796 In addition to this,
801 In addition to this,
797 it is possible to embed an IPython instance inside your own Python programs.
802 it is possible to embed an IPython instance inside your own Python programs.
798 This allows you to evaluate dynamically the state of your code,
803 This allows you to evaluate dynamically the state of your code,
799 operate with your variables, analyze them, etc. Note however that
804 operate with your variables, analyze them, etc. Note however that
800 any changes you make to values while in the shell do not propagate back
805 any changes you make to values while in the shell do not propagate back
801 to the running code, so it is safe to modify your values because you
806 to the running code, so it is safe to modify your values because you
802 won't break your code in bizarre ways by doing so.
807 won't break your code in bizarre ways by doing so.
803
808
804 .. note::
809 .. note::
805
810
806 At present, embedding IPython cannot be done from inside IPython.
811 At present, embedding IPython cannot be done from inside IPython.
807 Run the code samples below outside IPython.
812 Run the code samples below outside IPython.
808
813
809 This feature allows you to easily have a fully functional python
814 This feature allows you to easily have a fully functional python
810 environment for doing object introspection anywhere in your code with a
815 environment for doing object introspection anywhere in your code with a
811 simple function call. In some cases a simple print statement is enough,
816 simple function call. In some cases a simple print statement is enough,
812 but if you need to do more detailed analysis of a code fragment this
817 but if you need to do more detailed analysis of a code fragment this
813 feature can be very valuable.
818 feature can be very valuable.
814
819
815 It can also be useful in scientific computing situations where it is
820 It can also be useful in scientific computing situations where it is
816 common to need to do some automatic, computationally intensive part and
821 common to need to do some automatic, computationally intensive part and
817 then stop to look at data, plots, etc.
822 then stop to look at data, plots, etc.
818 Opening an IPython instance will give you full access to your data and
823 Opening an IPython instance will give you full access to your data and
819 functions, and you can resume program execution once you are done with
824 functions, and you can resume program execution once you are done with
820 the interactive part (perhaps to stop again later, as many times as
825 the interactive part (perhaps to stop again later, as many times as
821 needed).
826 needed).
822
827
823 The following code snippet is the bare minimum you need to include in
828 The following code snippet is the bare minimum you need to include in
824 your Python programs for this to work (detailed examples follow later)::
829 your Python programs for this to work (detailed examples follow later)::
825
830
826 from IPython import embed
831 from IPython import embed
827
832
828 embed() # this call anywhere in your program will start IPython
833 embed() # this call anywhere in your program will start IPython
829
834
830 .. note::
835 .. note::
831
836
832 As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
837 As of 0.13, you can embed an IPython *kernel*, for use with qtconsole,
833 etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
838 etc. via ``IPython.embed_kernel()`` instead of ``IPython.embed()``.
834 It should function just the same as regular embed, but you connect
839 It should function just the same as regular embed, but you connect
835 an external frontend rather than IPython starting up in the local
840 an external frontend rather than IPython starting up in the local
836 terminal.
841 terminal.
837
842
838 You can run embedded instances even in code which is itself being run at
843 You can run embedded instances even in code which is itself being run at
839 the IPython interactive prompt with '%run <filename>'. Since it's easy
844 the IPython interactive prompt with '%run <filename>'. Since it's easy
840 to get lost as to where you are (in your top-level IPython or in your
845 to get lost as to where you are (in your top-level IPython or in your
841 embedded one), it's a good idea in such cases to set the in/out prompts
846 embedded one), it's a good idea in such cases to set the in/out prompts
842 to something different for the embedded instances. The code examples
847 to something different for the embedded instances. The code examples
843 below illustrate this.
848 below illustrate this.
844
849
845 You can also have multiple IPython instances in your program and open
850 You can also have multiple IPython instances in your program and open
846 them separately, for example with different options for data
851 them separately, for example with different options for data
847 presentation. If you close and open the same instance multiple times,
852 presentation. If you close and open the same instance multiple times,
848 its prompt counters simply continue from each execution to the next.
853 its prompt counters simply continue from each execution to the next.
849
854
850 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
855 Please look at the docstrings in the :mod:`~IPython.frontend.terminal.embed`
851 module for more details on the use of this system.
856 module for more details on the use of this system.
852
857
853 The following sample file illustrating how to use the embedding
858 The following sample file illustrating how to use the embedding
854 functionality is provided in the examples directory as example-embed.py.
859 functionality is provided in the examples directory as example-embed.py.
855 It should be fairly self-explanatory:
860 It should be fairly self-explanatory:
856
861
857 .. literalinclude:: ../../../examples/core/example-embed.py
862 .. literalinclude:: ../../../examples/core/example-embed.py
858 :language: python
863 :language: python
859
864
860 Once you understand how the system functions, you can use the following
865 Once you understand how the system functions, you can use the following
861 code fragments in your programs which are ready for cut and paste:
866 code fragments in your programs which are ready for cut and paste:
862
867
863 .. literalinclude:: ../../../examples/core/example-embed-short.py
868 .. literalinclude:: ../../../examples/core/example-embed-short.py
864 :language: python
869 :language: python
865
870
866 Using the Python debugger (pdb)
871 Using the Python debugger (pdb)
867 ===============================
872 ===============================
868
873
869 Running entire programs via pdb
874 Running entire programs via pdb
870 -------------------------------
875 -------------------------------
871
876
872 pdb, the Python debugger, is a powerful interactive debugger which
877 pdb, the Python debugger, is a powerful interactive debugger which
873 allows you to step through code, set breakpoints, watch variables,
878 allows you to step through code, set breakpoints, watch variables,
874 etc. IPython makes it very easy to start any script under the control
879 etc. IPython makes it very easy to start any script under the control
875 of pdb, regardless of whether you have wrapped it into a 'main()'
880 of pdb, regardless of whether you have wrapped it into a 'main()'
876 function or not. For this, simply type '%run -d myscript' at an
881 function or not. For this, simply type '%run -d myscript' at an
877 IPython prompt. See the %run command's documentation (via '%run?' or
882 IPython prompt. See the %run command's documentation (via '%run?' or
878 in Sec. magic_ for more details, including how to control where pdb
883 in Sec. magic_ for more details, including how to control where pdb
879 will stop execution first.
884 will stop execution first.
880
885
881 For more information on the use of the pdb debugger, read the included
886 For more information on the use of the pdb debugger, read the included
882 pdb.doc file (part of the standard Python distribution). On a stock
887 pdb.doc file (part of the standard Python distribution). On a stock
883 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
888 Linux system it is located at /usr/lib/python2.3/pdb.doc, but the
884 easiest way to read it is by using the help() function of the pdb module
889 easiest way to read it is by using the help() function of the pdb module
885 as follows (in an IPython prompt)::
890 as follows (in an IPython prompt)::
886
891
887 In [1]: import pdb
892 In [1]: import pdb
888 In [2]: pdb.help()
893 In [2]: pdb.help()
889
894
890 This will load the pdb.doc document in a file viewer for you automatically.
895 This will load the pdb.doc document in a file viewer for you automatically.
891
896
892
897
893 Automatic invocation of pdb on exceptions
898 Automatic invocation of pdb on exceptions
894 -----------------------------------------
899 -----------------------------------------
895
900
896 IPython, if started with the ``--pdb`` option (or if the option is set in
901 IPython, if started with the ``--pdb`` option (or if the option is set in
897 your config file) can call the Python pdb debugger every time your code
902 your config file) can call the Python pdb debugger every time your code
898 triggers an uncaught exception. This feature
903 triggers an uncaught exception. This feature
899 can also be toggled at any time with the %pdb magic command. This can be
904 can also be toggled at any time with the %pdb magic command. This can be
900 extremely useful in order to find the origin of subtle bugs, because pdb
905 extremely useful in order to find the origin of subtle bugs, because pdb
901 opens up at the point in your code which triggered the exception, and
906 opens up at the point in your code which triggered the exception, and
902 while your program is at this point 'dead', all the data is still
907 while your program is at this point 'dead', all the data is still
903 available and you can walk up and down the stack frame and understand
908 available and you can walk up and down the stack frame and understand
904 the origin of the problem.
909 the origin of the problem.
905
910
906 Furthermore, you can use these debugging facilities both with the
911 Furthermore, you can use these debugging facilities both with the
907 embedded IPython mode and without IPython at all. For an embedded shell
912 embedded IPython mode and without IPython at all. For an embedded shell
908 (see sec. Embedding_), simply call the constructor with
913 (see sec. Embedding_), simply call the constructor with
909 ``--pdb`` in the argument string and pdb will automatically be called if an
914 ``--pdb`` in the argument string and pdb will automatically be called if an
910 uncaught exception is triggered by your code.
915 uncaught exception is triggered by your code.
911
916
912 For stand-alone use of the feature in your programs which do not use
917 For stand-alone use of the feature in your programs which do not use
913 IPython at all, put the following lines toward the top of your 'main'
918 IPython at all, put the following lines toward the top of your 'main'
914 routine::
919 routine::
915
920
916 import sys
921 import sys
917 from IPython.core import ultratb
922 from IPython.core import ultratb
918 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
923 sys.excepthook = ultratb.FormattedTB(mode='Verbose',
919 color_scheme='Linux', call_pdb=1)
924 color_scheme='Linux', call_pdb=1)
920
925
921 The mode keyword can be either 'Verbose' or 'Plain', giving either very
926 The mode keyword can be either 'Verbose' or 'Plain', giving either very
922 detailed or normal tracebacks respectively. The color_scheme keyword can
927 detailed or normal tracebacks respectively. The color_scheme keyword can
923 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
928 be one of 'NoColor', 'Linux' (default) or 'LightBG'. These are the same
924 options which can be set in IPython with ``--colors`` and ``--xmode``.
929 options which can be set in IPython with ``--colors`` and ``--xmode``.
925
930
926 This will give any of your programs detailed, colored tracebacks with
931 This will give any of your programs detailed, colored tracebacks with
927 automatic invocation of pdb.
932 automatic invocation of pdb.
928
933
929
934
930 Extensions for syntax processing
935 Extensions for syntax processing
931 ================================
936 ================================
932
937
933 This isn't for the faint of heart, because the potential for breaking
938 This isn't for the faint of heart, because the potential for breaking
934 things is quite high. But it can be a very powerful and useful feature.
939 things is quite high. But it can be a very powerful and useful feature.
935 In a nutshell, you can redefine the way IPython processes the user input
940 In a nutshell, you can redefine the way IPython processes the user input
936 line to accept new, special extensions to the syntax without needing to
941 line to accept new, special extensions to the syntax without needing to
937 change any of IPython's own code.
942 change any of IPython's own code.
938
943
939 In the IPython/extensions directory you will find some examples
944 In the IPython/extensions directory you will find some examples
940 supplied, which we will briefly describe now. These can be used 'as is'
945 supplied, which we will briefly describe now. These can be used 'as is'
941 (and both provide very useful functionality), or you can use them as a
946 (and both provide very useful functionality), or you can use them as a
942 starting point for writing your own extensions.
947 starting point for writing your own extensions.
943
948
944 .. _pasting_with_prompts:
949 .. _pasting_with_prompts:
945
950
946 Pasting of code starting with Python or IPython prompts
951 Pasting of code starting with Python or IPython prompts
947 -------------------------------------------------------
952 -------------------------------------------------------
948
953
949 IPython is smart enough to filter out input prompts, be they plain Python ones
954 IPython is smart enough to filter out input prompts, be they plain Python ones
950 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
955 (``>>>`` and ``...``) or IPython ones (``In [N]:`` and ``...:``). You can
951 therefore copy and paste from existing interactive sessions without worry.
956 therefore copy and paste from existing interactive sessions without worry.
952
957
953 The following is a 'screenshot' of how things work, copying an example from the
958 The following is a 'screenshot' of how things work, copying an example from the
954 standard Python tutorial::
959 standard Python tutorial::
955
960
956 In [1]: >>> # Fibonacci series:
961 In [1]: >>> # Fibonacci series:
957
962
958 In [2]: ... # the sum of two elements defines the next
963 In [2]: ... # the sum of two elements defines the next
959
964
960 In [3]: ... a, b = 0, 1
965 In [3]: ... a, b = 0, 1
961
966
962 In [4]: >>> while b < 10:
967 In [4]: >>> while b < 10:
963 ...: ... print b
968 ...: ... print b
964 ...: ... a, b = b, a+b
969 ...: ... a, b = b, a+b
965 ...:
970 ...:
966 1
971 1
967 1
972 1
968 2
973 2
969 3
974 3
970 5
975 5
971 8
976 8
972
977
973 And pasting from IPython sessions works equally well::
978 And pasting from IPython sessions works equally well::
974
979
975 In [1]: In [5]: def f(x):
980 In [1]: In [5]: def f(x):
976 ...: ...: "A simple function"
981 ...: ...: "A simple function"
977 ...: ...: return x**2
982 ...: ...: return x**2
978 ...: ...:
983 ...: ...:
979
984
980 In [2]: f(3)
985 In [2]: f(3)
981 Out[2]: 9
986 Out[2]: 9
982
987
983 .. _gui_support:
988 .. _gui_support:
984
989
985 GUI event loop support
990 GUI event loop support
986 ======================
991 ======================
987
992
988 .. versionadded:: 0.11
993 .. versionadded:: 0.11
989 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
994 The ``%gui`` magic and :mod:`IPython.lib.inputhook`.
990
995
991 IPython has excellent support for working interactively with Graphical User
996 IPython has excellent support for working interactively with Graphical User
992 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
997 Interface (GUI) toolkits, such as wxPython, PyQt4/PySide, PyGTK and Tk. This is
993 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
998 implemented using Python's builtin ``PyOSInputHook`` hook. This implementation
994 is extremely robust compared to our previous thread-based version. The
999 is extremely robust compared to our previous thread-based version. The
995 advantages of this are:
1000 advantages of this are:
996
1001
997 * GUIs can be enabled and disabled dynamically at runtime.
1002 * GUIs can be enabled and disabled dynamically at runtime.
998 * The active GUI can be switched dynamically at runtime.
1003 * The active GUI can be switched dynamically at runtime.
999 * In some cases, multiple GUIs can run simultaneously with no problems.
1004 * In some cases, multiple GUIs can run simultaneously with no problems.
1000 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
1005 * There is a developer API in :mod:`IPython.lib.inputhook` for customizing
1001 all of these things.
1006 all of these things.
1002
1007
1003 For users, enabling GUI event loop integration is simple. You simple use the
1008 For users, enabling GUI event loop integration is simple. You simple use the
1004 ``%gui`` magic as follows::
1009 ``%gui`` magic as follows::
1005
1010
1006 %gui [GUINAME]
1011 %gui [GUINAME]
1007
1012
1008 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
1013 With no arguments, ``%gui`` removes all GUI support. Valid ``GUINAME``
1009 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
1014 arguments are ``wx``, ``qt``, ``gtk`` and ``tk``.
1010
1015
1011 Thus, to use wxPython interactively and create a running :class:`wx.App`
1016 Thus, to use wxPython interactively and create a running :class:`wx.App`
1012 object, do::
1017 object, do::
1013
1018
1014 %gui wx
1019 %gui wx
1015
1020
1016 For information on IPython's matplotlib_ integration (and the ``matplotlib``
1021 For information on IPython's matplotlib_ integration (and the ``matplotlib``
1017 mode) see :ref:`this section <matplotlib_support>`.
1022 mode) see :ref:`this section <matplotlib_support>`.
1018
1023
1019 For developers that want to use IPython's GUI event loop integration in the
1024 For developers that want to use IPython's GUI event loop integration in the
1020 form of a library, these capabilities are exposed in library form in the
1025 form of a library, these capabilities are exposed in library form in the
1021 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
1026 :mod:`IPython.lib.inputhook` and :mod:`IPython.lib.guisupport` modules.
1022 Interested developers should see the module docstrings for more information,
1027 Interested developers should see the module docstrings for more information,
1023 but there are a few points that should be mentioned here.
1028 but there are a few points that should be mentioned here.
1024
1029
1025 First, the ``PyOSInputHook`` approach only works in command line settings
1030 First, the ``PyOSInputHook`` approach only works in command line settings
1026 where readline is activated. The integration with various eventloops
1031 where readline is activated. The integration with various eventloops
1027 is handled somewhat differently (and more simply) when using the standalone
1032 is handled somewhat differently (and more simply) when using the standalone
1028 kernel, as in the qtconsole and notebook.
1033 kernel, as in the qtconsole and notebook.
1029
1034
1030 Second, when using the ``PyOSInputHook`` approach, a GUI application should
1035 Second, when using the ``PyOSInputHook`` approach, a GUI application should
1031 *not* start its event loop. Instead all of this is handled by the
1036 *not* start its event loop. Instead all of this is handled by the
1032 ``PyOSInputHook``. This means that applications that are meant to be used both
1037 ``PyOSInputHook``. This means that applications that are meant to be used both
1033 in IPython and as standalone apps need to have special code to detects how the
1038 in IPython and as standalone apps need to have special code to detects how the
1034 application is being run. We highly recommend using IPython's support for this.
1039 application is being run. We highly recommend using IPython's support for this.
1035 Since the details vary slightly between toolkits, we point you to the various
1040 Since the details vary slightly between toolkits, we point you to the various
1036 examples in our source directory :file:`examples/lib` that demonstrate
1041 examples in our source directory :file:`examples/lib` that demonstrate
1037 these capabilities.
1042 these capabilities.
1038
1043
1039 Third, unlike previous versions of IPython, we no longer "hijack" (replace
1044 Third, unlike previous versions of IPython, we no longer "hijack" (replace
1040 them with no-ops) the event loops. This is done to allow applications that
1045 them with no-ops) the event loops. This is done to allow applications that
1041 actually need to run the real event loops to do so. This is often needed to
1046 actually need to run the real event loops to do so. This is often needed to
1042 process pending events at critical points.
1047 process pending events at critical points.
1043
1048
1044 Finally, we also have a number of examples in our source directory
1049 Finally, we also have a number of examples in our source directory
1045 :file:`examples/lib` that demonstrate these capabilities.
1050 :file:`examples/lib` that demonstrate these capabilities.
1046
1051
1047 PyQt and PySide
1052 PyQt and PySide
1048 ---------------
1053 ---------------
1049
1054
1050 .. attempt at explanation of the complete mess that is Qt support
1055 .. attempt at explanation of the complete mess that is Qt support
1051
1056
1052 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
1057 When you use ``--gui=qt`` or ``--matplotlib=qt``, IPython can work with either
1053 PyQt4 or PySide. There are three options for configuration here, because
1058 PyQt4 or PySide. There are three options for configuration here, because
1054 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
1059 PyQt4 has two APIs for QString and QVariant - v1, which is the default on
1055 Python 2, and the more natural v2, which is the only API supported by PySide.
1060 Python 2, and the more natural v2, which is the only API supported by PySide.
1056 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
1061 v2 is also the default for PyQt4 on Python 3. IPython's code for the QtConsole
1057 uses v2, but you can still use any interface in your code, since the
1062 uses v2, but you can still use any interface in your code, since the
1058 Qt frontend is in a different process.
1063 Qt frontend is in a different process.
1059
1064
1060 The default will be to import PyQt4 without configuration of the APIs, thus
1065 The default will be to import PyQt4 without configuration of the APIs, thus
1061 matching what most applications would expect. It will fall back of PySide if
1066 matching what most applications would expect. It will fall back of PySide if
1062 PyQt4 is unavailable.
1067 PyQt4 is unavailable.
1063
1068
1064 If specified, IPython will respect the environment variable ``QT_API`` used
1069 If specified, IPython will respect the environment variable ``QT_API`` used
1065 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
1070 by ETS. ETS 4.0 also works with both PyQt4 and PySide, but it requires
1066 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
1071 PyQt4 to use its v2 API. So if ``QT_API=pyside`` PySide will be used,
1067 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
1072 and if ``QT_API=pyqt`` then PyQt4 will be used *with the v2 API* for
1068 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
1073 QString and QVariant, so ETS codes like MayaVi will also work with IPython.
1069
1074
1070 If you launch IPython in matplotlib mode with ``ipython --matplotlib=qt``,
1075 If you launch IPython in matplotlib mode with ``ipython --matplotlib=qt``,
1071 then IPython will ask matplotlib which Qt library to use (only if QT_API is
1076 then IPython will ask matplotlib which Qt library to use (only if QT_API is
1072 *not set*), via the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or
1077 *not set*), via the 'backend.qt4' rcParam. If matplotlib is version 1.0.1 or
1073 older, then IPython will always use PyQt4 without setting the v2 APIs, since
1078 older, then IPython will always use PyQt4 without setting the v2 APIs, since
1074 neither v2 PyQt nor PySide work.
1079 neither v2 PyQt nor PySide work.
1075
1080
1076 .. warning::
1081 .. warning::
1077
1082
1078 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
1083 Note that this means for ETS 4 to work with PyQt4, ``QT_API`` *must* be set
1079 to work with IPython's qt integration, because otherwise PyQt4 will be
1084 to work with IPython's qt integration, because otherwise PyQt4 will be
1080 loaded in an incompatible mode.
1085 loaded in an incompatible mode.
1081
1086
1082 It also means that you must *not* have ``QT_API`` set if you want to
1087 It also means that you must *not* have ``QT_API`` set if you want to
1083 use ``--gui=qt`` with code that requires PyQt4 API v1.
1088 use ``--gui=qt`` with code that requires PyQt4 API v1.
1084
1089
1085
1090
1086 .. _matplotlib_support:
1091 .. _matplotlib_support:
1087
1092
1088 Plotting with matplotlib
1093 Plotting with matplotlib
1089 ========================
1094 ========================
1090
1095
1091 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
1096 matplotlib_ provides high quality 2D and 3D plotting for Python. matplotlib_
1092 can produce plots on screen using a variety of GUI toolkits, including Tk,
1097 can produce plots on screen using a variety of GUI toolkits, including Tk,
1093 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
1098 PyGTK, PyQt4 and wxPython. It also provides a number of commands useful for
1094 scientific computing, all with a syntax compatible with that of the popular
1099 scientific computing, all with a syntax compatible with that of the popular
1095 Matlab program.
1100 Matlab program.
1096
1101
1097 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
1102 To start IPython with matplotlib support, use the ``--matplotlib`` switch. If
1098 IPython is already running, you can run the ``%matplotlib`` magic. If no
1103 IPython is already running, you can run the ``%matplotlib`` magic. If no
1099 arguments are given, IPython will automatically detect your choice of
1104 arguments are given, IPython will automatically detect your choice of
1100 matplotlib backend. You can also request a specific backend with
1105 matplotlib backend. You can also request a specific backend with
1101 ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx',
1106 ``%matplotlib backend``, where ``backend`` must be one of: 'tk', 'qt', 'wx',
1102 'gtk', 'osx'. In the web notebook and Qt console, 'inline' is also a valid
1107 'gtk', 'osx'. In the web notebook and Qt console, 'inline' is also a valid
1103 backend value, which produces static figures inlined inside the application
1108 backend value, which produces static figures inlined inside the application
1104 window instead of matplotlib's interactive figures that live in separate
1109 window instead of matplotlib's interactive figures that live in separate
1105 windows.
1110 windows.
1106
1111
1107 .. _interactive_demos:
1112 .. _interactive_demos:
1108
1113
1109 Interactive demos with IPython
1114 Interactive demos with IPython
1110 ==============================
1115 ==============================
1111
1116
1112 IPython ships with a basic system for running scripts interactively in
1117 IPython ships with a basic system for running scripts interactively in
1113 sections, useful when presenting code to audiences. A few tags embedded
1118 sections, useful when presenting code to audiences. A few tags embedded
1114 in comments (so that the script remains valid Python code) divide a file
1119 in comments (so that the script remains valid Python code) divide a file
1115 into separate blocks, and the demo can be run one block at a time, with
1120 into separate blocks, and the demo can be run one block at a time, with
1116 IPython printing (with syntax highlighting) the block before executing
1121 IPython printing (with syntax highlighting) the block before executing
1117 it, and returning to the interactive prompt after each block. The
1122 it, and returning to the interactive prompt after each block. The
1118 interactive namespace is updated after each block is run with the
1123 interactive namespace is updated after each block is run with the
1119 contents of the demo's namespace.
1124 contents of the demo's namespace.
1120
1125
1121 This allows you to show a piece of code, run it and then execute
1126 This allows you to show a piece of code, run it and then execute
1122 interactively commands based on the variables just created. Once you
1127 interactively commands based on the variables just created. Once you
1123 want to continue, you simply execute the next block of the demo. The
1128 want to continue, you simply execute the next block of the demo. The
1124 following listing shows the markup necessary for dividing a script into
1129 following listing shows the markup necessary for dividing a script into
1125 sections for execution as a demo:
1130 sections for execution as a demo:
1126
1131
1127 .. literalinclude:: ../../../examples/lib/example-demo.py
1132 .. literalinclude:: ../../../examples/lib/example-demo.py
1128 :language: python
1133 :language: python
1129
1134
1130 In order to run a file as a demo, you must first make a Demo object out
1135 In order to run a file as a demo, you must first make a Demo object out
1131 of it. If the file is named myscript.py, the following code will make a
1136 of it. If the file is named myscript.py, the following code will make a
1132 demo::
1137 demo::
1133
1138
1134 from IPython.lib.demo import Demo
1139 from IPython.lib.demo import Demo
1135
1140
1136 mydemo = Demo('myscript.py')
1141 mydemo = Demo('myscript.py')
1137
1142
1138 This creates the mydemo object, whose blocks you run one at a time by
1143 This creates the mydemo object, whose blocks you run one at a time by
1139 simply calling the object with no arguments. If you have autocall active
1144 simply calling the object with no arguments. If you have autocall active
1140 in IPython (the default), all you need to do is type::
1145 in IPython (the default), all you need to do is type::
1141
1146
1142 mydemo
1147 mydemo
1143
1148
1144 and IPython will call it, executing each block. Demo objects can be
1149 and IPython will call it, executing each block. Demo objects can be
1145 restarted, you can move forward or back skipping blocks, re-execute the
1150 restarted, you can move forward or back skipping blocks, re-execute the
1146 last block, etc. Simply use the Tab key on a demo object to see its
1151 last block, etc. Simply use the Tab key on a demo object to see its
1147 methods, and call '?' on them to see their docstrings for more usage
1152 methods, and call '?' on them to see their docstrings for more usage
1148 details. In addition, the demo module itself contains a comprehensive
1153 details. In addition, the demo module itself contains a comprehensive
1149 docstring, which you can access via::
1154 docstring, which you can access via::
1150
1155
1151 from IPython.lib import demo
1156 from IPython.lib import demo
1152
1157
1153 demo?
1158 demo?
1154
1159
1155 Limitations: It is important to note that these demos are limited to
1160 Limitations: It is important to note that these demos are limited to
1156 fairly simple uses. In particular, you cannot break up sections within
1161 fairly simple uses. In particular, you cannot break up sections within
1157 indented code (loops, if statements, function definitions, etc.)
1162 indented code (loops, if statements, function definitions, etc.)
1158 Supporting something like this would basically require tracking the
1163 Supporting something like this would basically require tracking the
1159 internal execution state of the Python interpreter, so only top-level
1164 internal execution state of the Python interpreter, so only top-level
1160 divisions are allowed. If you want to be able to open an IPython
1165 divisions are allowed. If you want to be able to open an IPython
1161 instance at an arbitrary point in a program, you can use IPython's
1166 instance at an arbitrary point in a program, you can use IPython's
1162 embedding facilities, see :func:`IPython.embed` for details.
1167 embedding facilities, see :func:`IPython.embed` for details.
1163
1168
1164 .. include:: ../links.txt
1169 .. include:: ../links.txt
General Comments 0
You need to be logged in to leave comments. Login now