##// END OF EJS Templates
First semi-complete support for -pylab and %pylab....
Fernando Perez -
Show More
@@ -0,0 +1,146 b''
1 # -*- coding: utf-8 -*-
2 """Pylab (matplotlib) support utilities.
3
4 Authors
5 -------
6 Fernando Perez.
7 """
8
9 #-----------------------------------------------------------------------------
10 # Copyright (C) 2009 The IPython Development Team
11 #
12 # Distributed under the terms of the BSD License. The full license is in
13 # the file COPYING, distributed as part of this software.
14 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16 # Imports
17 #-----------------------------------------------------------------------------
18 from IPython.utils.genutils import flag_calls
19
20 #-----------------------------------------------------------------------------
21 # Main classes and functions
22 #-----------------------------------------------------------------------------
23
24 def pylab_activate(user_ns, gui=None, import_all=True):
25 """Activate pylab mode in the user's namespace.
26
27 Loads and initializes numpy, matplotlib and friends for interactive use.
28
29 Parameters
30 ----------
31 user_ns : dict
32 Namespace where the imports will occur.
33
34 gui : optional, string
35 A valid gui name following the conventions of the %gui magic.
36
37 import_all : optional, boolean
38 If true, an 'import *' is done from numpy and pylab.
39
40 Returns
41 -------
42 The actual gui used (if not given as input, it was obtained from matplotlib
43 itself, and will be needed next to configure IPython's gui integration.
44 """
45
46 # Initialize matplotlib to interactive mode always
47 import matplotlib
48
49 # If user specifies a GUI, that dictates the backend, otherwise we read the
50 # user's mpl default from the mpl rc structure
51 g2b = {'tk': 'TkAgg',
52 'gtk': 'GTKAgg',
53 'wx': 'WXAgg',
54 'qt': 'Qt4Agg', # qt3 not supported
55 'qt4': 'Qt4Agg' }
56
57 if gui:
58 # select backend based on requested gui
59 backend = g2b[gui]
60 else:
61 backend = matplotlib.rcParams['backend']
62 # In this case, we need to find what the appropriate gui selection call
63 # should be for IPython, so we can activate inputhook accordingly
64 b2g = dict(zip(g2b.values(),g2b.keys()))
65 gui = b2g[backend]
66
67 # We must set the desired backend before importing pylab
68 matplotlib.use(backend)
69
70 # This must be imported last in the matplotlib series, after
71 # backend/interactivity choices have been made
72 import matplotlib.pylab as pylab
73
74 # XXX For now leave this commented out, but depending on discussions with
75 # mpl-dev, we may be able to allow interactive switching...
76 #import matplotlib.pyplot
77 #matplotlib.pyplot.switch_backend(backend)
78
79 pylab.show._needmain = False
80 # We need to detect at runtime whether show() is called by the user.
81 # For this, we wrap it into a decorator which adds a 'called' flag.
82 pylab.draw_if_interactive = flag_calls(pylab.draw_if_interactive)
83
84 # Import numpy as np/pyplot as plt are conventions we're trying to
85 # somewhat standardize on. Making them available to users by default
86 # will greatly help this.
87 exec ("import numpy\n"
88 "import matplotlib\n"
89 "from matplotlib import pylab, mlab, pyplot\n"
90 "np = numpy\n"
91 "plt = pyplot\n"
92 ) in user_ns
93
94 if import_all:
95 exec("from matplotlib.pylab import *\n"
96 "from numpy import *\n") in user_ns
97
98 matplotlib.interactive(True)
99
100 print """
101 Welcome to pylab, a matplotlib-based Python environment.
102 Backend in use: %s
103 For more information, type 'help(pylab)'.""" % backend
104
105 return gui
106
107 # We need a little factory function here to create the closure where
108 # safe_execfile can live.
109 def mpl_runner(safe_execfile):
110 """Factory to return a matplotlib-enabled runner for %run.
111
112 Parameters
113 ----------
114 safe_execfile : function
115 This must be a function with the same interface as the
116 :meth:`safe_execfile` method of IPython.
117
118 Returns
119 -------
120 A function suitable for use as the ``runner`` argument of the %run magic
121 function.
122 """
123
124 def mpl_execfile(fname,*where,**kw):
125 """matplotlib-aware wrapper around safe_execfile.
126
127 Its interface is identical to that of the :func:`execfile` builtin.
128
129 This is ultimately a call to execfile(), but wrapped in safeties to
130 properly handle interactive rendering."""
131
132 import matplotlib
133 import matplotlib.pylab as pylab
134
135 #print '*** Matplotlib runner ***' # dbg
136 # turn off rendering until end of script
137 is_interactive = matplotlib.rcParams['interactive']
138 matplotlib.interactive(False)
139 safe_execfile(fname,*where,**kw)
140 matplotlib.interactive(is_interactive)
141 # make rendering call now, if the user tried to do it
142 if pylab.draw_if_interactive.called:
143 pylab.draw()
144 pylab.draw_if_interactive.called = False
145
146 return mpl_execfile
@@ -1,565 +1,555 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # encoding: utf-8
3 """
3 """
4 The :class:`~IPython.core.application.Application` object for the command
4 The :class:`~IPython.core.application.Application` object for the command
5 line :command:`ipython` program.
5 line :command:`ipython` program.
6
6
7 Authors:
7 Authors:
8
8
9 * Brian Granger
9 * Brian Granger
10 * Fernando Perez
10 * Fernando Perez
11
11
12 Notes
12 Notes
13 -----
13 -----
14 """
14 """
15
15
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17 # Copyright (C) 2008-2009 The IPython Development Team
17 # Copyright (C) 2008-2009 The IPython Development Team
18 #
18 #
19 # Distributed under the terms of the BSD License. The full license is in
19 # Distributed under the terms of the BSD License. The full license is in
20 # the file COPYING, distributed as part of this software.
20 # the file COPYING, distributed as part of this software.
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 #-----------------------------------------------------------------------------
23 #-----------------------------------------------------------------------------
24 # Imports
24 # Imports
25 #-----------------------------------------------------------------------------
25 #-----------------------------------------------------------------------------
26
26
27 import logging
27 import logging
28 import os
28 import os
29 import sys
29 import sys
30 import warnings
31
30
32 from IPython.core.application import Application, BaseAppArgParseConfigLoader
33 from IPython.core import release
31 from IPython.core import release
32 from IPython.core.application import Application, BaseAppArgParseConfigLoader
33 from IPython.core.error import UsageError
34 from IPython.core.iplib import InteractiveShell
34 from IPython.core.iplib import InteractiveShell
35 from IPython.core.pylabtools import pylab_activate
35 from IPython.config.loader import (
36 from IPython.config.loader import (
36 NoConfigDefault,
37 NoConfigDefault,
37 Config,
38 Config,
38 PyFileConfigLoader
39 PyFileConfigLoader
39 )
40 )
40
41 from IPython.lib import inputhook
41 from IPython.lib import inputhook
42
43 from IPython.utils.genutils import filefind, get_ipython_dir
42 from IPython.utils.genutils import filefind, get_ipython_dir
44
43
45 #-----------------------------------------------------------------------------
44 #-----------------------------------------------------------------------------
46 # Utilities and helpers
45 # Utilities and helpers
47 #-----------------------------------------------------------------------------
46 #-----------------------------------------------------------------------------
48
47
49
50 ipython_desc = """
48 ipython_desc = """
51 A Python shell with automatic history (input and output), dynamic object
49 A Python shell with automatic history (input and output), dynamic object
52 introspection, easier configuration, command completion, access to the system
50 introspection, easier configuration, command completion, access to the system
53 shell and more.
51 shell and more.
54 """
52 """
55
53
56 def pylab_warning():
57 msg = """
58
59 IPython's -pylab mode has been disabled until matplotlib supports this version
60 of IPython. This version of IPython has greatly improved GUI integration that
61 matplotlib will soon be able to take advantage of. This will eventually
62 result in greater stability and a richer API for matplotlib under IPython.
63 However during this transition, you will either need to use an older version
64 of IPython, or do the following to use matplotlib interactively::
65
66 import matplotlib
67 matplotlib.interactive(True)
68 matplotlib.use('wxagg') # adjust for your backend
69 %gui -a wx # adjust for your GUI
70 from matplotlib import pyplot as plt
71
72 See the %gui magic for information on the new interface.
73 """
74 warnings.warn(msg, category=DeprecationWarning, stacklevel=1)
75
76
77 #-----------------------------------------------------------------------------
54 #-----------------------------------------------------------------------------
78 # Main classes and functions
55 # Main classes and functions
79 #-----------------------------------------------------------------------------
56 #-----------------------------------------------------------------------------
80
57
81 cl_args = (
58 cl_args = (
82 (('--autocall',), dict(
59 (('--autocall',), dict(
83 type=int, dest='InteractiveShell.autocall', default=NoConfigDefault,
60 type=int, dest='InteractiveShell.autocall', default=NoConfigDefault,
84 help='Set the autocall value (0,1,2).',
61 help='Set the autocall value (0,1,2).',
85 metavar='InteractiveShell.autocall')
62 metavar='InteractiveShell.autocall')
86 ),
63 ),
87 (('--autoindent',), dict(
64 (('--autoindent',), dict(
88 action='store_true', dest='InteractiveShell.autoindent', default=NoConfigDefault,
65 action='store_true', dest='InteractiveShell.autoindent', default=NoConfigDefault,
89 help='Turn on autoindenting.')
66 help='Turn on autoindenting.')
90 ),
67 ),
91 (('--no-autoindent',), dict(
68 (('--no-autoindent',), dict(
92 action='store_false', dest='InteractiveShell.autoindent', default=NoConfigDefault,
69 action='store_false', dest='InteractiveShell.autoindent', default=NoConfigDefault,
93 help='Turn off autoindenting.')
70 help='Turn off autoindenting.')
94 ),
71 ),
95 (('--automagic',), dict(
72 (('--automagic',), dict(
96 action='store_true', dest='InteractiveShell.automagic', default=NoConfigDefault,
73 action='store_true', dest='InteractiveShell.automagic', default=NoConfigDefault,
97 help='Turn on the auto calling of magic commands.')
74 help='Turn on the auto calling of magic commands.')
98 ),
75 ),
99 (('--no-automagic',), dict(
76 (('--no-automagic',), dict(
100 action='store_false', dest='InteractiveShell.automagic', default=NoConfigDefault,
77 action='store_false', dest='InteractiveShell.automagic', default=NoConfigDefault,
101 help='Turn off the auto calling of magic commands.')
78 help='Turn off the auto calling of magic commands.')
102 ),
79 ),
103 (('--autoedit-syntax',), dict(
80 (('--autoedit-syntax',), dict(
104 action='store_true', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
81 action='store_true', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
105 help='Turn on auto editing of files with syntax errors.')
82 help='Turn on auto editing of files with syntax errors.')
106 ),
83 ),
107 (('--no-autoedit-syntax',), dict(
84 (('--no-autoedit-syntax',), dict(
108 action='store_false', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
85 action='store_false', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault,
109 help='Turn off auto editing of files with syntax errors.')
86 help='Turn off auto editing of files with syntax errors.')
110 ),
87 ),
111 (('--banner',), dict(
88 (('--banner',), dict(
112 action='store_true', dest='Global.display_banner', default=NoConfigDefault,
89 action='store_true', dest='Global.display_banner', default=NoConfigDefault,
113 help='Display a banner upon starting IPython.')
90 help='Display a banner upon starting IPython.')
114 ),
91 ),
115 (('--no-banner',), dict(
92 (('--no-banner',), dict(
116 action='store_false', dest='Global.display_banner', default=NoConfigDefault,
93 action='store_false', dest='Global.display_banner', default=NoConfigDefault,
117 help="Don't display a banner upon starting IPython.")
94 help="Don't display a banner upon starting IPython.")
118 ),
95 ),
119 (('--cache-size',), dict(
96 (('--cache-size',), dict(
120 type=int, dest='InteractiveShell.cache_size', default=NoConfigDefault,
97 type=int, dest='InteractiveShell.cache_size', default=NoConfigDefault,
121 help="Set the size of the output cache.",
98 help="Set the size of the output cache.",
122 metavar='InteractiveShell.cache_size')
99 metavar='InteractiveShell.cache_size')
123 ),
100 ),
124 (('--classic',), dict(
101 (('--classic',), dict(
125 action='store_true', dest='Global.classic', default=NoConfigDefault,
102 action='store_true', dest='Global.classic', default=NoConfigDefault,
126 help="Gives IPython a similar feel to the classic Python prompt.")
103 help="Gives IPython a similar feel to the classic Python prompt.")
127 ),
104 ),
128 (('--colors',), dict(
105 (('--colors',), dict(
129 type=str, dest='InteractiveShell.colors', default=NoConfigDefault,
106 type=str, dest='InteractiveShell.colors', default=NoConfigDefault,
130 help="Set the color scheme (NoColor, Linux, and LightBG).",
107 help="Set the color scheme (NoColor, Linux, and LightBG).",
131 metavar='InteractiveShell.colors')
108 metavar='InteractiveShell.colors')
132 ),
109 ),
133 (('--color-info',), dict(
110 (('--color-info',), dict(
134 action='store_true', dest='InteractiveShell.color_info', default=NoConfigDefault,
111 action='store_true', dest='InteractiveShell.color_info', default=NoConfigDefault,
135 help="Enable using colors for info related things.")
112 help="Enable using colors for info related things.")
136 ),
113 ),
137 (('--no-color-info',), dict(
114 (('--no-color-info',), dict(
138 action='store_false', dest='InteractiveShell.color_info', default=NoConfigDefault,
115 action='store_false', dest='InteractiveShell.color_info', default=NoConfigDefault,
139 help="Disable using colors for info related things.")
116 help="Disable using colors for info related things.")
140 ),
117 ),
141 (('--confirm-exit',), dict(
118 (('--confirm-exit',), dict(
142 action='store_true', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
119 action='store_true', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
143 help="Prompt the user when existing.")
120 help="Prompt the user when existing.")
144 ),
121 ),
145 (('--no-confirm-exit',), dict(
122 (('--no-confirm-exit',), dict(
146 action='store_false', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
123 action='store_false', dest='InteractiveShell.confirm_exit', default=NoConfigDefault,
147 help="Don't prompt the user when existing.")
124 help="Don't prompt the user when existing.")
148 ),
125 ),
149 (('--deep-reload',), dict(
126 (('--deep-reload',), dict(
150 action='store_true', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
127 action='store_true', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
151 help="Enable deep (recursive) reloading by default.")
128 help="Enable deep (recursive) reloading by default.")
152 ),
129 ),
153 (('--no-deep-reload',), dict(
130 (('--no-deep-reload',), dict(
154 action='store_false', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
131 action='store_false', dest='InteractiveShell.deep_reload', default=NoConfigDefault,
155 help="Disable deep (recursive) reloading by default.")
132 help="Disable deep (recursive) reloading by default.")
156 ),
133 ),
157 (('--editor',), dict(
134 (('--editor',), dict(
158 type=str, dest='InteractiveShell.editor', default=NoConfigDefault,
135 type=str, dest='InteractiveShell.editor', default=NoConfigDefault,
159 help="Set the editor used by IPython (default to $EDITOR/vi/notepad).",
136 help="Set the editor used by IPython (default to $EDITOR/vi/notepad).",
160 metavar='InteractiveShell.editor')
137 metavar='InteractiveShell.editor')
161 ),
138 ),
162 (('--log','-l'), dict(
139 (('--log','-l'), dict(
163 action='store_true', dest='InteractiveShell.logstart', default=NoConfigDefault,
140 action='store_true', dest='InteractiveShell.logstart', default=NoConfigDefault,
164 help="Start logging to the default file (./ipython_log.py).")
141 help="Start logging to the default file (./ipython_log.py).")
165 ),
142 ),
166 (('--logfile','-lf'), dict(
143 (('--logfile','-lf'), dict(
167 type=unicode, dest='InteractiveShell.logfile', default=NoConfigDefault,
144 type=unicode, dest='InteractiveShell.logfile', default=NoConfigDefault,
168 help="Start logging to logfile.",
145 help="Start logging to logfile.",
169 metavar='InteractiveShell.logfile')
146 metavar='InteractiveShell.logfile')
170 ),
147 ),
171 (('--log-append','-la'), dict(
148 (('--log-append','-la'), dict(
172 type=unicode, dest='InteractiveShell.logappend', default=NoConfigDefault,
149 type=unicode, dest='InteractiveShell.logappend', default=NoConfigDefault,
173 help="Start logging to the give file in append mode.",
150 help="Start logging to the give file in append mode.",
174 metavar='InteractiveShell.logfile')
151 metavar='InteractiveShell.logfile')
175 ),
152 ),
176 (('--pdb',), dict(
153 (('--pdb',), dict(
177 action='store_true', dest='InteractiveShell.pdb', default=NoConfigDefault,
154 action='store_true', dest='InteractiveShell.pdb', default=NoConfigDefault,
178 help="Enable auto calling the pdb debugger after every exception.")
155 help="Enable auto calling the pdb debugger after every exception.")
179 ),
156 ),
180 (('--no-pdb',), dict(
157 (('--no-pdb',), dict(
181 action='store_false', dest='InteractiveShell.pdb', default=NoConfigDefault,
158 action='store_false', dest='InteractiveShell.pdb', default=NoConfigDefault,
182 help="Disable auto calling the pdb debugger after every exception.")
159 help="Disable auto calling the pdb debugger after every exception.")
183 ),
160 ),
184 (('--pprint',), dict(
161 (('--pprint',), dict(
185 action='store_true', dest='InteractiveShell.pprint', default=NoConfigDefault,
162 action='store_true', dest='InteractiveShell.pprint', default=NoConfigDefault,
186 help="Enable auto pretty printing of results.")
163 help="Enable auto pretty printing of results.")
187 ),
164 ),
188 (('--no-pprint',), dict(
165 (('--no-pprint',), dict(
189 action='store_false', dest='InteractiveShell.pprint', default=NoConfigDefault,
166 action='store_false', dest='InteractiveShell.pprint', default=NoConfigDefault,
190 help="Disable auto auto pretty printing of results.")
167 help="Disable auto auto pretty printing of results.")
191 ),
168 ),
192 (('--prompt-in1','-pi1'), dict(
169 (('--prompt-in1','-pi1'), dict(
193 type=str, dest='InteractiveShell.prompt_in1', default=NoConfigDefault,
170 type=str, dest='InteractiveShell.prompt_in1', default=NoConfigDefault,
194 help="Set the main input prompt ('In [\#]: ')",
171 help="Set the main input prompt ('In [\#]: ')",
195 metavar='InteractiveShell.prompt_in1')
172 metavar='InteractiveShell.prompt_in1')
196 ),
173 ),
197 (('--prompt-in2','-pi2'), dict(
174 (('--prompt-in2','-pi2'), dict(
198 type=str, dest='InteractiveShell.prompt_in2', default=NoConfigDefault,
175 type=str, dest='InteractiveShell.prompt_in2', default=NoConfigDefault,
199 help="Set the secondary input prompt (' .\D.: ')",
176 help="Set the secondary input prompt (' .\D.: ')",
200 metavar='InteractiveShell.prompt_in2')
177 metavar='InteractiveShell.prompt_in2')
201 ),
178 ),
202 (('--prompt-out','-po'), dict(
179 (('--prompt-out','-po'), dict(
203 type=str, dest='InteractiveShell.prompt_out', default=NoConfigDefault,
180 type=str, dest='InteractiveShell.prompt_out', default=NoConfigDefault,
204 help="Set the output prompt ('Out[\#]:')",
181 help="Set the output prompt ('Out[\#]:')",
205 metavar='InteractiveShell.prompt_out')
182 metavar='InteractiveShell.prompt_out')
206 ),
183 ),
207 (('--quick',), dict(
184 (('--quick',), dict(
208 action='store_true', dest='Global.quick', default=NoConfigDefault,
185 action='store_true', dest='Global.quick', default=NoConfigDefault,
209 help="Enable quick startup with no config files.")
186 help="Enable quick startup with no config files.")
210 ),
187 ),
211 (('--readline',), dict(
188 (('--readline',), dict(
212 action='store_true', dest='InteractiveShell.readline_use', default=NoConfigDefault,
189 action='store_true', dest='InteractiveShell.readline_use', default=NoConfigDefault,
213 help="Enable readline for command line usage.")
190 help="Enable readline for command line usage.")
214 ),
191 ),
215 (('--no-readline',), dict(
192 (('--no-readline',), dict(
216 action='store_false', dest='InteractiveShell.readline_use', default=NoConfigDefault,
193 action='store_false', dest='InteractiveShell.readline_use', default=NoConfigDefault,
217 help="Disable readline for command line usage.")
194 help="Disable readline for command line usage.")
218 ),
195 ),
219 (('--screen-length','-sl'), dict(
196 (('--screen-length','-sl'), dict(
220 type=int, dest='InteractiveShell.screen_length', default=NoConfigDefault,
197 type=int, dest='InteractiveShell.screen_length', default=NoConfigDefault,
221 help='Number of lines on screen, used to control printing of long strings.',
198 help='Number of lines on screen, used to control printing of long strings.',
222 metavar='InteractiveShell.screen_length')
199 metavar='InteractiveShell.screen_length')
223 ),
200 ),
224 (('--separate-in','-si'), dict(
201 (('--separate-in','-si'), dict(
225 type=str, dest='InteractiveShell.separate_in', default=NoConfigDefault,
202 type=str, dest='InteractiveShell.separate_in', default=NoConfigDefault,
226 help="Separator before input prompts. Default '\n'.",
203 help="Separator before input prompts. Default '\n'.",
227 metavar='InteractiveShell.separate_in')
204 metavar='InteractiveShell.separate_in')
228 ),
205 ),
229 (('--separate-out','-so'), dict(
206 (('--separate-out','-so'), dict(
230 type=str, dest='InteractiveShell.separate_out', default=NoConfigDefault,
207 type=str, dest='InteractiveShell.separate_out', default=NoConfigDefault,
231 help="Separator before output prompts. Default 0 (nothing).",
208 help="Separator before output prompts. Default 0 (nothing).",
232 metavar='InteractiveShell.separate_out')
209 metavar='InteractiveShell.separate_out')
233 ),
210 ),
234 (('--separate-out2','-so2'), dict(
211 (('--separate-out2','-so2'), dict(
235 type=str, dest='InteractiveShell.separate_out2', default=NoConfigDefault,
212 type=str, dest='InteractiveShell.separate_out2', default=NoConfigDefault,
236 help="Separator after output prompts. Default 0 (nonight).",
213 help="Separator after output prompts. Default 0 (nonight).",
237 metavar='InteractiveShell.separate_out2')
214 metavar='InteractiveShell.separate_out2')
238 ),
215 ),
239 (('-no-sep',), dict(
216 (('-no-sep',), dict(
240 action='store_true', dest='Global.nosep', default=NoConfigDefault,
217 action='store_true', dest='Global.nosep', default=NoConfigDefault,
241 help="Eliminate all spacing between prompts.")
218 help="Eliminate all spacing between prompts.")
242 ),
219 ),
243 (('--term-title',), dict(
220 (('--term-title',), dict(
244 action='store_true', dest='InteractiveShell.term_title', default=NoConfigDefault,
221 action='store_true', dest='InteractiveShell.term_title', default=NoConfigDefault,
245 help="Enable auto setting the terminal title.")
222 help="Enable auto setting the terminal title.")
246 ),
223 ),
247 (('--no-term-title',), dict(
224 (('--no-term-title',), dict(
248 action='store_false', dest='InteractiveShell.term_title', default=NoConfigDefault,
225 action='store_false', dest='InteractiveShell.term_title', default=NoConfigDefault,
249 help="Disable auto setting the terminal title.")
226 help="Disable auto setting the terminal title.")
250 ),
227 ),
251 (('--xmode',), dict(
228 (('--xmode',), dict(
252 type=str, dest='InteractiveShell.xmode', default=NoConfigDefault,
229 type=str, dest='InteractiveShell.xmode', default=NoConfigDefault,
253 help="Exception mode ('Plain','Context','Verbose')",
230 help="Exception mode ('Plain','Context','Verbose')",
254 metavar='InteractiveShell.xmode')
231 metavar='InteractiveShell.xmode')
255 ),
232 ),
256 (('--ext',), dict(
233 (('--ext',), dict(
257 type=str, dest='Global.extra_extension', default=NoConfigDefault,
234 type=str, dest='Global.extra_extension', default=NoConfigDefault,
258 help="The dotted module name of an IPython extension to load.",
235 help="The dotted module name of an IPython extension to load.",
259 metavar='Global.extra_extension')
236 metavar='Global.extra_extension')
260 ),
237 ),
261 (('-c',), dict(
238 (('-c',), dict(
262 type=str, dest='Global.code_to_run', default=NoConfigDefault,
239 type=str, dest='Global.code_to_run', default=NoConfigDefault,
263 help="Execute the given command string.",
240 help="Execute the given command string.",
264 metavar='Global.code_to_run')
241 metavar='Global.code_to_run')
265 ),
242 ),
266 (('-i',), dict(
243 (('-i',), dict(
267 action='store_true', dest='Global.force_interact', default=NoConfigDefault,
244 action='store_true', dest='Global.force_interact', default=NoConfigDefault,
268 help="If running code from the command line, become interactive afterwards.")
245 help="If running code from the command line, become interactive afterwards.")
269 ),
246 ),
270 (('--wthread',), dict(
247 (('--wthread','-wthread'), dict(
271 action='store_true', dest='Global.wthread', default=NoConfigDefault,
248 action='store_true', dest='Global.wthread', default=NoConfigDefault,
272 help="Enable wxPython event loop integration.")
249 help="Enable wxPython event loop integration.")
273 ),
250 ),
274 (('--q4thread','--qthread'), dict(
251 (('--q4thread','--qthread','-q4thread','-qthread'), dict(
275 action='store_true', dest='Global.q4thread', default=NoConfigDefault,
252 action='store_true', dest='Global.q4thread', default=NoConfigDefault,
276 help="Enable Qt4 event loop integration. Qt3 is no longer supported.")
253 help="Enable Qt4 event loop integration. Qt3 is no longer supported.")
277 ),
254 ),
278 (('--gthread',), dict(
255 (('--gthread','-gthread'), dict(
279 action='store_true', dest='Global.gthread', default=NoConfigDefault,
256 action='store_true', dest='Global.gthread', default=NoConfigDefault,
280 help="Enable GTK event loop integration.")
257 help="Enable GTK event loop integration.")
281 ),
258 ),
282 # # These are only here to get the proper deprecation warnings
283 (('--pylab',), dict(
259 (('--pylab',), dict(
284 action='store_true', dest='Global.pylab', default=NoConfigDefault,
260 action='store_true', dest='Global.pylab', default=NoConfigDefault,
285 help="Disabled. Pylab has been disabled until matplotlib "
261 help="Pre-load matplotlib and numpy for interactive use.")
286 "supports this version of IPython.")
287 )
262 )
288 )
263 )
289
264
290
265
291 class IPythonAppCLConfigLoader(BaseAppArgParseConfigLoader):
266 class IPythonAppCLConfigLoader(BaseAppArgParseConfigLoader):
292
267
293 arguments = cl_args
268 arguments = cl_args
294
269
295 def load_config(self):
270 def load_config(self):
296 """Do actions just before loading the command line config."""
271 """Do actions just before loading the command line config."""
297
272
298 # Special hack: there are countless uses of 'ipython -pylab' (with one
273 # Special hack: there are countless uses of 'ipython -pylab' (with one
299 # dash) in the wild, including in printed books. Since argparse does
274 # dash) in the wild, including in printed books. Since argparse does
300 # will interpret -pylab as '-p ylab', sending us in a search for a
275 # will interpret -pylab as '-p ylab', sending us in a search for a
301 # profile named 'ylab', instead we special-case here -pylab as the
276 # profile named 'ylab', instead we special-case here -pylab as the
302 # first or second option only (this is how old ipython used to work)
277 # first or second option only (this is how old ipython used to work)
303 # and convert this use to --pylab. Ugly, but needed for this one
278 # and convert this use to --pylab. Ugly, but needed for this one
304 # very widely used case.
279 # very widely used case.
305 firstargs = sys.argv[:3]
280 firstargs = sys.argv[:3]
306 try:
281 try:
307 idx = firstargs.index('-pylab')
282 idx = firstargs.index('-pylab')
308 except ValueError:
283 except ValueError:
309 pass
284 pass
310 else:
285 else:
311 sys.argv[idx] = '--pylab'
286 sys.argv[idx] = '--pylab'
312 return super(IPythonAppCLConfigLoader, self).load_config()
287 return super(IPythonAppCLConfigLoader, self).load_config()
313
288
314 default_config_file_name = u'ipython_config.py'
289 default_config_file_name = u'ipython_config.py'
315
290
316
291
317 class IPythonApp(Application):
292 class IPythonApp(Application):
318 name = u'ipython'
293 name = u'ipython'
319 description = 'IPython: an enhanced interactive Python shell.'
294 description = 'IPython: an enhanced interactive Python shell.'
320 config_file_name = default_config_file_name
295 config_file_name = default_config_file_name
321
296
322 def create_default_config(self):
297 def create_default_config(self):
323 super(IPythonApp, self).create_default_config()
298 super(IPythonApp, self).create_default_config()
324 # Eliminate multiple lookups
299 # Eliminate multiple lookups
325 Global = self.default_config.Global
300 Global = self.default_config.Global
326 # Set all default values
301 # Set all default values
327 Global.display_banner = True
302 Global.display_banner = True
328
303
329 # If the -c flag is given or a file is given to run at the cmd line
304 # If the -c flag is given or a file is given to run at the cmd line
330 # like "ipython foo.py", normally we exit without starting the main
305 # like "ipython foo.py", normally we exit without starting the main
331 # loop. The force_interact config variable allows a user to override
306 # loop. The force_interact config variable allows a user to override
332 # this and interact. It is also set by the -i cmd line flag, just
307 # this and interact. It is also set by the -i cmd line flag, just
333 # like Python.
308 # like Python.
334 Global.force_interact = False
309 Global.force_interact = False
335
310
336 # By default always interact by starting the IPython mainloop.
311 # By default always interact by starting the IPython mainloop.
337 Global.interact = True
312 Global.interact = True
338
313
339 # No GUI integration by default
314 # No GUI integration by default
340 Global.wthread = False
315 Global.wthread = False
341 Global.q4thread = False
316 Global.q4thread = False
342 Global.gthread = False
317 Global.gthread = False
343
318
319 # Pylab off by default
320 Global.pylab = False
321
344 def create_command_line_config(self):
322 def create_command_line_config(self):
345 """Create and return a command line config loader."""
323 """Create and return a command line config loader."""
346 return IPythonAppCLConfigLoader(
324 return IPythonAppCLConfigLoader(
347 description=self.description,
325 description=self.description,
348 version=release.version
326 version=release.version
349 )
327 )
350
328
351 def post_load_command_line_config(self):
352 """Do actions after loading cl config."""
353 clc = self.command_line_config
354
355 # Display the deprecation warnings about threaded shells
356 if hasattr(clc.Global, 'pylab'):
357 pylab_warning()
358 del clc.Global['pylab']
359
329
360 def load_file_config(self):
330 def load_file_config(self):
361 if hasattr(self.command_line_config.Global, 'quick'):
331 if hasattr(self.command_line_config.Global, 'quick'):
362 if self.command_line_config.Global.quick:
332 if self.command_line_config.Global.quick:
363 self.file_config = Config()
333 self.file_config = Config()
364 return
334 return
365 super(IPythonApp, self).load_file_config()
335 super(IPythonApp, self).load_file_config()
366
336
367 def post_load_file_config(self):
337 def post_load_file_config(self):
368 if hasattr(self.command_line_config.Global, 'extra_extension'):
338 if hasattr(self.command_line_config.Global, 'extra_extension'):
369 if not hasattr(self.file_config.Global, 'extensions'):
339 if not hasattr(self.file_config.Global, 'extensions'):
370 self.file_config.Global.extensions = []
340 self.file_config.Global.extensions = []
371 self.file_config.Global.extensions.append(
341 self.file_config.Global.extensions.append(
372 self.command_line_config.Global.extra_extension)
342 self.command_line_config.Global.extra_extension)
373 del self.command_line_config.Global.extra_extension
343 del self.command_line_config.Global.extra_extension
374
344
375 def pre_construct(self):
345 def pre_construct(self):
376 config = self.master_config
346 config = self.master_config
377
347
378 if hasattr(config.Global, 'classic'):
348 if hasattr(config.Global, 'classic'):
379 if config.Global.classic:
349 if config.Global.classic:
380 config.InteractiveShell.cache_size = 0
350 config.InteractiveShell.cache_size = 0
381 config.InteractiveShell.pprint = 0
351 config.InteractiveShell.pprint = 0
382 config.InteractiveShell.prompt_in1 = '>>> '
352 config.InteractiveShell.prompt_in1 = '>>> '
383 config.InteractiveShell.prompt_in2 = '... '
353 config.InteractiveShell.prompt_in2 = '... '
384 config.InteractiveShell.prompt_out = ''
354 config.InteractiveShell.prompt_out = ''
385 config.InteractiveShell.separate_in = \
355 config.InteractiveShell.separate_in = \
386 config.InteractiveShell.separate_out = \
356 config.InteractiveShell.separate_out = \
387 config.InteractiveShell.separate_out2 = ''
357 config.InteractiveShell.separate_out2 = ''
388 config.InteractiveShell.colors = 'NoColor'
358 config.InteractiveShell.colors = 'NoColor'
389 config.InteractiveShell.xmode = 'Plain'
359 config.InteractiveShell.xmode = 'Plain'
390
360
391 if hasattr(config.Global, 'nosep'):
361 if hasattr(config.Global, 'nosep'):
392 if config.Global.nosep:
362 if config.Global.nosep:
393 config.InteractiveShell.separate_in = \
363 config.InteractiveShell.separate_in = \
394 config.InteractiveShell.separate_out = \
364 config.InteractiveShell.separate_out = \
395 config.InteractiveShell.separate_out2 = ''
365 config.InteractiveShell.separate_out2 = ''
396
366
397 # if there is code of files to run from the cmd line, don't interact
367 # if there is code of files to run from the cmd line, don't interact
398 # unless the -i flag (Global.force_interact) is true.
368 # unless the -i flag (Global.force_interact) is true.
399 code_to_run = config.Global.get('code_to_run','')
369 code_to_run = config.Global.get('code_to_run','')
400 file_to_run = False
370 file_to_run = False
401 if len(self.extra_args)>=1:
371 if len(self.extra_args)>=1:
402 if self.extra_args[0]:
372 if self.extra_args[0]:
403 file_to_run = True
373 file_to_run = True
404 if file_to_run or code_to_run:
374 if file_to_run or code_to_run:
405 if not config.Global.force_interact:
375 if not config.Global.force_interact:
406 config.Global.interact = False
376 config.Global.interact = False
407
377
408 def construct(self):
378 def construct(self):
409 # I am a little hesitant to put these into InteractiveShell itself.
379 # I am a little hesitant to put these into InteractiveShell itself.
410 # But that might be the place for them
380 # But that might be the place for them
411 sys.path.insert(0, '')
381 sys.path.insert(0, '')
412
382
413 # Create an InteractiveShell instance
383 # Create an InteractiveShell instance
414 self.shell = InteractiveShell(
384 self.shell = InteractiveShell(
415 parent=None,
385 parent=None,
416 config=self.master_config
386 config=self.master_config
417 )
387 )
418
388
419 def post_construct(self):
389 def post_construct(self):
420 """Do actions after construct, but before starting the app."""
390 """Do actions after construct, but before starting the app."""
421 config = self.master_config
391 config = self.master_config
422
392
423 # shell.display_banner should always be False for the terminal
393 # shell.display_banner should always be False for the terminal
424 # based app, because we call shell.show_banner() by hand below
394 # based app, because we call shell.show_banner() by hand below
425 # so the banner shows *before* all extension loading stuff.
395 # so the banner shows *before* all extension loading stuff.
426 self.shell.display_banner = False
396 self.shell.display_banner = False
427
397
428 if config.Global.display_banner and \
398 if config.Global.display_banner and \
429 config.Global.interact:
399 config.Global.interact:
430 self.shell.show_banner()
400 self.shell.show_banner()
431
401
432 # Make sure there is a space below the banner.
402 # Make sure there is a space below the banner.
433 if self.log_level <= logging.INFO: print
403 if self.log_level <= logging.INFO: print
434
404
435 # Now a variety of things that happen after the banner is printed.
405 # Now a variety of things that happen after the banner is printed.
436 self._enable_gui()
406 self._enable_gui_pylab()
437 self._load_extensions()
407 self._load_extensions()
438 self._run_exec_lines()
408 self._run_exec_lines()
439 self._run_exec_files()
409 self._run_exec_files()
440 self._run_cmd_line_code()
410 self._run_cmd_line_code()
411 self._configure_xmode()
412
413 def _enable_gui_pylab(self):
414 """Enable GUI event loop integration, taking pylab into account."""
415 Global = self.master_config.Global
416
417 # Select which gui to use
418 if Global.wthread:
419 gui = inputhook.GUI_WX
420 elif Global.q4thread:
421 gui = inputhook.GUI_QT
422 elif Global.gthread:
423 gui = inputhook.GUI_GTK
424 else:
425 gui = None
441
426
442 def _enable_gui(self):
427 if Global.pylab:
443 """Enable GUI event loop integration."""
428 activate = self.shell.enable_pylab
444 config = self.master_config
429 else:
430 # Enable only GUI integration, no pylab
431 activate = inputhook.enable_gui
432
433 if gui or Global.pylab:
445 try:
434 try:
446 # Enable GUI integration
435 m = "Enabling GUI event loop integration, toolkit=%s, pylab=%s"\
447 if config.Global.wthread:
436 % (gui, Global.pylab)
448 self.log.info("Enabling wx GUI event loop integration")
437 self.log.info(m)
449 inputhook.enable_wx(app=True)
438 activate(gui)
450 elif config.Global.q4thread:
451 self.log.info("Enabling Qt4 GUI event loop integration")
452 inputhook.enable_qt4(app=True)
453 elif config.Global.gthread:
454 self.log.info("Enabling GTK GUI event loop integration")
455 inputhook.enable_gtk(app=True)
456 except:
439 except:
457 self.log.warn("Error in enabling GUI event loop integration:")
440 self.log.warn("Error in enabling GUI event loop integration:")
458 self.shell.showtraceback()
441 self.shell.showtraceback()
459
442
443
460 def _load_extensions(self):
444 def _load_extensions(self):
461 """Load all IPython extensions in Global.extensions.
445 """Load all IPython extensions in Global.extensions.
462
446
463 This uses the :meth:`InteractiveShell.load_extensions` to load all
447 This uses the :meth:`InteractiveShell.load_extensions` to load all
464 the extensions listed in ``self.master_config.Global.extensions``.
448 the extensions listed in ``self.master_config.Global.extensions``.
465 """
449 """
466 try:
450 try:
467 if hasattr(self.master_config.Global, 'extensions'):
451 if hasattr(self.master_config.Global, 'extensions'):
468 self.log.debug("Loading IPython extensions...")
452 self.log.debug("Loading IPython extensions...")
469 extensions = self.master_config.Global.extensions
453 extensions = self.master_config.Global.extensions
470 for ext in extensions:
454 for ext in extensions:
471 try:
455 try:
472 self.log.info("Loading IPython extension: %s" % ext)
456 self.log.info("Loading IPython extension: %s" % ext)
473 self.shell.load_extension(ext)
457 self.shell.load_extension(ext)
474 except:
458 except:
475 self.log.warn("Error in loading extension: %s" % ext)
459 self.log.warn("Error in loading extension: %s" % ext)
476 self.shell.showtraceback()
460 self.shell.showtraceback()
477 except:
461 except:
478 self.log.warn("Unknown error in loading extensions:")
462 self.log.warn("Unknown error in loading extensions:")
479 self.shell.showtraceback()
463 self.shell.showtraceback()
480
464
481 def _run_exec_lines(self):
465 def _run_exec_lines(self):
482 """Run lines of code in Global.exec_lines in the user's namespace."""
466 """Run lines of code in Global.exec_lines in the user's namespace."""
483 try:
467 try:
484 if hasattr(self.master_config.Global, 'exec_lines'):
468 if hasattr(self.master_config.Global, 'exec_lines'):
485 self.log.debug("Running code from Global.exec_lines...")
469 self.log.debug("Running code from Global.exec_lines...")
486 exec_lines = self.master_config.Global.exec_lines
470 exec_lines = self.master_config.Global.exec_lines
487 for line in exec_lines:
471 for line in exec_lines:
488 try:
472 try:
489 self.log.info("Running code in user namespace: %s" % line)
473 self.log.info("Running code in user namespace: %s" % line)
490 self.shell.runlines(line)
474 self.shell.runlines(line)
491 except:
475 except:
492 self.log.warn("Error in executing line in user namespace: %s" % line)
476 self.log.warn("Error in executing line in user namespace: %s" % line)
493 self.shell.showtraceback()
477 self.shell.showtraceback()
494 except:
478 except:
495 self.log.warn("Unknown error in handling Global.exec_lines:")
479 self.log.warn("Unknown error in handling Global.exec_lines:")
496 self.shell.showtraceback()
480 self.shell.showtraceback()
497
481
498 def _exec_file(self, fname):
482 def _exec_file(self, fname):
499 full_filename = filefind(fname, [u'.', self.ipython_dir])
483 full_filename = filefind(fname, [u'.', self.ipython_dir])
500 if os.path.isfile(full_filename):
484 if os.path.isfile(full_filename):
501 if full_filename.endswith(u'.py'):
485 if full_filename.endswith(u'.py'):
502 self.log.info("Running file in user namespace: %s" % full_filename)
486 self.log.info("Running file in user namespace: %s" % full_filename)
503 self.shell.safe_execfile(full_filename, self.shell.user_ns)
487 self.shell.safe_execfile(full_filename, self.shell.user_ns)
504 elif full_filename.endswith('.ipy'):
488 elif full_filename.endswith('.ipy'):
505 self.log.info("Running file in user namespace: %s" % full_filename)
489 self.log.info("Running file in user namespace: %s" % full_filename)
506 self.shell.safe_execfile_ipy(full_filename)
490 self.shell.safe_execfile_ipy(full_filename)
507 else:
491 else:
508 self.log.warn("File does not have a .py or .ipy extension: <%s>" % full_filename)
492 self.log.warn("File does not have a .py or .ipy extension: <%s>" % full_filename)
509
493
510 def _run_exec_files(self):
494 def _run_exec_files(self):
511 try:
495 try:
512 if hasattr(self.master_config.Global, 'exec_files'):
496 if hasattr(self.master_config.Global, 'exec_files'):
513 self.log.debug("Running files in Global.exec_files...")
497 self.log.debug("Running files in Global.exec_files...")
514 exec_files = self.master_config.Global.exec_files
498 exec_files = self.master_config.Global.exec_files
515 for fname in exec_files:
499 for fname in exec_files:
516 self._exec_file(fname)
500 self._exec_file(fname)
517 except:
501 except:
518 self.log.warn("Unknown error in handling Global.exec_files:")
502 self.log.warn("Unknown error in handling Global.exec_files:")
519 self.shell.showtraceback()
503 self.shell.showtraceback()
520
504
521 def _run_cmd_line_code(self):
505 def _run_cmd_line_code(self):
522 if hasattr(self.master_config.Global, 'code_to_run'):
506 if hasattr(self.master_config.Global, 'code_to_run'):
523 line = self.master_config.Global.code_to_run
507 line = self.master_config.Global.code_to_run
524 try:
508 try:
525 self.log.info("Running code given at command line (-c): %s" % line)
509 self.log.info("Running code given at command line (-c): %s" % line)
526 self.shell.runlines(line)
510 self.shell.runlines(line)
527 except:
511 except:
528 self.log.warn("Error in executing line in user namespace: %s" % line)
512 self.log.warn("Error in executing line in user namespace: %s" % line)
529 self.shell.showtraceback()
513 self.shell.showtraceback()
530 return
514 return
531 # Like Python itself, ignore the second if the first of these is present
515 # Like Python itself, ignore the second if the first of these is present
532 try:
516 try:
533 fname = self.extra_args[0]
517 fname = self.extra_args[0]
534 except:
518 except:
535 pass
519 pass
536 else:
520 else:
537 try:
521 try:
538 self._exec_file(fname)
522 self._exec_file(fname)
539 except:
523 except:
540 self.log.warn("Error in executing file in user namespace: %s" % fname)
524 self.log.warn("Error in executing file in user namespace: %s" % fname)
541 self.shell.showtraceback()
525 self.shell.showtraceback()
542
526
527 def _configure_xmode(self):
528 # XXX - shouldn't this be read from the config? I'm still a little
529 # lost with all the details of handling the new config guys...
530 self.shell.InteractiveTB.set_mode(mode=self.shell.xmode)
531
543 def start_app(self):
532 def start_app(self):
544 if self.master_config.Global.interact:
533 if self.master_config.Global.interact:
545 self.log.debug("Starting IPython's mainloop...")
534 self.log.debug("Starting IPython's mainloop...")
546 self.shell.mainloop()
535 self.shell.mainloop()
547
536
548
537
538
549 def load_default_config(ipython_dir=None):
539 def load_default_config(ipython_dir=None):
550 """Load the default config file from the default ipython_dir.
540 """Load the default config file from the default ipython_dir.
551
541
552 This is useful for embedded shells.
542 This is useful for embedded shells.
553 """
543 """
554 if ipython_dir is None:
544 if ipython_dir is None:
555 ipython_dir = get_ipython_dir()
545 ipython_dir = get_ipython_dir()
556 cl = PyFileConfigLoader(default_config_file_name, ipython_dir)
546 cl = PyFileConfigLoader(default_config_file_name, ipython_dir)
557 config = cl.load_config()
547 config = cl.load_config()
558 return config
548 return config
559
549
560
550
561 def launch_new_instance():
551 def launch_new_instance():
562 """Create and run a full blown IPython instance"""
552 """Create and run a full blown IPython instance"""
563 app = IPythonApp()
553 app = IPythonApp()
564 app.start()
554 app.start()
565
555
@@ -1,2488 +1,2500 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """
2 """
3 Main IPython Component
3 Main IPython Component
4 """
4 """
5
5
6 #-----------------------------------------------------------------------------
6 #-----------------------------------------------------------------------------
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
7 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de>
8 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
8 # Copyright (C) 2001-2007 Fernando Perez. <fperez@colorado.edu>
9 # Copyright (C) 2008-2009 The IPython Development Team
9 # Copyright (C) 2008-2009 The IPython Development Team
10 #
10 #
11 # Distributed under the terms of the BSD License. The full license is in
11 # Distributed under the terms of the BSD License. The full license is in
12 # the file COPYING, distributed as part of this software.
12 # the file COPYING, distributed as part of this software.
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 #-----------------------------------------------------------------------------
15 #-----------------------------------------------------------------------------
16 # Imports
16 # Imports
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18
18
19 from __future__ import with_statement
19 from __future__ import with_statement
20
20
21 import __builtin__
21 import __builtin__
22 import StringIO
22 import StringIO
23 import bdb
23 import bdb
24 import codeop
24 import codeop
25 import exceptions
25 import exceptions
26 import new
26 import new
27 import os
27 import os
28 import re
28 import re
29 import string
29 import string
30 import sys
30 import sys
31 import tempfile
31 import tempfile
32 from contextlib import nested
32 from contextlib import nested
33
33
34 from IPython.core import ultratb
35 from IPython.core import debugger, oinspect
34 from IPython.core import debugger, oinspect
36 from IPython.core import shadowns
37 from IPython.core import history as ipcorehist
35 from IPython.core import history as ipcorehist
38 from IPython.core import prefilter
36 from IPython.core import prefilter
37 from IPython.core import shadowns
38 from IPython.core import ultratb
39 from IPython.core.alias import AliasManager
39 from IPython.core.alias import AliasManager
40 from IPython.core.builtin_trap import BuiltinTrap
40 from IPython.core.builtin_trap import BuiltinTrap
41 from IPython.core.component import Component
41 from IPython.core.display_trap import DisplayTrap
42 from IPython.core.display_trap import DisplayTrap
43 from IPython.core.error import TryNext, UsageError
42 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
44 from IPython.core.fakemodule import FakeModule, init_fakemod_dict
43 from IPython.core.logger import Logger
45 from IPython.core.logger import Logger
44 from IPython.core.magic import Magic
46 from IPython.core.magic import Magic
45 from IPython.core.prompts import CachedOutput
46 from IPython.core.prefilter import PrefilterManager
47 from IPython.core.prefilter import PrefilterManager
47 from IPython.core.component import Component
48 from IPython.core.prompts import CachedOutput
49 from IPython.core.pylabtools import pylab_activate
48 from IPython.core.usage import interactive_usage, default_banner
50 from IPython.core.usage import interactive_usage, default_banner
49 from IPython.core.error import TryNext, UsageError
50
51 from IPython.utils import pickleshare
52 from IPython.external.Itpl import ItplNS
51 from IPython.external.Itpl import ItplNS
52 from IPython.lib.inputhook import enable_gui
53 from IPython.lib.backgroundjobs import BackgroundJobManager
53 from IPython.lib.backgroundjobs import BackgroundJobManager
54 from IPython.utils.ipstruct import Struct
55 from IPython.utils import PyColorize
54 from IPython.utils import PyColorize
56 from IPython.utils.genutils import *
55 from IPython.utils import pickleshare
57 from IPython.utils.genutils import get_ipython_dir
56 from IPython.utils.genutils import get_ipython_dir
57 from IPython.utils.ipstruct import Struct
58 from IPython.utils.platutils import toggle_set_term_title, set_term_title
58 from IPython.utils.platutils import toggle_set_term_title, set_term_title
59 from IPython.utils.strdispatch import StrDispatch
59 from IPython.utils.strdispatch import StrDispatch
60 from IPython.utils.syspathcontext import prepended_to_syspath
60 from IPython.utils.syspathcontext import prepended_to_syspath
61
61
62 # XXX - need to clean up this import * line
63 from IPython.utils.genutils import *
64
62 # from IPython.utils import growl
65 # from IPython.utils import growl
63 # growl.start("IPython")
66 # growl.start("IPython")
64
67
65 from IPython.utils.traitlets import (
68 from IPython.utils.traitlets import (
66 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode
69 Int, Str, CBool, CaselessStrEnum, Enum, List, Unicode
67 )
70 )
68
71
69 #-----------------------------------------------------------------------------
72 #-----------------------------------------------------------------------------
70 # Globals
73 # Globals
71 #-----------------------------------------------------------------------------
74 #-----------------------------------------------------------------------------
72
75
73
74 # store the builtin raw_input globally, and use this always, in case user code
76 # store the builtin raw_input globally, and use this always, in case user code
75 # overwrites it (like wx.py.PyShell does)
77 # overwrites it (like wx.py.PyShell does)
76 raw_input_original = raw_input
78 raw_input_original = raw_input
77
79
78 # compiled regexps for autoindent management
80 # compiled regexps for autoindent management
79 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
81 dedent_re = re.compile(r'^\s+raise|^\s+return|^\s+pass')
80
82
81
82 #-----------------------------------------------------------------------------
83 #-----------------------------------------------------------------------------
83 # Utilities
84 # Utilities
84 #-----------------------------------------------------------------------------
85 #-----------------------------------------------------------------------------
85
86
86
87 ini_spaces_re = re.compile(r'^(\s+)')
87 ini_spaces_re = re.compile(r'^(\s+)')
88
88
89
89
90 def num_ini_spaces(strng):
90 def num_ini_spaces(strng):
91 """Return the number of initial spaces in a string"""
91 """Return the number of initial spaces in a string"""
92
92
93 ini_spaces = ini_spaces_re.match(strng)
93 ini_spaces = ini_spaces_re.match(strng)
94 if ini_spaces:
94 if ini_spaces:
95 return ini_spaces.end()
95 return ini_spaces.end()
96 else:
96 else:
97 return 0
97 return 0
98
98
99
99
100 def softspace(file, newvalue):
100 def softspace(file, newvalue):
101 """Copied from code.py, to remove the dependency"""
101 """Copied from code.py, to remove the dependency"""
102
102
103 oldvalue = 0
103 oldvalue = 0
104 try:
104 try:
105 oldvalue = file.softspace
105 oldvalue = file.softspace
106 except AttributeError:
106 except AttributeError:
107 pass
107 pass
108 try:
108 try:
109 file.softspace = newvalue
109 file.softspace = newvalue
110 except (AttributeError, TypeError):
110 except (AttributeError, TypeError):
111 # "attribute-less object" or "read-only attributes"
111 # "attribute-less object" or "read-only attributes"
112 pass
112 pass
113 return oldvalue
113 return oldvalue
114
114
115
115
116 class SpaceInInput(exceptions.Exception): pass
116 class SpaceInInput(exceptions.Exception): pass
117
117
118 class Bunch: pass
118 class Bunch: pass
119
119
120 class InputList(list):
120 class InputList(list):
121 """Class to store user input.
121 """Class to store user input.
122
122
123 It's basically a list, but slices return a string instead of a list, thus
123 It's basically a list, but slices return a string instead of a list, thus
124 allowing things like (assuming 'In' is an instance):
124 allowing things like (assuming 'In' is an instance):
125
125
126 exec In[4:7]
126 exec In[4:7]
127
127
128 or
128 or
129
129
130 exec In[5:9] + In[14] + In[21:25]"""
130 exec In[5:9] + In[14] + In[21:25]"""
131
131
132 def __getslice__(self,i,j):
132 def __getslice__(self,i,j):
133 return ''.join(list.__getslice__(self,i,j))
133 return ''.join(list.__getslice__(self,i,j))
134
134
135
135
136 class SyntaxTB(ultratb.ListTB):
136 class SyntaxTB(ultratb.ListTB):
137 """Extension which holds some state: the last exception value"""
137 """Extension which holds some state: the last exception value"""
138
138
139 def __init__(self,color_scheme = 'NoColor'):
139 def __init__(self,color_scheme = 'NoColor'):
140 ultratb.ListTB.__init__(self,color_scheme)
140 ultratb.ListTB.__init__(self,color_scheme)
141 self.last_syntax_error = None
141 self.last_syntax_error = None
142
142
143 def __call__(self, etype, value, elist):
143 def __call__(self, etype, value, elist):
144 self.last_syntax_error = value
144 self.last_syntax_error = value
145 ultratb.ListTB.__call__(self,etype,value,elist)
145 ultratb.ListTB.__call__(self,etype,value,elist)
146
146
147 def clear_err_state(self):
147 def clear_err_state(self):
148 """Return the current error state and clear it"""
148 """Return the current error state and clear it"""
149 e = self.last_syntax_error
149 e = self.last_syntax_error
150 self.last_syntax_error = None
150 self.last_syntax_error = None
151 return e
151 return e
152
152
153
153
154 def get_default_editor():
154 def get_default_editor():
155 try:
155 try:
156 ed = os.environ['EDITOR']
156 ed = os.environ['EDITOR']
157 except KeyError:
157 except KeyError:
158 if os.name == 'posix':
158 if os.name == 'posix':
159 ed = 'vi' # the only one guaranteed to be there!
159 ed = 'vi' # the only one guaranteed to be there!
160 else:
160 else:
161 ed = 'notepad' # same in Windows!
161 ed = 'notepad' # same in Windows!
162 return ed
162 return ed
163
163
164
164
165 def get_default_colors():
165 def get_default_colors():
166 if sys.platform=='darwin':
166 if sys.platform=='darwin':
167 return "LightBG"
167 return "LightBG"
168 elif os.name=='nt':
168 elif os.name=='nt':
169 return 'Linux'
169 return 'Linux'
170 else:
170 else:
171 return 'Linux'
171 return 'Linux'
172
172
173
173
174 class SeparateStr(Str):
174 class SeparateStr(Str):
175 """A Str subclass to validate separate_in, separate_out, etc.
175 """A Str subclass to validate separate_in, separate_out, etc.
176
176
177 This is a Str based traitlet that converts '0'->'' and '\\n'->'\n'.
177 This is a Str based traitlet that converts '0'->'' and '\\n'->'\n'.
178 """
178 """
179
179
180 def validate(self, obj, value):
180 def validate(self, obj, value):
181 if value == '0': value = ''
181 if value == '0': value = ''
182 value = value.replace('\\n','\n')
182 value = value.replace('\\n','\n')
183 return super(SeparateStr, self).validate(obj, value)
183 return super(SeparateStr, self).validate(obj, value)
184
184
185
185
186 #-----------------------------------------------------------------------------
186 #-----------------------------------------------------------------------------
187 # Main IPython class
187 # Main IPython class
188 #-----------------------------------------------------------------------------
188 #-----------------------------------------------------------------------------
189
189
190
190
191 class InteractiveShell(Component, Magic):
191 class InteractiveShell(Component, Magic):
192 """An enhanced, interactive shell for Python."""
192 """An enhanced, interactive shell for Python."""
193
193
194 autocall = Enum((0,1,2), default_value=1, config=True)
194 autocall = Enum((0,1,2), default_value=1, config=True)
195 autoedit_syntax = CBool(False, config=True)
195 autoedit_syntax = CBool(False, config=True)
196 autoindent = CBool(True, config=True)
196 autoindent = CBool(True, config=True)
197 automagic = CBool(True, config=True)
197 automagic = CBool(True, config=True)
198 banner = Str('')
198 banner = Str('')
199 banner1 = Str(default_banner, config=True)
199 banner1 = Str(default_banner, config=True)
200 banner2 = Str('', config=True)
200 banner2 = Str('', config=True)
201 cache_size = Int(1000, config=True)
201 cache_size = Int(1000, config=True)
202 color_info = CBool(True, config=True)
202 color_info = CBool(True, config=True)
203 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
203 colors = CaselessStrEnum(('NoColor','LightBG','Linux'),
204 default_value=get_default_colors(), config=True)
204 default_value=get_default_colors(), config=True)
205 confirm_exit = CBool(True, config=True)
205 confirm_exit = CBool(True, config=True)
206 debug = CBool(False, config=True)
206 debug = CBool(False, config=True)
207 deep_reload = CBool(False, config=True)
207 deep_reload = CBool(False, config=True)
208 # This display_banner only controls whether or not self.show_banner()
208 # This display_banner only controls whether or not self.show_banner()
209 # is called when mainloop/interact are called. The default is False
209 # is called when mainloop/interact are called. The default is False
210 # because for the terminal based application, the banner behavior
210 # because for the terminal based application, the banner behavior
211 # is controlled by Global.display_banner, which IPythonApp looks at
211 # is controlled by Global.display_banner, which IPythonApp looks at
212 # to determine if *it* should call show_banner() by hand or not.
212 # to determine if *it* should call show_banner() by hand or not.
213 display_banner = CBool(False) # This isn't configurable!
213 display_banner = CBool(False) # This isn't configurable!
214 embedded = CBool(False)
214 embedded = CBool(False)
215 embedded_active = CBool(False)
215 embedded_active = CBool(False)
216 editor = Str(get_default_editor(), config=True)
216 editor = Str(get_default_editor(), config=True)
217 filename = Str("<ipython console>")
217 filename = Str("<ipython console>")
218 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
218 ipython_dir= Unicode('', config=True) # Set to get_ipython_dir() in __init__
219 logstart = CBool(False, config=True)
219 logstart = CBool(False, config=True)
220 logfile = Str('', config=True)
220 logfile = Str('', config=True)
221 logappend = Str('', config=True)
221 logappend = Str('', config=True)
222 object_info_string_level = Enum((0,1,2), default_value=0,
222 object_info_string_level = Enum((0,1,2), default_value=0,
223 config=True)
223 config=True)
224 pager = Str('less', config=True)
224 pager = Str('less', config=True)
225 pdb = CBool(False, config=True)
225 pdb = CBool(False, config=True)
226 pprint = CBool(True, config=True)
226 pprint = CBool(True, config=True)
227 profile = Str('', config=True)
227 profile = Str('', config=True)
228 prompt_in1 = Str('In [\\#]: ', config=True)
228 prompt_in1 = Str('In [\\#]: ', config=True)
229 prompt_in2 = Str(' .\\D.: ', config=True)
229 prompt_in2 = Str(' .\\D.: ', config=True)
230 prompt_out = Str('Out[\\#]: ', config=True)
230 prompt_out = Str('Out[\\#]: ', config=True)
231 prompts_pad_left = CBool(True, config=True)
231 prompts_pad_left = CBool(True, config=True)
232 quiet = CBool(False, config=True)
232 quiet = CBool(False, config=True)
233
233
234 readline_use = CBool(True, config=True)
234 readline_use = CBool(True, config=True)
235 readline_merge_completions = CBool(True, config=True)
235 readline_merge_completions = CBool(True, config=True)
236 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
236 readline_omit__names = Enum((0,1,2), default_value=0, config=True)
237 readline_remove_delims = Str('-/~', config=True)
237 readline_remove_delims = Str('-/~', config=True)
238 readline_parse_and_bind = List([
238 readline_parse_and_bind = List([
239 'tab: complete',
239 'tab: complete',
240 '"\C-l": possible-completions',
240 '"\C-l": possible-completions',
241 'set show-all-if-ambiguous on',
241 'set show-all-if-ambiguous on',
242 '"\C-o": tab-insert',
242 '"\C-o": tab-insert',
243 '"\M-i": " "',
243 '"\M-i": " "',
244 '"\M-o": "\d\d\d\d"',
244 '"\M-o": "\d\d\d\d"',
245 '"\M-I": "\d\d\d\d"',
245 '"\M-I": "\d\d\d\d"',
246 '"\C-r": reverse-search-history',
246 '"\C-r": reverse-search-history',
247 '"\C-s": forward-search-history',
247 '"\C-s": forward-search-history',
248 '"\C-p": history-search-backward',
248 '"\C-p": history-search-backward',
249 '"\C-n": history-search-forward',
249 '"\C-n": history-search-forward',
250 '"\e[A": history-search-backward',
250 '"\e[A": history-search-backward',
251 '"\e[B": history-search-forward',
251 '"\e[B": history-search-forward',
252 '"\C-k": kill-line',
252 '"\C-k": kill-line',
253 '"\C-u": unix-line-discard',
253 '"\C-u": unix-line-discard',
254 ], allow_none=False, config=True)
254 ], allow_none=False, config=True)
255
255
256 screen_length = Int(0, config=True)
256 screen_length = Int(0, config=True)
257
257
258 # Use custom TraitletTypes that convert '0'->'' and '\\n'->'\n'
258 # Use custom TraitletTypes that convert '0'->'' and '\\n'->'\n'
259 separate_in = SeparateStr('\n', config=True)
259 separate_in = SeparateStr('\n', config=True)
260 separate_out = SeparateStr('', config=True)
260 separate_out = SeparateStr('', config=True)
261 separate_out2 = SeparateStr('', config=True)
261 separate_out2 = SeparateStr('', config=True)
262
262
263 system_header = Str('IPython system call: ', config=True)
263 system_header = Str('IPython system call: ', config=True)
264 system_verbose = CBool(False, config=True)
264 system_verbose = CBool(False, config=True)
265 term_title = CBool(False, config=True)
265 term_title = CBool(False, config=True)
266 wildcards_case_sensitive = CBool(True, config=True)
266 wildcards_case_sensitive = CBool(True, config=True)
267 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
267 xmode = CaselessStrEnum(('Context','Plain', 'Verbose'),
268 default_value='Context', config=True)
268 default_value='Context', config=True)
269
269
270 autoexec = List(allow_none=False)
270 autoexec = List(allow_none=False)
271
271
272 # class attribute to indicate whether the class supports threads or not.
272 # class attribute to indicate whether the class supports threads or not.
273 # Subclasses with thread support should override this as needed.
273 # Subclasses with thread support should override this as needed.
274 isthreaded = False
274 isthreaded = False
275
275
276 def __init__(self, parent=None, config=None, ipython_dir=None, usage=None,
276 def __init__(self, parent=None, config=None, ipython_dir=None, usage=None,
277 user_ns=None, user_global_ns=None,
277 user_ns=None, user_global_ns=None,
278 banner1=None, banner2=None, display_banner=None,
278 banner1=None, banner2=None, display_banner=None,
279 custom_exceptions=((),None)):
279 custom_exceptions=((),None)):
280
280
281 # This is where traitlets with a config_key argument are updated
281 # This is where traitlets with a config_key argument are updated
282 # from the values on config.
282 # from the values on config.
283 super(InteractiveShell, self).__init__(parent, config=config)
283 super(InteractiveShell, self).__init__(parent, config=config)
284
284
285 # These are relatively independent and stateless
285 # These are relatively independent and stateless
286 self.init_ipython_dir(ipython_dir)
286 self.init_ipython_dir(ipython_dir)
287 self.init_instance_attrs()
287 self.init_instance_attrs()
288 self.init_term_title()
288 self.init_term_title()
289 self.init_usage(usage)
289 self.init_usage(usage)
290 self.init_banner(banner1, banner2, display_banner)
290 self.init_banner(banner1, banner2, display_banner)
291
291
292 # Create namespaces (user_ns, user_global_ns, etc.)
292 # Create namespaces (user_ns, user_global_ns, etc.)
293 self.init_create_namespaces(user_ns, user_global_ns)
293 self.init_create_namespaces(user_ns, user_global_ns)
294 # This has to be done after init_create_namespaces because it uses
294 # This has to be done after init_create_namespaces because it uses
295 # something in self.user_ns, but before init_sys_modules, which
295 # something in self.user_ns, but before init_sys_modules, which
296 # is the first thing to modify sys.
296 # is the first thing to modify sys.
297 self.save_sys_module_state()
297 self.save_sys_module_state()
298 self.init_sys_modules()
298 self.init_sys_modules()
299
299
300 self.init_history()
300 self.init_history()
301 self.init_encoding()
301 self.init_encoding()
302 self.init_prefilter()
302 self.init_prefilter()
303
303
304 Magic.__init__(self, self)
304 Magic.__init__(self, self)
305
305
306 self.init_syntax_highlighting()
306 self.init_syntax_highlighting()
307 self.init_hooks()
307 self.init_hooks()
308 self.init_pushd_popd_magic()
308 self.init_pushd_popd_magic()
309 self.init_traceback_handlers(custom_exceptions)
309 self.init_traceback_handlers(custom_exceptions)
310 self.init_user_ns()
310 self.init_user_ns()
311 self.init_logger()
311 self.init_logger()
312 self.init_alias()
312 self.init_alias()
313 self.init_builtins()
313 self.init_builtins()
314
314
315 # pre_config_initialization
315 # pre_config_initialization
316 self.init_shadow_hist()
316 self.init_shadow_hist()
317
317
318 # The next section should contain averything that was in ipmaker.
318 # The next section should contain averything that was in ipmaker.
319 self.init_logstart()
319 self.init_logstart()
320
320
321 # The following was in post_config_initialization
321 # The following was in post_config_initialization
322 self.init_inspector()
322 self.init_inspector()
323 self.init_readline()
323 self.init_readline()
324 self.init_prompts()
324 self.init_prompts()
325 self.init_displayhook()
325 self.init_displayhook()
326 self.init_reload_doctest()
326 self.init_reload_doctest()
327 self.init_magics()
327 self.init_magics()
328 self.init_pdb()
328 self.init_pdb()
329 self.hooks.late_startup_hook()
329 self.hooks.late_startup_hook()
330
330
331 def get_ipython(self):
331 def get_ipython(self):
332 return self
332 return self
333
333
334 #-------------------------------------------------------------------------
334 #-------------------------------------------------------------------------
335 # Traitlet changed handlers
335 # Traitlet changed handlers
336 #-------------------------------------------------------------------------
336 #-------------------------------------------------------------------------
337
337
338 def _banner1_changed(self):
338 def _banner1_changed(self):
339 self.compute_banner()
339 self.compute_banner()
340
340
341 def _banner2_changed(self):
341 def _banner2_changed(self):
342 self.compute_banner()
342 self.compute_banner()
343
343
344 def _ipython_dir_changed(self, name, new):
344 def _ipython_dir_changed(self, name, new):
345 if not os.path.isdir(new):
345 if not os.path.isdir(new):
346 os.makedirs(new, mode = 0777)
346 os.makedirs(new, mode = 0777)
347 if not os.path.isdir(self.ipython_extension_dir):
347 if not os.path.isdir(self.ipython_extension_dir):
348 os.makedirs(self.ipython_extension_dir, mode = 0777)
348 os.makedirs(self.ipython_extension_dir, mode = 0777)
349
349
350 @property
350 @property
351 def ipython_extension_dir(self):
351 def ipython_extension_dir(self):
352 return os.path.join(self.ipython_dir, 'extensions')
352 return os.path.join(self.ipython_dir, 'extensions')
353
353
354 @property
354 @property
355 def usable_screen_length(self):
355 def usable_screen_length(self):
356 if self.screen_length == 0:
356 if self.screen_length == 0:
357 return 0
357 return 0
358 else:
358 else:
359 num_lines_bot = self.separate_in.count('\n')+1
359 num_lines_bot = self.separate_in.count('\n')+1
360 return self.screen_length - num_lines_bot
360 return self.screen_length - num_lines_bot
361
361
362 def _term_title_changed(self, name, new_value):
362 def _term_title_changed(self, name, new_value):
363 self.init_term_title()
363 self.init_term_title()
364
364
365 def set_autoindent(self,value=None):
365 def set_autoindent(self,value=None):
366 """Set the autoindent flag, checking for readline support.
366 """Set the autoindent flag, checking for readline support.
367
367
368 If called with no arguments, it acts as a toggle."""
368 If called with no arguments, it acts as a toggle."""
369
369
370 if not self.has_readline:
370 if not self.has_readline:
371 if os.name == 'posix':
371 if os.name == 'posix':
372 warn("The auto-indent feature requires the readline library")
372 warn("The auto-indent feature requires the readline library")
373 self.autoindent = 0
373 self.autoindent = 0
374 return
374 return
375 if value is None:
375 if value is None:
376 self.autoindent = not self.autoindent
376 self.autoindent = not self.autoindent
377 else:
377 else:
378 self.autoindent = value
378 self.autoindent = value
379
379
380 #-------------------------------------------------------------------------
380 #-------------------------------------------------------------------------
381 # init_* methods called by __init__
381 # init_* methods called by __init__
382 #-------------------------------------------------------------------------
382 #-------------------------------------------------------------------------
383
383
384 def init_ipython_dir(self, ipython_dir):
384 def init_ipython_dir(self, ipython_dir):
385 if ipython_dir is not None:
385 if ipython_dir is not None:
386 self.ipython_dir = ipython_dir
386 self.ipython_dir = ipython_dir
387 self.config.Global.ipython_dir = self.ipython_dir
387 self.config.Global.ipython_dir = self.ipython_dir
388 return
388 return
389
389
390 if hasattr(self.config.Global, 'ipython_dir'):
390 if hasattr(self.config.Global, 'ipython_dir'):
391 self.ipython_dir = self.config.Global.ipython_dir
391 self.ipython_dir = self.config.Global.ipython_dir
392 else:
392 else:
393 self.ipython_dir = get_ipython_dir()
393 self.ipython_dir = get_ipython_dir()
394
394
395 # All children can just read this
395 # All children can just read this
396 self.config.Global.ipython_dir = self.ipython_dir
396 self.config.Global.ipython_dir = self.ipython_dir
397
397
398 def init_instance_attrs(self):
398 def init_instance_attrs(self):
399 self.jobs = BackgroundJobManager()
399 self.jobs = BackgroundJobManager()
400 self.more = False
400 self.more = False
401
401
402 # command compiler
402 # command compiler
403 self.compile = codeop.CommandCompiler()
403 self.compile = codeop.CommandCompiler()
404
404
405 # User input buffer
405 # User input buffer
406 self.buffer = []
406 self.buffer = []
407
407
408 # Make an empty namespace, which extension writers can rely on both
408 # Make an empty namespace, which extension writers can rely on both
409 # existing and NEVER being used by ipython itself. This gives them a
409 # existing and NEVER being used by ipython itself. This gives them a
410 # convenient location for storing additional information and state
410 # convenient location for storing additional information and state
411 # their extensions may require, without fear of collisions with other
411 # their extensions may require, without fear of collisions with other
412 # ipython names that may develop later.
412 # ipython names that may develop later.
413 self.meta = Struct()
413 self.meta = Struct()
414
414
415 # Object variable to store code object waiting execution. This is
415 # Object variable to store code object waiting execution. This is
416 # used mainly by the multithreaded shells, but it can come in handy in
416 # used mainly by the multithreaded shells, but it can come in handy in
417 # other situations. No need to use a Queue here, since it's a single
417 # other situations. No need to use a Queue here, since it's a single
418 # item which gets cleared once run.
418 # item which gets cleared once run.
419 self.code_to_run = None
419 self.code_to_run = None
420
420
421 # Flag to mark unconditional exit
421 # Flag to mark unconditional exit
422 self.exit_now = False
422 self.exit_now = False
423
423
424 # Temporary files used for various purposes. Deleted at exit.
424 # Temporary files used for various purposes. Deleted at exit.
425 self.tempfiles = []
425 self.tempfiles = []
426
426
427 # Keep track of readline usage (later set by init_readline)
427 # Keep track of readline usage (later set by init_readline)
428 self.has_readline = False
428 self.has_readline = False
429
429
430 # keep track of where we started running (mainly for crash post-mortem)
430 # keep track of where we started running (mainly for crash post-mortem)
431 # This is not being used anywhere currently.
431 # This is not being used anywhere currently.
432 self.starting_dir = os.getcwd()
432 self.starting_dir = os.getcwd()
433
433
434 # Indentation management
434 # Indentation management
435 self.indent_current_nsp = 0
435 self.indent_current_nsp = 0
436
436
437 def init_term_title(self):
437 def init_term_title(self):
438 # Enable or disable the terminal title.
438 # Enable or disable the terminal title.
439 if self.term_title:
439 if self.term_title:
440 toggle_set_term_title(True)
440 toggle_set_term_title(True)
441 set_term_title('IPython: ' + abbrev_cwd())
441 set_term_title('IPython: ' + abbrev_cwd())
442 else:
442 else:
443 toggle_set_term_title(False)
443 toggle_set_term_title(False)
444
444
445 def init_usage(self, usage=None):
445 def init_usage(self, usage=None):
446 if usage is None:
446 if usage is None:
447 self.usage = interactive_usage
447 self.usage = interactive_usage
448 else:
448 else:
449 self.usage = usage
449 self.usage = usage
450
450
451 def init_encoding(self):
451 def init_encoding(self):
452 # Get system encoding at startup time. Certain terminals (like Emacs
452 # Get system encoding at startup time. Certain terminals (like Emacs
453 # under Win32 have it set to None, and we need to have a known valid
453 # under Win32 have it set to None, and we need to have a known valid
454 # encoding to use in the raw_input() method
454 # encoding to use in the raw_input() method
455 try:
455 try:
456 self.stdin_encoding = sys.stdin.encoding or 'ascii'
456 self.stdin_encoding = sys.stdin.encoding or 'ascii'
457 except AttributeError:
457 except AttributeError:
458 self.stdin_encoding = 'ascii'
458 self.stdin_encoding = 'ascii'
459
459
460 def init_syntax_highlighting(self):
460 def init_syntax_highlighting(self):
461 # Python source parser/formatter for syntax highlighting
461 # Python source parser/formatter for syntax highlighting
462 pyformat = PyColorize.Parser().format
462 pyformat = PyColorize.Parser().format
463 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
463 self.pycolorize = lambda src: pyformat(src,'str',self.colors)
464
464
465 def init_pushd_popd_magic(self):
465 def init_pushd_popd_magic(self):
466 # for pushd/popd management
466 # for pushd/popd management
467 try:
467 try:
468 self.home_dir = get_home_dir()
468 self.home_dir = get_home_dir()
469 except HomeDirError, msg:
469 except HomeDirError, msg:
470 fatal(msg)
470 fatal(msg)
471
471
472 self.dir_stack = []
472 self.dir_stack = []
473
473
474 def init_logger(self):
474 def init_logger(self):
475 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
475 self.logger = Logger(self, logfname='ipython_log.py', logmode='rotate')
476 # local shortcut, this is used a LOT
476 # local shortcut, this is used a LOT
477 self.log = self.logger.log
477 self.log = self.logger.log
478
478
479 def init_logstart(self):
479 def init_logstart(self):
480 if self.logappend:
480 if self.logappend:
481 self.magic_logstart(self.logappend + ' append')
481 self.magic_logstart(self.logappend + ' append')
482 elif self.logfile:
482 elif self.logfile:
483 self.magic_logstart(self.logfile)
483 self.magic_logstart(self.logfile)
484 elif self.logstart:
484 elif self.logstart:
485 self.magic_logstart()
485 self.magic_logstart()
486
486
487 def init_builtins(self):
487 def init_builtins(self):
488 self.builtin_trap = BuiltinTrap(self)
488 self.builtin_trap = BuiltinTrap(self)
489
489
490 def init_inspector(self):
490 def init_inspector(self):
491 # Object inspector
491 # Object inspector
492 self.inspector = oinspect.Inspector(oinspect.InspectColors,
492 self.inspector = oinspect.Inspector(oinspect.InspectColors,
493 PyColorize.ANSICodeColors,
493 PyColorize.ANSICodeColors,
494 'NoColor',
494 'NoColor',
495 self.object_info_string_level)
495 self.object_info_string_level)
496
496
497 def init_prompts(self):
497 def init_prompts(self):
498 # Initialize cache, set in/out prompts and printing system
498 # Initialize cache, set in/out prompts and printing system
499 self.outputcache = CachedOutput(self,
499 self.outputcache = CachedOutput(self,
500 self.cache_size,
500 self.cache_size,
501 self.pprint,
501 self.pprint,
502 input_sep = self.separate_in,
502 input_sep = self.separate_in,
503 output_sep = self.separate_out,
503 output_sep = self.separate_out,
504 output_sep2 = self.separate_out2,
504 output_sep2 = self.separate_out2,
505 ps1 = self.prompt_in1,
505 ps1 = self.prompt_in1,
506 ps2 = self.prompt_in2,
506 ps2 = self.prompt_in2,
507 ps_out = self.prompt_out,
507 ps_out = self.prompt_out,
508 pad_left = self.prompts_pad_left)
508 pad_left = self.prompts_pad_left)
509
509
510 # user may have over-ridden the default print hook:
510 # user may have over-ridden the default print hook:
511 try:
511 try:
512 self.outputcache.__class__.display = self.hooks.display
512 self.outputcache.__class__.display = self.hooks.display
513 except AttributeError:
513 except AttributeError:
514 pass
514 pass
515
515
516 def init_displayhook(self):
516 def init_displayhook(self):
517 self.display_trap = DisplayTrap(self, self.outputcache)
517 self.display_trap = DisplayTrap(self, self.outputcache)
518
518
519 def init_reload_doctest(self):
519 def init_reload_doctest(self):
520 # Do a proper resetting of doctest, including the necessary displayhook
520 # Do a proper resetting of doctest, including the necessary displayhook
521 # monkeypatching
521 # monkeypatching
522 try:
522 try:
523 doctest_reload()
523 doctest_reload()
524 except ImportError:
524 except ImportError:
525 warn("doctest module does not exist.")
525 warn("doctest module does not exist.")
526
526
527 #-------------------------------------------------------------------------
527 #-------------------------------------------------------------------------
528 # Things related to the banner
528 # Things related to the banner
529 #-------------------------------------------------------------------------
529 #-------------------------------------------------------------------------
530
530
531 def init_banner(self, banner1, banner2, display_banner):
531 def init_banner(self, banner1, banner2, display_banner):
532 if banner1 is not None:
532 if banner1 is not None:
533 self.banner1 = banner1
533 self.banner1 = banner1
534 if banner2 is not None:
534 if banner2 is not None:
535 self.banner2 = banner2
535 self.banner2 = banner2
536 if display_banner is not None:
536 if display_banner is not None:
537 self.display_banner = display_banner
537 self.display_banner = display_banner
538 self.compute_banner()
538 self.compute_banner()
539
539
540 def show_banner(self, banner=None):
540 def show_banner(self, banner=None):
541 if banner is None:
541 if banner is None:
542 banner = self.banner
542 banner = self.banner
543 self.write(banner)
543 self.write(banner)
544
544
545 def compute_banner(self):
545 def compute_banner(self):
546 self.banner = self.banner1 + '\n'
546 self.banner = self.banner1 + '\n'
547 if self.profile:
547 if self.profile:
548 self.banner += '\nIPython profile: %s\n' % self.profile
548 self.banner += '\nIPython profile: %s\n' % self.profile
549 if self.banner2:
549 if self.banner2:
550 self.banner += '\n' + self.banner2 + '\n'
550 self.banner += '\n' + self.banner2 + '\n'
551
551
552 #-------------------------------------------------------------------------
552 #-------------------------------------------------------------------------
553 # Things related to injections into the sys module
553 # Things related to injections into the sys module
554 #-------------------------------------------------------------------------
554 #-------------------------------------------------------------------------
555
555
556 def save_sys_module_state(self):
556 def save_sys_module_state(self):
557 """Save the state of hooks in the sys module.
557 """Save the state of hooks in the sys module.
558
558
559 This has to be called after self.user_ns is created.
559 This has to be called after self.user_ns is created.
560 """
560 """
561 self._orig_sys_module_state = {}
561 self._orig_sys_module_state = {}
562 self._orig_sys_module_state['stdin'] = sys.stdin
562 self._orig_sys_module_state['stdin'] = sys.stdin
563 self._orig_sys_module_state['stdout'] = sys.stdout
563 self._orig_sys_module_state['stdout'] = sys.stdout
564 self._orig_sys_module_state['stderr'] = sys.stderr
564 self._orig_sys_module_state['stderr'] = sys.stderr
565 self._orig_sys_module_state['excepthook'] = sys.excepthook
565 self._orig_sys_module_state['excepthook'] = sys.excepthook
566 try:
566 try:
567 self._orig_sys_modules_main_name = self.user_ns['__name__']
567 self._orig_sys_modules_main_name = self.user_ns['__name__']
568 except KeyError:
568 except KeyError:
569 pass
569 pass
570
570
571 def restore_sys_module_state(self):
571 def restore_sys_module_state(self):
572 """Restore the state of the sys module."""
572 """Restore the state of the sys module."""
573 try:
573 try:
574 for k, v in self._orig_sys_module_state.items():
574 for k, v in self._orig_sys_module_state.items():
575 setattr(sys, k, v)
575 setattr(sys, k, v)
576 except AttributeError:
576 except AttributeError:
577 pass
577 pass
578 try:
578 try:
579 delattr(sys, 'ipcompleter')
579 delattr(sys, 'ipcompleter')
580 except AttributeError:
580 except AttributeError:
581 pass
581 pass
582 # Reset what what done in self.init_sys_modules
582 # Reset what what done in self.init_sys_modules
583 try:
583 try:
584 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
584 sys.modules[self.user_ns['__name__']] = self._orig_sys_modules_main_name
585 except (AttributeError, KeyError):
585 except (AttributeError, KeyError):
586 pass
586 pass
587
587
588 #-------------------------------------------------------------------------
588 #-------------------------------------------------------------------------
589 # Things related to hooks
589 # Things related to hooks
590 #-------------------------------------------------------------------------
590 #-------------------------------------------------------------------------
591
591
592 def init_hooks(self):
592 def init_hooks(self):
593 # hooks holds pointers used for user-side customizations
593 # hooks holds pointers used for user-side customizations
594 self.hooks = Struct()
594 self.hooks = Struct()
595
595
596 self.strdispatchers = {}
596 self.strdispatchers = {}
597
597
598 # Set all default hooks, defined in the IPython.hooks module.
598 # Set all default hooks, defined in the IPython.hooks module.
599 import IPython.core.hooks
599 import IPython.core.hooks
600 hooks = IPython.core.hooks
600 hooks = IPython.core.hooks
601 for hook_name in hooks.__all__:
601 for hook_name in hooks.__all__:
602 # default hooks have priority 100, i.e. low; user hooks should have
602 # default hooks have priority 100, i.e. low; user hooks should have
603 # 0-100 priority
603 # 0-100 priority
604 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
604 self.set_hook(hook_name,getattr(hooks,hook_name), 100)
605
605
606 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
606 def set_hook(self,name,hook, priority = 50, str_key = None, re_key = None):
607 """set_hook(name,hook) -> sets an internal IPython hook.
607 """set_hook(name,hook) -> sets an internal IPython hook.
608
608
609 IPython exposes some of its internal API as user-modifiable hooks. By
609 IPython exposes some of its internal API as user-modifiable hooks. By
610 adding your function to one of these hooks, you can modify IPython's
610 adding your function to one of these hooks, you can modify IPython's
611 behavior to call at runtime your own routines."""
611 behavior to call at runtime your own routines."""
612
612
613 # At some point in the future, this should validate the hook before it
613 # At some point in the future, this should validate the hook before it
614 # accepts it. Probably at least check that the hook takes the number
614 # accepts it. Probably at least check that the hook takes the number
615 # of args it's supposed to.
615 # of args it's supposed to.
616
616
617 f = new.instancemethod(hook,self,self.__class__)
617 f = new.instancemethod(hook,self,self.__class__)
618
618
619 # check if the hook is for strdispatcher first
619 # check if the hook is for strdispatcher first
620 if str_key is not None:
620 if str_key is not None:
621 sdp = self.strdispatchers.get(name, StrDispatch())
621 sdp = self.strdispatchers.get(name, StrDispatch())
622 sdp.add_s(str_key, f, priority )
622 sdp.add_s(str_key, f, priority )
623 self.strdispatchers[name] = sdp
623 self.strdispatchers[name] = sdp
624 return
624 return
625 if re_key is not None:
625 if re_key is not None:
626 sdp = self.strdispatchers.get(name, StrDispatch())
626 sdp = self.strdispatchers.get(name, StrDispatch())
627 sdp.add_re(re.compile(re_key), f, priority )
627 sdp.add_re(re.compile(re_key), f, priority )
628 self.strdispatchers[name] = sdp
628 self.strdispatchers[name] = sdp
629 return
629 return
630
630
631 dp = getattr(self.hooks, name, None)
631 dp = getattr(self.hooks, name, None)
632 if name not in IPython.core.hooks.__all__:
632 if name not in IPython.core.hooks.__all__:
633 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
633 print "Warning! Hook '%s' is not one of %s" % (name, IPython.core.hooks.__all__ )
634 if not dp:
634 if not dp:
635 dp = IPython.core.hooks.CommandChainDispatcher()
635 dp = IPython.core.hooks.CommandChainDispatcher()
636
636
637 try:
637 try:
638 dp.add(f,priority)
638 dp.add(f,priority)
639 except AttributeError:
639 except AttributeError:
640 # it was not commandchain, plain old func - replace
640 # it was not commandchain, plain old func - replace
641 dp = f
641 dp = f
642
642
643 setattr(self.hooks,name, dp)
643 setattr(self.hooks,name, dp)
644
644
645 #-------------------------------------------------------------------------
645 #-------------------------------------------------------------------------
646 # Things related to the "main" module
646 # Things related to the "main" module
647 #-------------------------------------------------------------------------
647 #-------------------------------------------------------------------------
648
648
649 def new_main_mod(self,ns=None):
649 def new_main_mod(self,ns=None):
650 """Return a new 'main' module object for user code execution.
650 """Return a new 'main' module object for user code execution.
651 """
651 """
652 main_mod = self._user_main_module
652 main_mod = self._user_main_module
653 init_fakemod_dict(main_mod,ns)
653 init_fakemod_dict(main_mod,ns)
654 return main_mod
654 return main_mod
655
655
656 def cache_main_mod(self,ns,fname):
656 def cache_main_mod(self,ns,fname):
657 """Cache a main module's namespace.
657 """Cache a main module's namespace.
658
658
659 When scripts are executed via %run, we must keep a reference to the
659 When scripts are executed via %run, we must keep a reference to the
660 namespace of their __main__ module (a FakeModule instance) around so
660 namespace of their __main__ module (a FakeModule instance) around so
661 that Python doesn't clear it, rendering objects defined therein
661 that Python doesn't clear it, rendering objects defined therein
662 useless.
662 useless.
663
663
664 This method keeps said reference in a private dict, keyed by the
664 This method keeps said reference in a private dict, keyed by the
665 absolute path of the module object (which corresponds to the script
665 absolute path of the module object (which corresponds to the script
666 path). This way, for multiple executions of the same script we only
666 path). This way, for multiple executions of the same script we only
667 keep one copy of the namespace (the last one), thus preventing memory
667 keep one copy of the namespace (the last one), thus preventing memory
668 leaks from old references while allowing the objects from the last
668 leaks from old references while allowing the objects from the last
669 execution to be accessible.
669 execution to be accessible.
670
670
671 Note: we can not allow the actual FakeModule instances to be deleted,
671 Note: we can not allow the actual FakeModule instances to be deleted,
672 because of how Python tears down modules (it hard-sets all their
672 because of how Python tears down modules (it hard-sets all their
673 references to None without regard for reference counts). This method
673 references to None without regard for reference counts). This method
674 must therefore make a *copy* of the given namespace, to allow the
674 must therefore make a *copy* of the given namespace, to allow the
675 original module's __dict__ to be cleared and reused.
675 original module's __dict__ to be cleared and reused.
676
676
677
677
678 Parameters
678 Parameters
679 ----------
679 ----------
680 ns : a namespace (a dict, typically)
680 ns : a namespace (a dict, typically)
681
681
682 fname : str
682 fname : str
683 Filename associated with the namespace.
683 Filename associated with the namespace.
684
684
685 Examples
685 Examples
686 --------
686 --------
687
687
688 In [10]: import IPython
688 In [10]: import IPython
689
689
690 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
690 In [11]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
691
691
692 In [12]: IPython.__file__ in _ip._main_ns_cache
692 In [12]: IPython.__file__ in _ip._main_ns_cache
693 Out[12]: True
693 Out[12]: True
694 """
694 """
695 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
695 self._main_ns_cache[os.path.abspath(fname)] = ns.copy()
696
696
697 def clear_main_mod_cache(self):
697 def clear_main_mod_cache(self):
698 """Clear the cache of main modules.
698 """Clear the cache of main modules.
699
699
700 Mainly for use by utilities like %reset.
700 Mainly for use by utilities like %reset.
701
701
702 Examples
702 Examples
703 --------
703 --------
704
704
705 In [15]: import IPython
705 In [15]: import IPython
706
706
707 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
707 In [16]: _ip.cache_main_mod(IPython.__dict__,IPython.__file__)
708
708
709 In [17]: len(_ip._main_ns_cache) > 0
709 In [17]: len(_ip._main_ns_cache) > 0
710 Out[17]: True
710 Out[17]: True
711
711
712 In [18]: _ip.clear_main_mod_cache()
712 In [18]: _ip.clear_main_mod_cache()
713
713
714 In [19]: len(_ip._main_ns_cache) == 0
714 In [19]: len(_ip._main_ns_cache) == 0
715 Out[19]: True
715 Out[19]: True
716 """
716 """
717 self._main_ns_cache.clear()
717 self._main_ns_cache.clear()
718
718
719 #-------------------------------------------------------------------------
719 #-------------------------------------------------------------------------
720 # Things related to debugging
720 # Things related to debugging
721 #-------------------------------------------------------------------------
721 #-------------------------------------------------------------------------
722
722
723 def init_pdb(self):
723 def init_pdb(self):
724 # Set calling of pdb on exceptions
724 # Set calling of pdb on exceptions
725 # self.call_pdb is a property
725 # self.call_pdb is a property
726 self.call_pdb = self.pdb
726 self.call_pdb = self.pdb
727
727
728 def _get_call_pdb(self):
728 def _get_call_pdb(self):
729 return self._call_pdb
729 return self._call_pdb
730
730
731 def _set_call_pdb(self,val):
731 def _set_call_pdb(self,val):
732
732
733 if val not in (0,1,False,True):
733 if val not in (0,1,False,True):
734 raise ValueError,'new call_pdb value must be boolean'
734 raise ValueError,'new call_pdb value must be boolean'
735
735
736 # store value in instance
736 # store value in instance
737 self._call_pdb = val
737 self._call_pdb = val
738
738
739 # notify the actual exception handlers
739 # notify the actual exception handlers
740 self.InteractiveTB.call_pdb = val
740 self.InteractiveTB.call_pdb = val
741 if self.isthreaded:
741 if self.isthreaded:
742 try:
742 try:
743 self.sys_excepthook.call_pdb = val
743 self.sys_excepthook.call_pdb = val
744 except:
744 except:
745 warn('Failed to activate pdb for threaded exception handler')
745 warn('Failed to activate pdb for threaded exception handler')
746
746
747 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
747 call_pdb = property(_get_call_pdb,_set_call_pdb,None,
748 'Control auto-activation of pdb at exceptions')
748 'Control auto-activation of pdb at exceptions')
749
749
750 def debugger(self,force=False):
750 def debugger(self,force=False):
751 """Call the pydb/pdb debugger.
751 """Call the pydb/pdb debugger.
752
752
753 Keywords:
753 Keywords:
754
754
755 - force(False): by default, this routine checks the instance call_pdb
755 - force(False): by default, this routine checks the instance call_pdb
756 flag and does not actually invoke the debugger if the flag is false.
756 flag and does not actually invoke the debugger if the flag is false.
757 The 'force' option forces the debugger to activate even if the flag
757 The 'force' option forces the debugger to activate even if the flag
758 is false.
758 is false.
759 """
759 """
760
760
761 if not (force or self.call_pdb):
761 if not (force or self.call_pdb):
762 return
762 return
763
763
764 if not hasattr(sys,'last_traceback'):
764 if not hasattr(sys,'last_traceback'):
765 error('No traceback has been produced, nothing to debug.')
765 error('No traceback has been produced, nothing to debug.')
766 return
766 return
767
767
768 # use pydb if available
768 # use pydb if available
769 if debugger.has_pydb:
769 if debugger.has_pydb:
770 from pydb import pm
770 from pydb import pm
771 else:
771 else:
772 # fallback to our internal debugger
772 # fallback to our internal debugger
773 pm = lambda : self.InteractiveTB.debugger(force=True)
773 pm = lambda : self.InteractiveTB.debugger(force=True)
774 self.history_saving_wrapper(pm)()
774 self.history_saving_wrapper(pm)()
775
775
776 #-------------------------------------------------------------------------
776 #-------------------------------------------------------------------------
777 # Things related to IPython's various namespaces
777 # Things related to IPython's various namespaces
778 #-------------------------------------------------------------------------
778 #-------------------------------------------------------------------------
779
779
780 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
780 def init_create_namespaces(self, user_ns=None, user_global_ns=None):
781 # Create the namespace where the user will operate. user_ns is
781 # Create the namespace where the user will operate. user_ns is
782 # normally the only one used, and it is passed to the exec calls as
782 # normally the only one used, and it is passed to the exec calls as
783 # the locals argument. But we do carry a user_global_ns namespace
783 # the locals argument. But we do carry a user_global_ns namespace
784 # given as the exec 'globals' argument, This is useful in embedding
784 # given as the exec 'globals' argument, This is useful in embedding
785 # situations where the ipython shell opens in a context where the
785 # situations where the ipython shell opens in a context where the
786 # distinction between locals and globals is meaningful. For
786 # distinction between locals and globals is meaningful. For
787 # non-embedded contexts, it is just the same object as the user_ns dict.
787 # non-embedded contexts, it is just the same object as the user_ns dict.
788
788
789 # FIXME. For some strange reason, __builtins__ is showing up at user
789 # FIXME. For some strange reason, __builtins__ is showing up at user
790 # level as a dict instead of a module. This is a manual fix, but I
790 # level as a dict instead of a module. This is a manual fix, but I
791 # should really track down where the problem is coming from. Alex
791 # should really track down where the problem is coming from. Alex
792 # Schmolck reported this problem first.
792 # Schmolck reported this problem first.
793
793
794 # A useful post by Alex Martelli on this topic:
794 # A useful post by Alex Martelli on this topic:
795 # Re: inconsistent value from __builtins__
795 # Re: inconsistent value from __builtins__
796 # Von: Alex Martelli <aleaxit@yahoo.com>
796 # Von: Alex Martelli <aleaxit@yahoo.com>
797 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
797 # Datum: Freitag 01 Oktober 2004 04:45:34 nachmittags/abends
798 # Gruppen: comp.lang.python
798 # Gruppen: comp.lang.python
799
799
800 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
800 # Michael Hohn <hohn@hooknose.lbl.gov> wrote:
801 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
801 # > >>> print type(builtin_check.get_global_binding('__builtins__'))
802 # > <type 'dict'>
802 # > <type 'dict'>
803 # > >>> print type(__builtins__)
803 # > >>> print type(__builtins__)
804 # > <type 'module'>
804 # > <type 'module'>
805 # > Is this difference in return value intentional?
805 # > Is this difference in return value intentional?
806
806
807 # Well, it's documented that '__builtins__' can be either a dictionary
807 # Well, it's documented that '__builtins__' can be either a dictionary
808 # or a module, and it's been that way for a long time. Whether it's
808 # or a module, and it's been that way for a long time. Whether it's
809 # intentional (or sensible), I don't know. In any case, the idea is
809 # intentional (or sensible), I don't know. In any case, the idea is
810 # that if you need to access the built-in namespace directly, you
810 # that if you need to access the built-in namespace directly, you
811 # should start with "import __builtin__" (note, no 's') which will
811 # should start with "import __builtin__" (note, no 's') which will
812 # definitely give you a module. Yeah, it's somewhat confusing:-(.
812 # definitely give you a module. Yeah, it's somewhat confusing:-(.
813
813
814 # These routines return properly built dicts as needed by the rest of
814 # These routines return properly built dicts as needed by the rest of
815 # the code, and can also be used by extension writers to generate
815 # the code, and can also be used by extension writers to generate
816 # properly initialized namespaces.
816 # properly initialized namespaces.
817 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
817 user_ns, user_global_ns = self.make_user_namespaces(user_ns,
818 user_global_ns)
818 user_global_ns)
819
819
820 # Assign namespaces
820 # Assign namespaces
821 # This is the namespace where all normal user variables live
821 # This is the namespace where all normal user variables live
822 self.user_ns = user_ns
822 self.user_ns = user_ns
823 self.user_global_ns = user_global_ns
823 self.user_global_ns = user_global_ns
824
824
825 # An auxiliary namespace that checks what parts of the user_ns were
825 # An auxiliary namespace that checks what parts of the user_ns were
826 # loaded at startup, so we can list later only variables defined in
826 # loaded at startup, so we can list later only variables defined in
827 # actual interactive use. Since it is always a subset of user_ns, it
827 # actual interactive use. Since it is always a subset of user_ns, it
828 # doesn't need to be seaparately tracked in the ns_table
828 # doesn't need to be seaparately tracked in the ns_table
829 self.user_config_ns = {}
829 self.user_config_ns = {}
830
830
831 # A namespace to keep track of internal data structures to prevent
831 # A namespace to keep track of internal data structures to prevent
832 # them from cluttering user-visible stuff. Will be updated later
832 # them from cluttering user-visible stuff. Will be updated later
833 self.internal_ns = {}
833 self.internal_ns = {}
834
834
835 # Now that FakeModule produces a real module, we've run into a nasty
835 # Now that FakeModule produces a real module, we've run into a nasty
836 # problem: after script execution (via %run), the module where the user
836 # problem: after script execution (via %run), the module where the user
837 # code ran is deleted. Now that this object is a true module (needed
837 # code ran is deleted. Now that this object is a true module (needed
838 # so docetst and other tools work correctly), the Python module
838 # so docetst and other tools work correctly), the Python module
839 # teardown mechanism runs over it, and sets to None every variable
839 # teardown mechanism runs over it, and sets to None every variable
840 # present in that module. Top-level references to objects from the
840 # present in that module. Top-level references to objects from the
841 # script survive, because the user_ns is updated with them. However,
841 # script survive, because the user_ns is updated with them. However,
842 # calling functions defined in the script that use other things from
842 # calling functions defined in the script that use other things from
843 # the script will fail, because the function's closure had references
843 # the script will fail, because the function's closure had references
844 # to the original objects, which are now all None. So we must protect
844 # to the original objects, which are now all None. So we must protect
845 # these modules from deletion by keeping a cache.
845 # these modules from deletion by keeping a cache.
846 #
846 #
847 # To avoid keeping stale modules around (we only need the one from the
847 # To avoid keeping stale modules around (we only need the one from the
848 # last run), we use a dict keyed with the full path to the script, so
848 # last run), we use a dict keyed with the full path to the script, so
849 # only the last version of the module is held in the cache. Note,
849 # only the last version of the module is held in the cache. Note,
850 # however, that we must cache the module *namespace contents* (their
850 # however, that we must cache the module *namespace contents* (their
851 # __dict__). Because if we try to cache the actual modules, old ones
851 # __dict__). Because if we try to cache the actual modules, old ones
852 # (uncached) could be destroyed while still holding references (such as
852 # (uncached) could be destroyed while still holding references (such as
853 # those held by GUI objects that tend to be long-lived)>
853 # those held by GUI objects that tend to be long-lived)>
854 #
854 #
855 # The %reset command will flush this cache. See the cache_main_mod()
855 # The %reset command will flush this cache. See the cache_main_mod()
856 # and clear_main_mod_cache() methods for details on use.
856 # and clear_main_mod_cache() methods for details on use.
857
857
858 # This is the cache used for 'main' namespaces
858 # This is the cache used for 'main' namespaces
859 self._main_ns_cache = {}
859 self._main_ns_cache = {}
860 # And this is the single instance of FakeModule whose __dict__ we keep
860 # And this is the single instance of FakeModule whose __dict__ we keep
861 # copying and clearing for reuse on each %run
861 # copying and clearing for reuse on each %run
862 self._user_main_module = FakeModule()
862 self._user_main_module = FakeModule()
863
863
864 # A table holding all the namespaces IPython deals with, so that
864 # A table holding all the namespaces IPython deals with, so that
865 # introspection facilities can search easily.
865 # introspection facilities can search easily.
866 self.ns_table = {'user':user_ns,
866 self.ns_table = {'user':user_ns,
867 'user_global':user_global_ns,
867 'user_global':user_global_ns,
868 'internal':self.internal_ns,
868 'internal':self.internal_ns,
869 'builtin':__builtin__.__dict__
869 'builtin':__builtin__.__dict__
870 }
870 }
871
871
872 # Similarly, track all namespaces where references can be held and that
872 # Similarly, track all namespaces where references can be held and that
873 # we can safely clear (so it can NOT include builtin). This one can be
873 # we can safely clear (so it can NOT include builtin). This one can be
874 # a simple list.
874 # a simple list.
875 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
875 self.ns_refs_table = [ user_ns, user_global_ns, self.user_config_ns,
876 self.internal_ns, self._main_ns_cache ]
876 self.internal_ns, self._main_ns_cache ]
877
877
878 def init_sys_modules(self):
878 def init_sys_modules(self):
879 # We need to insert into sys.modules something that looks like a
879 # We need to insert into sys.modules something that looks like a
880 # module but which accesses the IPython namespace, for shelve and
880 # module but which accesses the IPython namespace, for shelve and
881 # pickle to work interactively. Normally they rely on getting
881 # pickle to work interactively. Normally they rely on getting
882 # everything out of __main__, but for embedding purposes each IPython
882 # everything out of __main__, but for embedding purposes each IPython
883 # instance has its own private namespace, so we can't go shoving
883 # instance has its own private namespace, so we can't go shoving
884 # everything into __main__.
884 # everything into __main__.
885
885
886 # note, however, that we should only do this for non-embedded
886 # note, however, that we should only do this for non-embedded
887 # ipythons, which really mimic the __main__.__dict__ with their own
887 # ipythons, which really mimic the __main__.__dict__ with their own
888 # namespace. Embedded instances, on the other hand, should not do
888 # namespace. Embedded instances, on the other hand, should not do
889 # this because they need to manage the user local/global namespaces
889 # this because they need to manage the user local/global namespaces
890 # only, but they live within a 'normal' __main__ (meaning, they
890 # only, but they live within a 'normal' __main__ (meaning, they
891 # shouldn't overtake the execution environment of the script they're
891 # shouldn't overtake the execution environment of the script they're
892 # embedded in).
892 # embedded in).
893
893
894 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
894 # This is overridden in the InteractiveShellEmbed subclass to a no-op.
895
895
896 try:
896 try:
897 main_name = self.user_ns['__name__']
897 main_name = self.user_ns['__name__']
898 except KeyError:
898 except KeyError:
899 raise KeyError('user_ns dictionary MUST have a "__name__" key')
899 raise KeyError('user_ns dictionary MUST have a "__name__" key')
900 else:
900 else:
901 sys.modules[main_name] = FakeModule(self.user_ns)
901 sys.modules[main_name] = FakeModule(self.user_ns)
902
902
903 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
903 def make_user_namespaces(self, user_ns=None, user_global_ns=None):
904 """Return a valid local and global user interactive namespaces.
904 """Return a valid local and global user interactive namespaces.
905
905
906 This builds a dict with the minimal information needed to operate as a
906 This builds a dict with the minimal information needed to operate as a
907 valid IPython user namespace, which you can pass to the various
907 valid IPython user namespace, which you can pass to the various
908 embedding classes in ipython. The default implementation returns the
908 embedding classes in ipython. The default implementation returns the
909 same dict for both the locals and the globals to allow functions to
909 same dict for both the locals and the globals to allow functions to
910 refer to variables in the namespace. Customized implementations can
910 refer to variables in the namespace. Customized implementations can
911 return different dicts. The locals dictionary can actually be anything
911 return different dicts. The locals dictionary can actually be anything
912 following the basic mapping protocol of a dict, but the globals dict
912 following the basic mapping protocol of a dict, but the globals dict
913 must be a true dict, not even a subclass. It is recommended that any
913 must be a true dict, not even a subclass. It is recommended that any
914 custom object for the locals namespace synchronize with the globals
914 custom object for the locals namespace synchronize with the globals
915 dict somehow.
915 dict somehow.
916
916
917 Raises TypeError if the provided globals namespace is not a true dict.
917 Raises TypeError if the provided globals namespace is not a true dict.
918
918
919 :Parameters:
919 :Parameters:
920 user_ns : dict-like, optional
920 user_ns : dict-like, optional
921 The current user namespace. The items in this namespace should
921 The current user namespace. The items in this namespace should
922 be included in the output. If None, an appropriate blank
922 be included in the output. If None, an appropriate blank
923 namespace should be created.
923 namespace should be created.
924 user_global_ns : dict, optional
924 user_global_ns : dict, optional
925 The current user global namespace. The items in this namespace
925 The current user global namespace. The items in this namespace
926 should be included in the output. If None, an appropriate
926 should be included in the output. If None, an appropriate
927 blank namespace should be created.
927 blank namespace should be created.
928
928
929 :Returns:
929 :Returns:
930 A tuple pair of dictionary-like object to be used as the local namespace
930 A tuple pair of dictionary-like object to be used as the local namespace
931 of the interpreter and a dict to be used as the global namespace.
931 of the interpreter and a dict to be used as the global namespace.
932 """
932 """
933
933
934 if user_ns is None:
934 if user_ns is None:
935 # Set __name__ to __main__ to better match the behavior of the
935 # Set __name__ to __main__ to better match the behavior of the
936 # normal interpreter.
936 # normal interpreter.
937 user_ns = {'__name__' :'__main__',
937 user_ns = {'__name__' :'__main__',
938 '__builtins__' : __builtin__,
938 '__builtins__' : __builtin__,
939 }
939 }
940 else:
940 else:
941 user_ns.setdefault('__name__','__main__')
941 user_ns.setdefault('__name__','__main__')
942 user_ns.setdefault('__builtins__',__builtin__)
942 user_ns.setdefault('__builtins__',__builtin__)
943
943
944 if user_global_ns is None:
944 if user_global_ns is None:
945 user_global_ns = user_ns
945 user_global_ns = user_ns
946 if type(user_global_ns) is not dict:
946 if type(user_global_ns) is not dict:
947 raise TypeError("user_global_ns must be a true dict; got %r"
947 raise TypeError("user_global_ns must be a true dict; got %r"
948 % type(user_global_ns))
948 % type(user_global_ns))
949
949
950 return user_ns, user_global_ns
950 return user_ns, user_global_ns
951
951
952 def init_user_ns(self):
952 def init_user_ns(self):
953 """Initialize all user-visible namespaces to their minimum defaults.
953 """Initialize all user-visible namespaces to their minimum defaults.
954
954
955 Certain history lists are also initialized here, as they effectively
955 Certain history lists are also initialized here, as they effectively
956 act as user namespaces.
956 act as user namespaces.
957
957
958 Notes
958 Notes
959 -----
959 -----
960 All data structures here are only filled in, they are NOT reset by this
960 All data structures here are only filled in, they are NOT reset by this
961 method. If they were not empty before, data will simply be added to
961 method. If they were not empty before, data will simply be added to
962 therm.
962 therm.
963 """
963 """
964 # Store myself as the public api!!!
964 # Store myself as the public api!!!
965 self.user_ns['get_ipython'] = self.get_ipython
965 self.user_ns['get_ipython'] = self.get_ipython
966
966
967 # make global variables for user access to the histories
967 # make global variables for user access to the histories
968 self.user_ns['_ih'] = self.input_hist
968 self.user_ns['_ih'] = self.input_hist
969 self.user_ns['_oh'] = self.output_hist
969 self.user_ns['_oh'] = self.output_hist
970 self.user_ns['_dh'] = self.dir_hist
970 self.user_ns['_dh'] = self.dir_hist
971
971
972 # user aliases to input and output histories
972 # user aliases to input and output histories
973 self.user_ns['In'] = self.input_hist
973 self.user_ns['In'] = self.input_hist
974 self.user_ns['Out'] = self.output_hist
974 self.user_ns['Out'] = self.output_hist
975
975
976 self.user_ns['_sh'] = shadowns
976 self.user_ns['_sh'] = shadowns
977
977
978 # Put 'help' in the user namespace
978 # Put 'help' in the user namespace
979 try:
979 try:
980 from site import _Helper
980 from site import _Helper
981 self.user_ns['help'] = _Helper()
981 self.user_ns['help'] = _Helper()
982 except ImportError:
982 except ImportError:
983 warn('help() not available - check site.py')
983 warn('help() not available - check site.py')
984
984
985 def reset(self):
985 def reset(self):
986 """Clear all internal namespaces.
986 """Clear all internal namespaces.
987
987
988 Note that this is much more aggressive than %reset, since it clears
988 Note that this is much more aggressive than %reset, since it clears
989 fully all namespaces, as well as all input/output lists.
989 fully all namespaces, as well as all input/output lists.
990 """
990 """
991 for ns in self.ns_refs_table:
991 for ns in self.ns_refs_table:
992 ns.clear()
992 ns.clear()
993
993
994 self.alias_manager.clear_aliases()
994 self.alias_manager.clear_aliases()
995
995
996 # Clear input and output histories
996 # Clear input and output histories
997 self.input_hist[:] = []
997 self.input_hist[:] = []
998 self.input_hist_raw[:] = []
998 self.input_hist_raw[:] = []
999 self.output_hist.clear()
999 self.output_hist.clear()
1000
1000
1001 # Restore the user namespaces to minimal usability
1001 # Restore the user namespaces to minimal usability
1002 self.init_user_ns()
1002 self.init_user_ns()
1003
1003
1004 # Restore the default and user aliases
1004 # Restore the default and user aliases
1005 self.alias_manager.init_aliases()
1005 self.alias_manager.init_aliases()
1006
1006
1007 def push(self, variables, interactive=True):
1007 def push(self, variables, interactive=True):
1008 """Inject a group of variables into the IPython user namespace.
1008 """Inject a group of variables into the IPython user namespace.
1009
1009
1010 Parameters
1010 Parameters
1011 ----------
1011 ----------
1012 variables : dict, str or list/tuple of str
1012 variables : dict, str or list/tuple of str
1013 The variables to inject into the user's namespace. If a dict,
1013 The variables to inject into the user's namespace. If a dict,
1014 a simple update is done. If a str, the string is assumed to
1014 a simple update is done. If a str, the string is assumed to
1015 have variable names separated by spaces. A list/tuple of str
1015 have variable names separated by spaces. A list/tuple of str
1016 can also be used to give the variable names. If just the variable
1016 can also be used to give the variable names. If just the variable
1017 names are give (list/tuple/str) then the variable values looked
1017 names are give (list/tuple/str) then the variable values looked
1018 up in the callers frame.
1018 up in the callers frame.
1019 interactive : bool
1019 interactive : bool
1020 If True (default), the variables will be listed with the ``who``
1020 If True (default), the variables will be listed with the ``who``
1021 magic.
1021 magic.
1022 """
1022 """
1023 vdict = None
1023 vdict = None
1024
1024
1025 # We need a dict of name/value pairs to do namespace updates.
1025 # We need a dict of name/value pairs to do namespace updates.
1026 if isinstance(variables, dict):
1026 if isinstance(variables, dict):
1027 vdict = variables
1027 vdict = variables
1028 elif isinstance(variables, (basestring, list, tuple)):
1028 elif isinstance(variables, (basestring, list, tuple)):
1029 if isinstance(variables, basestring):
1029 if isinstance(variables, basestring):
1030 vlist = variables.split()
1030 vlist = variables.split()
1031 else:
1031 else:
1032 vlist = variables
1032 vlist = variables
1033 vdict = {}
1033 vdict = {}
1034 cf = sys._getframe(1)
1034 cf = sys._getframe(1)
1035 for name in vlist:
1035 for name in vlist:
1036 try:
1036 try:
1037 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1037 vdict[name] = eval(name, cf.f_globals, cf.f_locals)
1038 except:
1038 except:
1039 print ('Could not get variable %s from %s' %
1039 print ('Could not get variable %s from %s' %
1040 (name,cf.f_code.co_name))
1040 (name,cf.f_code.co_name))
1041 else:
1041 else:
1042 raise ValueError('variables must be a dict/str/list/tuple')
1042 raise ValueError('variables must be a dict/str/list/tuple')
1043
1043
1044 # Propagate variables to user namespace
1044 # Propagate variables to user namespace
1045 self.user_ns.update(vdict)
1045 self.user_ns.update(vdict)
1046
1046
1047 # And configure interactive visibility
1047 # And configure interactive visibility
1048 config_ns = self.user_config_ns
1048 config_ns = self.user_config_ns
1049 if interactive:
1049 if interactive:
1050 for name, val in vdict.iteritems():
1050 for name, val in vdict.iteritems():
1051 config_ns.pop(name, None)
1051 config_ns.pop(name, None)
1052 else:
1052 else:
1053 for name,val in vdict.iteritems():
1053 for name,val in vdict.iteritems():
1054 config_ns[name] = val
1054 config_ns[name] = val
1055
1055
1056 #-------------------------------------------------------------------------
1056 #-------------------------------------------------------------------------
1057 # Things related to history management
1057 # Things related to history management
1058 #-------------------------------------------------------------------------
1058 #-------------------------------------------------------------------------
1059
1059
1060 def init_history(self):
1060 def init_history(self):
1061 # List of input with multi-line handling.
1061 # List of input with multi-line handling.
1062 self.input_hist = InputList()
1062 self.input_hist = InputList()
1063 # This one will hold the 'raw' input history, without any
1063 # This one will hold the 'raw' input history, without any
1064 # pre-processing. This will allow users to retrieve the input just as
1064 # pre-processing. This will allow users to retrieve the input just as
1065 # it was exactly typed in by the user, with %hist -r.
1065 # it was exactly typed in by the user, with %hist -r.
1066 self.input_hist_raw = InputList()
1066 self.input_hist_raw = InputList()
1067
1067
1068 # list of visited directories
1068 # list of visited directories
1069 try:
1069 try:
1070 self.dir_hist = [os.getcwd()]
1070 self.dir_hist = [os.getcwd()]
1071 except OSError:
1071 except OSError:
1072 self.dir_hist = []
1072 self.dir_hist = []
1073
1073
1074 # dict of output history
1074 # dict of output history
1075 self.output_hist = {}
1075 self.output_hist = {}
1076
1076
1077 # Now the history file
1077 # Now the history file
1078 if self.profile:
1078 if self.profile:
1079 histfname = 'history-%s' % self.profile
1079 histfname = 'history-%s' % self.profile
1080 else:
1080 else:
1081 histfname = 'history'
1081 histfname = 'history'
1082 self.histfile = os.path.join(self.ipython_dir, histfname)
1082 self.histfile = os.path.join(self.ipython_dir, histfname)
1083
1083
1084 # Fill the history zero entry, user counter starts at 1
1084 # Fill the history zero entry, user counter starts at 1
1085 self.input_hist.append('\n')
1085 self.input_hist.append('\n')
1086 self.input_hist_raw.append('\n')
1086 self.input_hist_raw.append('\n')
1087
1087
1088 def init_shadow_hist(self):
1088 def init_shadow_hist(self):
1089 try:
1089 try:
1090 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1090 self.db = pickleshare.PickleShareDB(self.ipython_dir + "/db")
1091 except exceptions.UnicodeDecodeError:
1091 except exceptions.UnicodeDecodeError:
1092 print "Your ipython_dir can't be decoded to unicode!"
1092 print "Your ipython_dir can't be decoded to unicode!"
1093 print "Please set HOME environment variable to something that"
1093 print "Please set HOME environment variable to something that"
1094 print r"only has ASCII characters, e.g. c:\home"
1094 print r"only has ASCII characters, e.g. c:\home"
1095 print "Now it is", self.ipython_dir
1095 print "Now it is", self.ipython_dir
1096 sys.exit()
1096 sys.exit()
1097 self.shadowhist = ipcorehist.ShadowHist(self.db)
1097 self.shadowhist = ipcorehist.ShadowHist(self.db)
1098
1098
1099 def savehist(self):
1099 def savehist(self):
1100 """Save input history to a file (via readline library)."""
1100 """Save input history to a file (via readline library)."""
1101
1101
1102 if not self.has_readline:
1102 if not self.has_readline:
1103 return
1103 return
1104
1104
1105 try:
1105 try:
1106 self.readline.write_history_file(self.histfile)
1106 self.readline.write_history_file(self.histfile)
1107 except:
1107 except:
1108 print 'Unable to save IPython command history to file: ' + \
1108 print 'Unable to save IPython command history to file: ' + \
1109 `self.histfile`
1109 `self.histfile`
1110
1110
1111 def reloadhist(self):
1111 def reloadhist(self):
1112 """Reload the input history from disk file."""
1112 """Reload the input history from disk file."""
1113
1113
1114 if self.has_readline:
1114 if self.has_readline:
1115 try:
1115 try:
1116 self.readline.clear_history()
1116 self.readline.clear_history()
1117 self.readline.read_history_file(self.shell.histfile)
1117 self.readline.read_history_file(self.shell.histfile)
1118 except AttributeError:
1118 except AttributeError:
1119 pass
1119 pass
1120
1120
1121 def history_saving_wrapper(self, func):
1121 def history_saving_wrapper(self, func):
1122 """ Wrap func for readline history saving
1122 """ Wrap func for readline history saving
1123
1123
1124 Convert func into callable that saves & restores
1124 Convert func into callable that saves & restores
1125 history around the call """
1125 history around the call """
1126
1126
1127 if not self.has_readline:
1127 if not self.has_readline:
1128 return func
1128 return func
1129
1129
1130 def wrapper():
1130 def wrapper():
1131 self.savehist()
1131 self.savehist()
1132 try:
1132 try:
1133 func()
1133 func()
1134 finally:
1134 finally:
1135 readline.read_history_file(self.histfile)
1135 readline.read_history_file(self.histfile)
1136 return wrapper
1136 return wrapper
1137
1137
1138 #-------------------------------------------------------------------------
1138 #-------------------------------------------------------------------------
1139 # Things related to exception handling and tracebacks (not debugging)
1139 # Things related to exception handling and tracebacks (not debugging)
1140 #-------------------------------------------------------------------------
1140 #-------------------------------------------------------------------------
1141
1141
1142 def init_traceback_handlers(self, custom_exceptions):
1142 def init_traceback_handlers(self, custom_exceptions):
1143 # Syntax error handler.
1143 # Syntax error handler.
1144 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
1144 self.SyntaxTB = SyntaxTB(color_scheme='NoColor')
1145
1145
1146 # The interactive one is initialized with an offset, meaning we always
1146 # The interactive one is initialized with an offset, meaning we always
1147 # want to remove the topmost item in the traceback, which is our own
1147 # want to remove the topmost item in the traceback, which is our own
1148 # internal code. Valid modes: ['Plain','Context','Verbose']
1148 # internal code. Valid modes: ['Plain','Context','Verbose']
1149 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1149 self.InteractiveTB = ultratb.AutoFormattedTB(mode = 'Plain',
1150 color_scheme='NoColor',
1150 color_scheme='NoColor',
1151 tb_offset = 1)
1151 tb_offset = 1)
1152
1152
1153 # IPython itself shouldn't crash. This will produce a detailed
1153 # IPython itself shouldn't crash. This will produce a detailed
1154 # post-mortem if it does. But we only install the crash handler for
1154 # post-mortem if it does. But we only install the crash handler for
1155 # non-threaded shells, the threaded ones use a normal verbose reporter
1155 # non-threaded shells, the threaded ones use a normal verbose reporter
1156 # and lose the crash handler. This is because exceptions in the main
1156 # and lose the crash handler. This is because exceptions in the main
1157 # thread (such as in GUI code) propagate directly to sys.excepthook,
1157 # thread (such as in GUI code) propagate directly to sys.excepthook,
1158 # and there's no point in printing crash dumps for every user exception.
1158 # and there's no point in printing crash dumps for every user exception.
1159 if self.isthreaded:
1159 if self.isthreaded:
1160 ipCrashHandler = ultratb.FormattedTB()
1160 ipCrashHandler = ultratb.FormattedTB()
1161 else:
1161 else:
1162 from IPython.core import crashhandler
1162 from IPython.core import crashhandler
1163 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
1163 ipCrashHandler = crashhandler.IPythonCrashHandler(self)
1164 self.set_crash_handler(ipCrashHandler)
1164 self.set_crash_handler(ipCrashHandler)
1165
1165
1166 # and add any custom exception handlers the user may have specified
1166 # and add any custom exception handlers the user may have specified
1167 self.set_custom_exc(*custom_exceptions)
1167 self.set_custom_exc(*custom_exceptions)
1168
1168
1169 def set_crash_handler(self, crashHandler):
1169 def set_crash_handler(self, crashHandler):
1170 """Set the IPython crash handler.
1170 """Set the IPython crash handler.
1171
1171
1172 This must be a callable with a signature suitable for use as
1172 This must be a callable with a signature suitable for use as
1173 sys.excepthook."""
1173 sys.excepthook."""
1174
1174
1175 # Install the given crash handler as the Python exception hook
1175 # Install the given crash handler as the Python exception hook
1176 sys.excepthook = crashHandler
1176 sys.excepthook = crashHandler
1177
1177
1178 # The instance will store a pointer to this, so that runtime code
1178 # The instance will store a pointer to this, so that runtime code
1179 # (such as magics) can access it. This is because during the
1179 # (such as magics) can access it. This is because during the
1180 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1180 # read-eval loop, it gets temporarily overwritten (to deal with GUI
1181 # frameworks).
1181 # frameworks).
1182 self.sys_excepthook = sys.excepthook
1182 self.sys_excepthook = sys.excepthook
1183
1183
1184 def set_custom_exc(self,exc_tuple,handler):
1184 def set_custom_exc(self,exc_tuple,handler):
1185 """set_custom_exc(exc_tuple,handler)
1185 """set_custom_exc(exc_tuple,handler)
1186
1186
1187 Set a custom exception handler, which will be called if any of the
1187 Set a custom exception handler, which will be called if any of the
1188 exceptions in exc_tuple occur in the mainloop (specifically, in the
1188 exceptions in exc_tuple occur in the mainloop (specifically, in the
1189 runcode() method.
1189 runcode() method.
1190
1190
1191 Inputs:
1191 Inputs:
1192
1192
1193 - exc_tuple: a *tuple* of valid exceptions to call the defined
1193 - exc_tuple: a *tuple* of valid exceptions to call the defined
1194 handler for. It is very important that you use a tuple, and NOT A
1194 handler for. It is very important that you use a tuple, and NOT A
1195 LIST here, because of the way Python's except statement works. If
1195 LIST here, because of the way Python's except statement works. If
1196 you only want to trap a single exception, use a singleton tuple:
1196 you only want to trap a single exception, use a singleton tuple:
1197
1197
1198 exc_tuple == (MyCustomException,)
1198 exc_tuple == (MyCustomException,)
1199
1199
1200 - handler: this must be defined as a function with the following
1200 - handler: this must be defined as a function with the following
1201 basic interface: def my_handler(self,etype,value,tb).
1201 basic interface: def my_handler(self,etype,value,tb).
1202
1202
1203 This will be made into an instance method (via new.instancemethod)
1203 This will be made into an instance method (via new.instancemethod)
1204 of IPython itself, and it will be called if any of the exceptions
1204 of IPython itself, and it will be called if any of the exceptions
1205 listed in the exc_tuple are caught. If the handler is None, an
1205 listed in the exc_tuple are caught. If the handler is None, an
1206 internal basic one is used, which just prints basic info.
1206 internal basic one is used, which just prints basic info.
1207
1207
1208 WARNING: by putting in your own exception handler into IPython's main
1208 WARNING: by putting in your own exception handler into IPython's main
1209 execution loop, you run a very good chance of nasty crashes. This
1209 execution loop, you run a very good chance of nasty crashes. This
1210 facility should only be used if you really know what you are doing."""
1210 facility should only be used if you really know what you are doing."""
1211
1211
1212 assert type(exc_tuple)==type(()) , \
1212 assert type(exc_tuple)==type(()) , \
1213 "The custom exceptions must be given AS A TUPLE."
1213 "The custom exceptions must be given AS A TUPLE."
1214
1214
1215 def dummy_handler(self,etype,value,tb):
1215 def dummy_handler(self,etype,value,tb):
1216 print '*** Simple custom exception handler ***'
1216 print '*** Simple custom exception handler ***'
1217 print 'Exception type :',etype
1217 print 'Exception type :',etype
1218 print 'Exception value:',value
1218 print 'Exception value:',value
1219 print 'Traceback :',tb
1219 print 'Traceback :',tb
1220 print 'Source code :','\n'.join(self.buffer)
1220 print 'Source code :','\n'.join(self.buffer)
1221
1221
1222 if handler is None: handler = dummy_handler
1222 if handler is None: handler = dummy_handler
1223
1223
1224 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1224 self.CustomTB = new.instancemethod(handler,self,self.__class__)
1225 self.custom_exceptions = exc_tuple
1225 self.custom_exceptions = exc_tuple
1226
1226
1227 def excepthook(self, etype, value, tb):
1227 def excepthook(self, etype, value, tb):
1228 """One more defense for GUI apps that call sys.excepthook.
1228 """One more defense for GUI apps that call sys.excepthook.
1229
1229
1230 GUI frameworks like wxPython trap exceptions and call
1230 GUI frameworks like wxPython trap exceptions and call
1231 sys.excepthook themselves. I guess this is a feature that
1231 sys.excepthook themselves. I guess this is a feature that
1232 enables them to keep running after exceptions that would
1232 enables them to keep running after exceptions that would
1233 otherwise kill their mainloop. This is a bother for IPython
1233 otherwise kill their mainloop. This is a bother for IPython
1234 which excepts to catch all of the program exceptions with a try:
1234 which excepts to catch all of the program exceptions with a try:
1235 except: statement.
1235 except: statement.
1236
1236
1237 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1237 Normally, IPython sets sys.excepthook to a CrashHandler instance, so if
1238 any app directly invokes sys.excepthook, it will look to the user like
1238 any app directly invokes sys.excepthook, it will look to the user like
1239 IPython crashed. In order to work around this, we can disable the
1239 IPython crashed. In order to work around this, we can disable the
1240 CrashHandler and replace it with this excepthook instead, which prints a
1240 CrashHandler and replace it with this excepthook instead, which prints a
1241 regular traceback using our InteractiveTB. In this fashion, apps which
1241 regular traceback using our InteractiveTB. In this fashion, apps which
1242 call sys.excepthook will generate a regular-looking exception from
1242 call sys.excepthook will generate a regular-looking exception from
1243 IPython, and the CrashHandler will only be triggered by real IPython
1243 IPython, and the CrashHandler will only be triggered by real IPython
1244 crashes.
1244 crashes.
1245
1245
1246 This hook should be used sparingly, only in places which are not likely
1246 This hook should be used sparingly, only in places which are not likely
1247 to be true IPython errors.
1247 to be true IPython errors.
1248 """
1248 """
1249 self.showtraceback((etype,value,tb),tb_offset=0)
1249 self.showtraceback((etype,value,tb),tb_offset=0)
1250
1250
1251 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1251 def showtraceback(self,exc_tuple = None,filename=None,tb_offset=None):
1252 """Display the exception that just occurred.
1252 """Display the exception that just occurred.
1253
1253
1254 If nothing is known about the exception, this is the method which
1254 If nothing is known about the exception, this is the method which
1255 should be used throughout the code for presenting user tracebacks,
1255 should be used throughout the code for presenting user tracebacks,
1256 rather than directly invoking the InteractiveTB object.
1256 rather than directly invoking the InteractiveTB object.
1257
1257
1258 A specific showsyntaxerror() also exists, but this method can take
1258 A specific showsyntaxerror() also exists, but this method can take
1259 care of calling it if needed, so unless you are explicitly catching a
1259 care of calling it if needed, so unless you are explicitly catching a
1260 SyntaxError exception, don't try to analyze the stack manually and
1260 SyntaxError exception, don't try to analyze the stack manually and
1261 simply call this method."""
1261 simply call this method."""
1262
1262
1263
1263
1264 # Though this won't be called by syntax errors in the input line,
1264 # Though this won't be called by syntax errors in the input line,
1265 # there may be SyntaxError cases whith imported code.
1265 # there may be SyntaxError cases whith imported code.
1266
1266
1267 try:
1267 try:
1268 if exc_tuple is None:
1268 if exc_tuple is None:
1269 etype, value, tb = sys.exc_info()
1269 etype, value, tb = sys.exc_info()
1270 else:
1270 else:
1271 etype, value, tb = exc_tuple
1271 etype, value, tb = exc_tuple
1272
1272
1273 if etype is SyntaxError:
1273 if etype is SyntaxError:
1274 self.showsyntaxerror(filename)
1274 self.showsyntaxerror(filename)
1275 elif etype is UsageError:
1275 elif etype is UsageError:
1276 print "UsageError:", value
1276 print "UsageError:", value
1277 else:
1277 else:
1278 # WARNING: these variables are somewhat deprecated and not
1278 # WARNING: these variables are somewhat deprecated and not
1279 # necessarily safe to use in a threaded environment, but tools
1279 # necessarily safe to use in a threaded environment, but tools
1280 # like pdb depend on their existence, so let's set them. If we
1280 # like pdb depend on their existence, so let's set them. If we
1281 # find problems in the field, we'll need to revisit their use.
1281 # find problems in the field, we'll need to revisit their use.
1282 sys.last_type = etype
1282 sys.last_type = etype
1283 sys.last_value = value
1283 sys.last_value = value
1284 sys.last_traceback = tb
1284 sys.last_traceback = tb
1285
1285
1286 if etype in self.custom_exceptions:
1286 if etype in self.custom_exceptions:
1287 self.CustomTB(etype,value,tb)
1287 self.CustomTB(etype,value,tb)
1288 else:
1288 else:
1289 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1289 self.InteractiveTB(etype,value,tb,tb_offset=tb_offset)
1290 if self.InteractiveTB.call_pdb and self.has_readline:
1290 if self.InteractiveTB.call_pdb and self.has_readline:
1291 # pdb mucks up readline, fix it back
1291 # pdb mucks up readline, fix it back
1292 self.set_completer()
1292 self.set_completer()
1293 except KeyboardInterrupt:
1293 except KeyboardInterrupt:
1294 self.write("\nKeyboardInterrupt\n")
1294 self.write("\nKeyboardInterrupt\n")
1295
1295
1296 def showsyntaxerror(self, filename=None):
1296 def showsyntaxerror(self, filename=None):
1297 """Display the syntax error that just occurred.
1297 """Display the syntax error that just occurred.
1298
1298
1299 This doesn't display a stack trace because there isn't one.
1299 This doesn't display a stack trace because there isn't one.
1300
1300
1301 If a filename is given, it is stuffed in the exception instead
1301 If a filename is given, it is stuffed in the exception instead
1302 of what was there before (because Python's parser always uses
1302 of what was there before (because Python's parser always uses
1303 "<string>" when reading from a string).
1303 "<string>" when reading from a string).
1304 """
1304 """
1305 etype, value, last_traceback = sys.exc_info()
1305 etype, value, last_traceback = sys.exc_info()
1306
1306
1307 # See note about these variables in showtraceback() below
1307 # See note about these variables in showtraceback() below
1308 sys.last_type = etype
1308 sys.last_type = etype
1309 sys.last_value = value
1309 sys.last_value = value
1310 sys.last_traceback = last_traceback
1310 sys.last_traceback = last_traceback
1311
1311
1312 if filename and etype is SyntaxError:
1312 if filename and etype is SyntaxError:
1313 # Work hard to stuff the correct filename in the exception
1313 # Work hard to stuff the correct filename in the exception
1314 try:
1314 try:
1315 msg, (dummy_filename, lineno, offset, line) = value
1315 msg, (dummy_filename, lineno, offset, line) = value
1316 except:
1316 except:
1317 # Not the format we expect; leave it alone
1317 # Not the format we expect; leave it alone
1318 pass
1318 pass
1319 else:
1319 else:
1320 # Stuff in the right filename
1320 # Stuff in the right filename
1321 try:
1321 try:
1322 # Assume SyntaxError is a class exception
1322 # Assume SyntaxError is a class exception
1323 value = SyntaxError(msg, (filename, lineno, offset, line))
1323 value = SyntaxError(msg, (filename, lineno, offset, line))
1324 except:
1324 except:
1325 # If that failed, assume SyntaxError is a string
1325 # If that failed, assume SyntaxError is a string
1326 value = msg, (filename, lineno, offset, line)
1326 value = msg, (filename, lineno, offset, line)
1327 self.SyntaxTB(etype,value,[])
1327 self.SyntaxTB(etype,value,[])
1328
1328
1329 def edit_syntax_error(self):
1329 def edit_syntax_error(self):
1330 """The bottom half of the syntax error handler called in the main loop.
1330 """The bottom half of the syntax error handler called in the main loop.
1331
1331
1332 Loop until syntax error is fixed or user cancels.
1332 Loop until syntax error is fixed or user cancels.
1333 """
1333 """
1334
1334
1335 while self.SyntaxTB.last_syntax_error:
1335 while self.SyntaxTB.last_syntax_error:
1336 # copy and clear last_syntax_error
1336 # copy and clear last_syntax_error
1337 err = self.SyntaxTB.clear_err_state()
1337 err = self.SyntaxTB.clear_err_state()
1338 if not self._should_recompile(err):
1338 if not self._should_recompile(err):
1339 return
1339 return
1340 try:
1340 try:
1341 # may set last_syntax_error again if a SyntaxError is raised
1341 # may set last_syntax_error again if a SyntaxError is raised
1342 self.safe_execfile(err.filename,self.user_ns)
1342 self.safe_execfile(err.filename,self.user_ns)
1343 except:
1343 except:
1344 self.showtraceback()
1344 self.showtraceback()
1345 else:
1345 else:
1346 try:
1346 try:
1347 f = file(err.filename)
1347 f = file(err.filename)
1348 try:
1348 try:
1349 # This should be inside a display_trap block and I
1349 # This should be inside a display_trap block and I
1350 # think it is.
1350 # think it is.
1351 sys.displayhook(f.read())
1351 sys.displayhook(f.read())
1352 finally:
1352 finally:
1353 f.close()
1353 f.close()
1354 except:
1354 except:
1355 self.showtraceback()
1355 self.showtraceback()
1356
1356
1357 def _should_recompile(self,e):
1357 def _should_recompile(self,e):
1358 """Utility routine for edit_syntax_error"""
1358 """Utility routine for edit_syntax_error"""
1359
1359
1360 if e.filename in ('<ipython console>','<input>','<string>',
1360 if e.filename in ('<ipython console>','<input>','<string>',
1361 '<console>','<BackgroundJob compilation>',
1361 '<console>','<BackgroundJob compilation>',
1362 None):
1362 None):
1363
1363
1364 return False
1364 return False
1365 try:
1365 try:
1366 if (self.autoedit_syntax and
1366 if (self.autoedit_syntax and
1367 not self.ask_yes_no('Return to editor to correct syntax error? '
1367 not self.ask_yes_no('Return to editor to correct syntax error? '
1368 '[Y/n] ','y')):
1368 '[Y/n] ','y')):
1369 return False
1369 return False
1370 except EOFError:
1370 except EOFError:
1371 return False
1371 return False
1372
1372
1373 def int0(x):
1373 def int0(x):
1374 try:
1374 try:
1375 return int(x)
1375 return int(x)
1376 except TypeError:
1376 except TypeError:
1377 return 0
1377 return 0
1378 # always pass integer line and offset values to editor hook
1378 # always pass integer line and offset values to editor hook
1379 try:
1379 try:
1380 self.hooks.fix_error_editor(e.filename,
1380 self.hooks.fix_error_editor(e.filename,
1381 int0(e.lineno),int0(e.offset),e.msg)
1381 int0(e.lineno),int0(e.offset),e.msg)
1382 except TryNext:
1382 except TryNext:
1383 warn('Could not open editor')
1383 warn('Could not open editor')
1384 return False
1384 return False
1385 return True
1385 return True
1386
1386
1387 #-------------------------------------------------------------------------
1387 #-------------------------------------------------------------------------
1388 # Things related to tab completion
1388 # Things related to tab completion
1389 #-------------------------------------------------------------------------
1389 #-------------------------------------------------------------------------
1390
1390
1391 def complete(self, text):
1391 def complete(self, text):
1392 """Return a sorted list of all possible completions on text.
1392 """Return a sorted list of all possible completions on text.
1393
1393
1394 Inputs:
1394 Inputs:
1395
1395
1396 - text: a string of text to be completed on.
1396 - text: a string of text to be completed on.
1397
1397
1398 This is a wrapper around the completion mechanism, similar to what
1398 This is a wrapper around the completion mechanism, similar to what
1399 readline does at the command line when the TAB key is hit. By
1399 readline does at the command line when the TAB key is hit. By
1400 exposing it as a method, it can be used by other non-readline
1400 exposing it as a method, it can be used by other non-readline
1401 environments (such as GUIs) for text completion.
1401 environments (such as GUIs) for text completion.
1402
1402
1403 Simple usage example:
1403 Simple usage example:
1404
1404
1405 In [7]: x = 'hello'
1405 In [7]: x = 'hello'
1406
1406
1407 In [8]: x
1407 In [8]: x
1408 Out[8]: 'hello'
1408 Out[8]: 'hello'
1409
1409
1410 In [9]: print x
1410 In [9]: print x
1411 hello
1411 hello
1412
1412
1413 In [10]: _ip.complete('x.l')
1413 In [10]: _ip.complete('x.l')
1414 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1414 Out[10]: ['x.ljust', 'x.lower', 'x.lstrip']
1415 """
1415 """
1416
1416
1417 # Inject names into __builtin__ so we can complete on the added names.
1417 # Inject names into __builtin__ so we can complete on the added names.
1418 with self.builtin_trap:
1418 with self.builtin_trap:
1419 complete = self.Completer.complete
1419 complete = self.Completer.complete
1420 state = 0
1420 state = 0
1421 # use a dict so we get unique keys, since ipyhton's multiple
1421 # use a dict so we get unique keys, since ipyhton's multiple
1422 # completers can return duplicates. When we make 2.4 a requirement,
1422 # completers can return duplicates. When we make 2.4 a requirement,
1423 # start using sets instead, which are faster.
1423 # start using sets instead, which are faster.
1424 comps = {}
1424 comps = {}
1425 while True:
1425 while True:
1426 newcomp = complete(text,state,line_buffer=text)
1426 newcomp = complete(text,state,line_buffer=text)
1427 if newcomp is None:
1427 if newcomp is None:
1428 break
1428 break
1429 comps[newcomp] = 1
1429 comps[newcomp] = 1
1430 state += 1
1430 state += 1
1431 outcomps = comps.keys()
1431 outcomps = comps.keys()
1432 outcomps.sort()
1432 outcomps.sort()
1433 #print "T:",text,"OC:",outcomps # dbg
1433 #print "T:",text,"OC:",outcomps # dbg
1434 #print "vars:",self.user_ns.keys()
1434 #print "vars:",self.user_ns.keys()
1435 return outcomps
1435 return outcomps
1436
1436
1437 def set_custom_completer(self,completer,pos=0):
1437 def set_custom_completer(self,completer,pos=0):
1438 """Adds a new custom completer function.
1438 """Adds a new custom completer function.
1439
1439
1440 The position argument (defaults to 0) is the index in the completers
1440 The position argument (defaults to 0) is the index in the completers
1441 list where you want the completer to be inserted."""
1441 list where you want the completer to be inserted."""
1442
1442
1443 newcomp = new.instancemethod(completer,self.Completer,
1443 newcomp = new.instancemethod(completer,self.Completer,
1444 self.Completer.__class__)
1444 self.Completer.__class__)
1445 self.Completer.matchers.insert(pos,newcomp)
1445 self.Completer.matchers.insert(pos,newcomp)
1446
1446
1447 def set_completer(self):
1447 def set_completer(self):
1448 """Reset readline's completer to be our own."""
1448 """Reset readline's completer to be our own."""
1449 self.readline.set_completer(self.Completer.complete)
1449 self.readline.set_completer(self.Completer.complete)
1450
1450
1451 def set_completer_frame(self, frame=None):
1451 def set_completer_frame(self, frame=None):
1452 """Set the frame of the completer."""
1452 """Set the frame of the completer."""
1453 if frame:
1453 if frame:
1454 self.Completer.namespace = frame.f_locals
1454 self.Completer.namespace = frame.f_locals
1455 self.Completer.global_namespace = frame.f_globals
1455 self.Completer.global_namespace = frame.f_globals
1456 else:
1456 else:
1457 self.Completer.namespace = self.user_ns
1457 self.Completer.namespace = self.user_ns
1458 self.Completer.global_namespace = self.user_global_ns
1458 self.Completer.global_namespace = self.user_global_ns
1459
1459
1460 #-------------------------------------------------------------------------
1460 #-------------------------------------------------------------------------
1461 # Things related to readline
1461 # Things related to readline
1462 #-------------------------------------------------------------------------
1462 #-------------------------------------------------------------------------
1463
1463
1464 def init_readline(self):
1464 def init_readline(self):
1465 """Command history completion/saving/reloading."""
1465 """Command history completion/saving/reloading."""
1466
1466
1467 self.rl_next_input = None
1467 self.rl_next_input = None
1468 self.rl_do_indent = False
1468 self.rl_do_indent = False
1469
1469
1470 if not self.readline_use:
1470 if not self.readline_use:
1471 return
1471 return
1472
1472
1473 import IPython.utils.rlineimpl as readline
1473 import IPython.utils.rlineimpl as readline
1474
1474
1475 if not readline.have_readline:
1475 if not readline.have_readline:
1476 self.has_readline = 0
1476 self.has_readline = 0
1477 self.readline = None
1477 self.readline = None
1478 # no point in bugging windows users with this every time:
1478 # no point in bugging windows users with this every time:
1479 warn('Readline services not available on this platform.')
1479 warn('Readline services not available on this platform.')
1480 else:
1480 else:
1481 sys.modules['readline'] = readline
1481 sys.modules['readline'] = readline
1482 import atexit
1482 import atexit
1483 from IPython.core.completer import IPCompleter
1483 from IPython.core.completer import IPCompleter
1484 self.Completer = IPCompleter(self,
1484 self.Completer = IPCompleter(self,
1485 self.user_ns,
1485 self.user_ns,
1486 self.user_global_ns,
1486 self.user_global_ns,
1487 self.readline_omit__names,
1487 self.readline_omit__names,
1488 self.alias_manager.alias_table)
1488 self.alias_manager.alias_table)
1489 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1489 sdisp = self.strdispatchers.get('complete_command', StrDispatch())
1490 self.strdispatchers['complete_command'] = sdisp
1490 self.strdispatchers['complete_command'] = sdisp
1491 self.Completer.custom_completers = sdisp
1491 self.Completer.custom_completers = sdisp
1492 # Platform-specific configuration
1492 # Platform-specific configuration
1493 if os.name == 'nt':
1493 if os.name == 'nt':
1494 self.readline_startup_hook = readline.set_pre_input_hook
1494 self.readline_startup_hook = readline.set_pre_input_hook
1495 else:
1495 else:
1496 self.readline_startup_hook = readline.set_startup_hook
1496 self.readline_startup_hook = readline.set_startup_hook
1497
1497
1498 # Load user's initrc file (readline config)
1498 # Load user's initrc file (readline config)
1499 # Or if libedit is used, load editrc.
1499 # Or if libedit is used, load editrc.
1500 inputrc_name = os.environ.get('INPUTRC')
1500 inputrc_name = os.environ.get('INPUTRC')
1501 if inputrc_name is None:
1501 if inputrc_name is None:
1502 home_dir = get_home_dir()
1502 home_dir = get_home_dir()
1503 if home_dir is not None:
1503 if home_dir is not None:
1504 inputrc_name = '.inputrc'
1504 inputrc_name = '.inputrc'
1505 if readline.uses_libedit:
1505 if readline.uses_libedit:
1506 inputrc_name = '.editrc'
1506 inputrc_name = '.editrc'
1507 inputrc_name = os.path.join(home_dir, inputrc_name)
1507 inputrc_name = os.path.join(home_dir, inputrc_name)
1508 if os.path.isfile(inputrc_name):
1508 if os.path.isfile(inputrc_name):
1509 try:
1509 try:
1510 readline.read_init_file(inputrc_name)
1510 readline.read_init_file(inputrc_name)
1511 except:
1511 except:
1512 warn('Problems reading readline initialization file <%s>'
1512 warn('Problems reading readline initialization file <%s>'
1513 % inputrc_name)
1513 % inputrc_name)
1514
1514
1515 self.has_readline = 1
1515 self.has_readline = 1
1516 self.readline = readline
1516 self.readline = readline
1517 # save this in sys so embedded copies can restore it properly
1517 # save this in sys so embedded copies can restore it properly
1518 sys.ipcompleter = self.Completer.complete
1518 sys.ipcompleter = self.Completer.complete
1519 self.set_completer()
1519 self.set_completer()
1520
1520
1521 # Configure readline according to user's prefs
1521 # Configure readline according to user's prefs
1522 # This is only done if GNU readline is being used. If libedit
1522 # This is only done if GNU readline is being used. If libedit
1523 # is being used (as on Leopard) the readline config is
1523 # is being used (as on Leopard) the readline config is
1524 # not run as the syntax for libedit is different.
1524 # not run as the syntax for libedit is different.
1525 if not readline.uses_libedit:
1525 if not readline.uses_libedit:
1526 for rlcommand in self.readline_parse_and_bind:
1526 for rlcommand in self.readline_parse_and_bind:
1527 #print "loading rl:",rlcommand # dbg
1527 #print "loading rl:",rlcommand # dbg
1528 readline.parse_and_bind(rlcommand)
1528 readline.parse_and_bind(rlcommand)
1529
1529
1530 # Remove some chars from the delimiters list. If we encounter
1530 # Remove some chars from the delimiters list. If we encounter
1531 # unicode chars, discard them.
1531 # unicode chars, discard them.
1532 delims = readline.get_completer_delims().encode("ascii", "ignore")
1532 delims = readline.get_completer_delims().encode("ascii", "ignore")
1533 delims = delims.translate(string._idmap,
1533 delims = delims.translate(string._idmap,
1534 self.readline_remove_delims)
1534 self.readline_remove_delims)
1535 readline.set_completer_delims(delims)
1535 readline.set_completer_delims(delims)
1536 # otherwise we end up with a monster history after a while:
1536 # otherwise we end up with a monster history after a while:
1537 readline.set_history_length(1000)
1537 readline.set_history_length(1000)
1538 try:
1538 try:
1539 #print '*** Reading readline history' # dbg
1539 #print '*** Reading readline history' # dbg
1540 readline.read_history_file(self.histfile)
1540 readline.read_history_file(self.histfile)
1541 except IOError:
1541 except IOError:
1542 pass # It doesn't exist yet.
1542 pass # It doesn't exist yet.
1543
1543
1544 atexit.register(self.atexit_operations)
1544 atexit.register(self.atexit_operations)
1545 del atexit
1545 del atexit
1546
1546
1547 # Configure auto-indent for all platforms
1547 # Configure auto-indent for all platforms
1548 self.set_autoindent(self.autoindent)
1548 self.set_autoindent(self.autoindent)
1549
1549
1550 def set_next_input(self, s):
1550 def set_next_input(self, s):
1551 """ Sets the 'default' input string for the next command line.
1551 """ Sets the 'default' input string for the next command line.
1552
1552
1553 Requires readline.
1553 Requires readline.
1554
1554
1555 Example:
1555 Example:
1556
1556
1557 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1557 [D:\ipython]|1> _ip.set_next_input("Hello Word")
1558 [D:\ipython]|2> Hello Word_ # cursor is here
1558 [D:\ipython]|2> Hello Word_ # cursor is here
1559 """
1559 """
1560
1560
1561 self.rl_next_input = s
1561 self.rl_next_input = s
1562
1562
1563 def pre_readline(self):
1563 def pre_readline(self):
1564 """readline hook to be used at the start of each line.
1564 """readline hook to be used at the start of each line.
1565
1565
1566 Currently it handles auto-indent only."""
1566 Currently it handles auto-indent only."""
1567
1567
1568 #debugx('self.indent_current_nsp','pre_readline:')
1568 #debugx('self.indent_current_nsp','pre_readline:')
1569
1569
1570 if self.rl_do_indent:
1570 if self.rl_do_indent:
1571 self.readline.insert_text(self._indent_current_str())
1571 self.readline.insert_text(self._indent_current_str())
1572 if self.rl_next_input is not None:
1572 if self.rl_next_input is not None:
1573 self.readline.insert_text(self.rl_next_input)
1573 self.readline.insert_text(self.rl_next_input)
1574 self.rl_next_input = None
1574 self.rl_next_input = None
1575
1575
1576 def _indent_current_str(self):
1576 def _indent_current_str(self):
1577 """return the current level of indentation as a string"""
1577 """return the current level of indentation as a string"""
1578 return self.indent_current_nsp * ' '
1578 return self.indent_current_nsp * ' '
1579
1579
1580 #-------------------------------------------------------------------------
1580 #-------------------------------------------------------------------------
1581 # Things related to magics
1581 # Things related to magics
1582 #-------------------------------------------------------------------------
1582 #-------------------------------------------------------------------------
1583
1583
1584 def init_magics(self):
1584 def init_magics(self):
1585 # Set user colors (don't do it in the constructor above so that it
1585 # Set user colors (don't do it in the constructor above so that it
1586 # doesn't crash if colors option is invalid)
1586 # doesn't crash if colors option is invalid)
1587 self.magic_colors(self.colors)
1587 self.magic_colors(self.colors)
1588
1588
1589 def magic(self,arg_s):
1589 def magic(self,arg_s):
1590 """Call a magic function by name.
1590 """Call a magic function by name.
1591
1591
1592 Input: a string containing the name of the magic function to call and any
1592 Input: a string containing the name of the magic function to call and any
1593 additional arguments to be passed to the magic.
1593 additional arguments to be passed to the magic.
1594
1594
1595 magic('name -opt foo bar') is equivalent to typing at the ipython
1595 magic('name -opt foo bar') is equivalent to typing at the ipython
1596 prompt:
1596 prompt:
1597
1597
1598 In[1]: %name -opt foo bar
1598 In[1]: %name -opt foo bar
1599
1599
1600 To call a magic without arguments, simply use magic('name').
1600 To call a magic without arguments, simply use magic('name').
1601
1601
1602 This provides a proper Python function to call IPython's magics in any
1602 This provides a proper Python function to call IPython's magics in any
1603 valid Python code you can type at the interpreter, including loops and
1603 valid Python code you can type at the interpreter, including loops and
1604 compound statements.
1604 compound statements.
1605 """
1605 """
1606
1606
1607 args = arg_s.split(' ',1)
1607 args = arg_s.split(' ',1)
1608 magic_name = args[0]
1608 magic_name = args[0]
1609 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1609 magic_name = magic_name.lstrip(prefilter.ESC_MAGIC)
1610
1610
1611 try:
1611 try:
1612 magic_args = args[1]
1612 magic_args = args[1]
1613 except IndexError:
1613 except IndexError:
1614 magic_args = ''
1614 magic_args = ''
1615 fn = getattr(self,'magic_'+magic_name,None)
1615 fn = getattr(self,'magic_'+magic_name,None)
1616 if fn is None:
1616 if fn is None:
1617 error("Magic function `%s` not found." % magic_name)
1617 error("Magic function `%s` not found." % magic_name)
1618 else:
1618 else:
1619 magic_args = self.var_expand(magic_args,1)
1619 magic_args = self.var_expand(magic_args,1)
1620 with nested(self.builtin_trap,):
1620 with nested(self.builtin_trap,):
1621 result = fn(magic_args)
1621 result = fn(magic_args)
1622 return result
1622 return result
1623
1623
1624 def define_magic(self, magicname, func):
1624 def define_magic(self, magicname, func):
1625 """Expose own function as magic function for ipython
1625 """Expose own function as magic function for ipython
1626
1626
1627 def foo_impl(self,parameter_s=''):
1627 def foo_impl(self,parameter_s=''):
1628 'My very own magic!. (Use docstrings, IPython reads them).'
1628 'My very own magic!. (Use docstrings, IPython reads them).'
1629 print 'Magic function. Passed parameter is between < >:'
1629 print 'Magic function. Passed parameter is between < >:'
1630 print '<%s>' % parameter_s
1630 print '<%s>' % parameter_s
1631 print 'The self object is:',self
1631 print 'The self object is:',self
1632
1632
1633 self.define_magic('foo',foo_impl)
1633 self.define_magic('foo',foo_impl)
1634 """
1634 """
1635
1635
1636 import new
1636 import new
1637 im = new.instancemethod(func,self, self.__class__)
1637 im = new.instancemethod(func,self, self.__class__)
1638 old = getattr(self, "magic_" + magicname, None)
1638 old = getattr(self, "magic_" + magicname, None)
1639 setattr(self, "magic_" + magicname, im)
1639 setattr(self, "magic_" + magicname, im)
1640 return old
1640 return old
1641
1641
1642 #-------------------------------------------------------------------------
1642 #-------------------------------------------------------------------------
1643 # Things related to macros
1643 # Things related to macros
1644 #-------------------------------------------------------------------------
1644 #-------------------------------------------------------------------------
1645
1645
1646 def define_macro(self, name, themacro):
1646 def define_macro(self, name, themacro):
1647 """Define a new macro
1647 """Define a new macro
1648
1648
1649 Parameters
1649 Parameters
1650 ----------
1650 ----------
1651 name : str
1651 name : str
1652 The name of the macro.
1652 The name of the macro.
1653 themacro : str or Macro
1653 themacro : str or Macro
1654 The action to do upon invoking the macro. If a string, a new
1654 The action to do upon invoking the macro. If a string, a new
1655 Macro object is created by passing the string to it.
1655 Macro object is created by passing the string to it.
1656 """
1656 """
1657
1657
1658 from IPython.core import macro
1658 from IPython.core import macro
1659
1659
1660 if isinstance(themacro, basestring):
1660 if isinstance(themacro, basestring):
1661 themacro = macro.Macro(themacro)
1661 themacro = macro.Macro(themacro)
1662 if not isinstance(themacro, macro.Macro):
1662 if not isinstance(themacro, macro.Macro):
1663 raise ValueError('A macro must be a string or a Macro instance.')
1663 raise ValueError('A macro must be a string or a Macro instance.')
1664 self.user_ns[name] = themacro
1664 self.user_ns[name] = themacro
1665
1665
1666 #-------------------------------------------------------------------------
1666 #-------------------------------------------------------------------------
1667 # Things related to the running of system commands
1667 # Things related to the running of system commands
1668 #-------------------------------------------------------------------------
1668 #-------------------------------------------------------------------------
1669
1669
1670 def system(self, cmd):
1670 def system(self, cmd):
1671 """Make a system call, using IPython."""
1671 """Make a system call, using IPython."""
1672 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1672 return self.hooks.shell_hook(self.var_expand(cmd, depth=2))
1673
1673
1674 #-------------------------------------------------------------------------
1674 #-------------------------------------------------------------------------
1675 # Things related to aliases
1675 # Things related to aliases
1676 #-------------------------------------------------------------------------
1676 #-------------------------------------------------------------------------
1677
1677
1678 def init_alias(self):
1678 def init_alias(self):
1679 self.alias_manager = AliasManager(self, config=self.config)
1679 self.alias_manager = AliasManager(self, config=self.config)
1680 self.ns_table['alias'] = self.alias_manager.alias_table,
1680 self.ns_table['alias'] = self.alias_manager.alias_table,
1681
1681
1682 #-------------------------------------------------------------------------
1682 #-------------------------------------------------------------------------
1683 # Things related to the running of code
1683 # Things related to the running of code
1684 #-------------------------------------------------------------------------
1684 #-------------------------------------------------------------------------
1685
1685
1686 def ex(self, cmd):
1686 def ex(self, cmd):
1687 """Execute a normal python statement in user namespace."""
1687 """Execute a normal python statement in user namespace."""
1688 with nested(self.builtin_trap,):
1688 with nested(self.builtin_trap,):
1689 exec cmd in self.user_global_ns, self.user_ns
1689 exec cmd in self.user_global_ns, self.user_ns
1690
1690
1691 def ev(self, expr):
1691 def ev(self, expr):
1692 """Evaluate python expression expr in user namespace.
1692 """Evaluate python expression expr in user namespace.
1693
1693
1694 Returns the result of evaluation
1694 Returns the result of evaluation
1695 """
1695 """
1696 with nested(self.builtin_trap,):
1696 with nested(self.builtin_trap,):
1697 return eval(expr, self.user_global_ns, self.user_ns)
1697 return eval(expr, self.user_global_ns, self.user_ns)
1698
1698
1699 def mainloop(self, display_banner=None):
1699 def mainloop(self, display_banner=None):
1700 """Start the mainloop.
1700 """Start the mainloop.
1701
1701
1702 If an optional banner argument is given, it will override the
1702 If an optional banner argument is given, it will override the
1703 internally created default banner.
1703 internally created default banner.
1704 """
1704 """
1705
1705
1706 with nested(self.builtin_trap, self.display_trap):
1706 with nested(self.builtin_trap, self.display_trap):
1707
1707
1708 # if you run stuff with -c <cmd>, raw hist is not updated
1708 # if you run stuff with -c <cmd>, raw hist is not updated
1709 # ensure that it's in sync
1709 # ensure that it's in sync
1710 if len(self.input_hist) != len (self.input_hist_raw):
1710 if len(self.input_hist) != len (self.input_hist_raw):
1711 self.input_hist_raw = InputList(self.input_hist)
1711 self.input_hist_raw = InputList(self.input_hist)
1712
1712
1713 while 1:
1713 while 1:
1714 try:
1714 try:
1715 self.interact(display_banner=display_banner)
1715 self.interact(display_banner=display_banner)
1716 #self.interact_with_readline()
1716 #self.interact_with_readline()
1717 # XXX for testing of a readline-decoupled repl loop, call
1717 # XXX for testing of a readline-decoupled repl loop, call
1718 # interact_with_readline above
1718 # interact_with_readline above
1719 break
1719 break
1720 except KeyboardInterrupt:
1720 except KeyboardInterrupt:
1721 # this should not be necessary, but KeyboardInterrupt
1721 # this should not be necessary, but KeyboardInterrupt
1722 # handling seems rather unpredictable...
1722 # handling seems rather unpredictable...
1723 self.write("\nKeyboardInterrupt in interact()\n")
1723 self.write("\nKeyboardInterrupt in interact()\n")
1724
1724
1725 def interact_prompt(self):
1725 def interact_prompt(self):
1726 """ Print the prompt (in read-eval-print loop)
1726 """ Print the prompt (in read-eval-print loop)
1727
1727
1728 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1728 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1729 used in standard IPython flow.
1729 used in standard IPython flow.
1730 """
1730 """
1731 if self.more:
1731 if self.more:
1732 try:
1732 try:
1733 prompt = self.hooks.generate_prompt(True)
1733 prompt = self.hooks.generate_prompt(True)
1734 except:
1734 except:
1735 self.showtraceback()
1735 self.showtraceback()
1736 if self.autoindent:
1736 if self.autoindent:
1737 self.rl_do_indent = True
1737 self.rl_do_indent = True
1738
1738
1739 else:
1739 else:
1740 try:
1740 try:
1741 prompt = self.hooks.generate_prompt(False)
1741 prompt = self.hooks.generate_prompt(False)
1742 except:
1742 except:
1743 self.showtraceback()
1743 self.showtraceback()
1744 self.write(prompt)
1744 self.write(prompt)
1745
1745
1746 def interact_handle_input(self,line):
1746 def interact_handle_input(self,line):
1747 """ Handle the input line (in read-eval-print loop)
1747 """ Handle the input line (in read-eval-print loop)
1748
1748
1749 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1749 Provided for those who want to implement their own read-eval-print loop (e.g. GUIs), not
1750 used in standard IPython flow.
1750 used in standard IPython flow.
1751 """
1751 """
1752 if line.lstrip() == line:
1752 if line.lstrip() == line:
1753 self.shadowhist.add(line.strip())
1753 self.shadowhist.add(line.strip())
1754 lineout = self.prefilter_manager.prefilter_lines(line,self.more)
1754 lineout = self.prefilter_manager.prefilter_lines(line,self.more)
1755
1755
1756 if line.strip():
1756 if line.strip():
1757 if self.more:
1757 if self.more:
1758 self.input_hist_raw[-1] += '%s\n' % line
1758 self.input_hist_raw[-1] += '%s\n' % line
1759 else:
1759 else:
1760 self.input_hist_raw.append('%s\n' % line)
1760 self.input_hist_raw.append('%s\n' % line)
1761
1761
1762
1762
1763 self.more = self.push_line(lineout)
1763 self.more = self.push_line(lineout)
1764 if (self.SyntaxTB.last_syntax_error and
1764 if (self.SyntaxTB.last_syntax_error and
1765 self.autoedit_syntax):
1765 self.autoedit_syntax):
1766 self.edit_syntax_error()
1766 self.edit_syntax_error()
1767
1767
1768 def interact_with_readline(self):
1768 def interact_with_readline(self):
1769 """ Demo of using interact_handle_input, interact_prompt
1769 """ Demo of using interact_handle_input, interact_prompt
1770
1770
1771 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1771 This is the main read-eval-print loop. If you need to implement your own (e.g. for GUI),
1772 it should work like this.
1772 it should work like this.
1773 """
1773 """
1774 self.readline_startup_hook(self.pre_readline)
1774 self.readline_startup_hook(self.pre_readline)
1775 while not self.exit_now:
1775 while not self.exit_now:
1776 self.interact_prompt()
1776 self.interact_prompt()
1777 if self.more:
1777 if self.more:
1778 self.rl_do_indent = True
1778 self.rl_do_indent = True
1779 else:
1779 else:
1780 self.rl_do_indent = False
1780 self.rl_do_indent = False
1781 line = raw_input_original().decode(self.stdin_encoding)
1781 line = raw_input_original().decode(self.stdin_encoding)
1782 self.interact_handle_input(line)
1782 self.interact_handle_input(line)
1783
1783
1784 def interact(self, display_banner=None):
1784 def interact(self, display_banner=None):
1785 """Closely emulate the interactive Python console."""
1785 """Closely emulate the interactive Python console."""
1786
1786
1787 # batch run -> do not interact
1787 # batch run -> do not interact
1788 if self.exit_now:
1788 if self.exit_now:
1789 return
1789 return
1790
1790
1791 if display_banner is None:
1791 if display_banner is None:
1792 display_banner = self.display_banner
1792 display_banner = self.display_banner
1793 if display_banner:
1793 if display_banner:
1794 self.show_banner()
1794 self.show_banner()
1795
1795
1796 more = 0
1796 more = 0
1797
1797
1798 # Mark activity in the builtins
1798 # Mark activity in the builtins
1799 __builtin__.__dict__['__IPYTHON__active'] += 1
1799 __builtin__.__dict__['__IPYTHON__active'] += 1
1800
1800
1801 if self.has_readline:
1801 if self.has_readline:
1802 self.readline_startup_hook(self.pre_readline)
1802 self.readline_startup_hook(self.pre_readline)
1803 # exit_now is set by a call to %Exit or %Quit, through the
1803 # exit_now is set by a call to %Exit or %Quit, through the
1804 # ask_exit callback.
1804 # ask_exit callback.
1805
1805
1806 while not self.exit_now:
1806 while not self.exit_now:
1807 self.hooks.pre_prompt_hook()
1807 self.hooks.pre_prompt_hook()
1808 if more:
1808 if more:
1809 try:
1809 try:
1810 prompt = self.hooks.generate_prompt(True)
1810 prompt = self.hooks.generate_prompt(True)
1811 except:
1811 except:
1812 self.showtraceback()
1812 self.showtraceback()
1813 if self.autoindent:
1813 if self.autoindent:
1814 self.rl_do_indent = True
1814 self.rl_do_indent = True
1815
1815
1816 else:
1816 else:
1817 try:
1817 try:
1818 prompt = self.hooks.generate_prompt(False)
1818 prompt = self.hooks.generate_prompt(False)
1819 except:
1819 except:
1820 self.showtraceback()
1820 self.showtraceback()
1821 try:
1821 try:
1822 line = self.raw_input(prompt, more)
1822 line = self.raw_input(prompt, more)
1823 if self.exit_now:
1823 if self.exit_now:
1824 # quick exit on sys.std[in|out] close
1824 # quick exit on sys.std[in|out] close
1825 break
1825 break
1826 if self.autoindent:
1826 if self.autoindent:
1827 self.rl_do_indent = False
1827 self.rl_do_indent = False
1828
1828
1829 except KeyboardInterrupt:
1829 except KeyboardInterrupt:
1830 #double-guard against keyboardinterrupts during kbdint handling
1830 #double-guard against keyboardinterrupts during kbdint handling
1831 try:
1831 try:
1832 self.write('\nKeyboardInterrupt\n')
1832 self.write('\nKeyboardInterrupt\n')
1833 self.resetbuffer()
1833 self.resetbuffer()
1834 # keep cache in sync with the prompt counter:
1834 # keep cache in sync with the prompt counter:
1835 self.outputcache.prompt_count -= 1
1835 self.outputcache.prompt_count -= 1
1836
1836
1837 if self.autoindent:
1837 if self.autoindent:
1838 self.indent_current_nsp = 0
1838 self.indent_current_nsp = 0
1839 more = 0
1839 more = 0
1840 except KeyboardInterrupt:
1840 except KeyboardInterrupt:
1841 pass
1841 pass
1842 except EOFError:
1842 except EOFError:
1843 if self.autoindent:
1843 if self.autoindent:
1844 self.rl_do_indent = False
1844 self.rl_do_indent = False
1845 self.readline_startup_hook(None)
1845 self.readline_startup_hook(None)
1846 self.write('\n')
1846 self.write('\n')
1847 self.exit()
1847 self.exit()
1848 except bdb.BdbQuit:
1848 except bdb.BdbQuit:
1849 warn('The Python debugger has exited with a BdbQuit exception.\n'
1849 warn('The Python debugger has exited with a BdbQuit exception.\n'
1850 'Because of how pdb handles the stack, it is impossible\n'
1850 'Because of how pdb handles the stack, it is impossible\n'
1851 'for IPython to properly format this particular exception.\n'
1851 'for IPython to properly format this particular exception.\n'
1852 'IPython will resume normal operation.')
1852 'IPython will resume normal operation.')
1853 except:
1853 except:
1854 # exceptions here are VERY RARE, but they can be triggered
1854 # exceptions here are VERY RARE, but they can be triggered
1855 # asynchronously by signal handlers, for example.
1855 # asynchronously by signal handlers, for example.
1856 self.showtraceback()
1856 self.showtraceback()
1857 else:
1857 else:
1858 more = self.push_line(line)
1858 more = self.push_line(line)
1859 if (self.SyntaxTB.last_syntax_error and
1859 if (self.SyntaxTB.last_syntax_error and
1860 self.autoedit_syntax):
1860 self.autoedit_syntax):
1861 self.edit_syntax_error()
1861 self.edit_syntax_error()
1862
1862
1863 # We are off again...
1863 # We are off again...
1864 __builtin__.__dict__['__IPYTHON__active'] -= 1
1864 __builtin__.__dict__['__IPYTHON__active'] -= 1
1865
1865
1866 def safe_execfile(self, fname, *where, **kw):
1866 def safe_execfile(self, fname, *where, **kw):
1867 """A safe version of the builtin execfile().
1867 """A safe version of the builtin execfile().
1868
1868
1869 This version will never throw an exception, but instead print
1869 This version will never throw an exception, but instead print
1870 helpful error messages to the screen. This only works on pure
1870 helpful error messages to the screen. This only works on pure
1871 Python files with the .py extension.
1871 Python files with the .py extension.
1872
1872
1873 Parameters
1873 Parameters
1874 ----------
1874 ----------
1875 fname : string
1875 fname : string
1876 The name of the file to be executed.
1876 The name of the file to be executed.
1877 where : tuple
1877 where : tuple
1878 One or two namespaces, passed to execfile() as (globals,locals).
1878 One or two namespaces, passed to execfile() as (globals,locals).
1879 If only one is given, it is passed as both.
1879 If only one is given, it is passed as both.
1880 exit_ignore : bool (False)
1880 exit_ignore : bool (False)
1881 If True, then don't print errors for non-zero exit statuses.
1881 If True, then don't print errors for non-zero exit statuses.
1882 """
1882 """
1883 kw.setdefault('exit_ignore', False)
1883 kw.setdefault('exit_ignore', False)
1884
1884
1885 fname = os.path.abspath(os.path.expanduser(fname))
1885 fname = os.path.abspath(os.path.expanduser(fname))
1886
1886
1887 # Make sure we have a .py file
1887 # Make sure we have a .py file
1888 if not fname.endswith('.py'):
1888 if not fname.endswith('.py'):
1889 warn('File must end with .py to be run using execfile: <%s>' % fname)
1889 warn('File must end with .py to be run using execfile: <%s>' % fname)
1890
1890
1891 # Make sure we can open the file
1891 # Make sure we can open the file
1892 try:
1892 try:
1893 with open(fname) as thefile:
1893 with open(fname) as thefile:
1894 pass
1894 pass
1895 except:
1895 except:
1896 warn('Could not open file <%s> for safe execution.' % fname)
1896 warn('Could not open file <%s> for safe execution.' % fname)
1897 return
1897 return
1898
1898
1899 # Find things also in current directory. This is needed to mimic the
1899 # Find things also in current directory. This is needed to mimic the
1900 # behavior of running a script from the system command line, where
1900 # behavior of running a script from the system command line, where
1901 # Python inserts the script's directory into sys.path
1901 # Python inserts the script's directory into sys.path
1902 dname = os.path.dirname(fname)
1902 dname = os.path.dirname(fname)
1903
1903
1904 with prepended_to_syspath(dname):
1904 with prepended_to_syspath(dname):
1905 try:
1905 try:
1906 if sys.platform == 'win32' and sys.version_info < (2,5,1):
1906 if sys.platform == 'win32' and sys.version_info < (2,5,1):
1907 # Work around a bug in Python for Windows. The bug was
1907 # Work around a bug in Python for Windows. The bug was
1908 # fixed in in Python 2.5 r54159 and 54158, but that's still
1908 # fixed in in Python 2.5 r54159 and 54158, but that's still
1909 # SVN Python as of March/07. For details, see:
1909 # SVN Python as of March/07. For details, see:
1910 # http://projects.scipy.org/ipython/ipython/ticket/123
1910 # http://projects.scipy.org/ipython/ipython/ticket/123
1911 try:
1911 try:
1912 globs,locs = where[0:2]
1912 globs,locs = where[0:2]
1913 except:
1913 except:
1914 try:
1914 try:
1915 globs = locs = where[0]
1915 globs = locs = where[0]
1916 except:
1916 except:
1917 globs = locs = globals()
1917 globs = locs = globals()
1918 exec file(fname) in globs,locs
1918 exec file(fname) in globs,locs
1919 else:
1919 else:
1920 execfile(fname,*where)
1920 execfile(fname,*where)
1921 except SyntaxError:
1921 except SyntaxError:
1922 self.showsyntaxerror()
1922 self.showsyntaxerror()
1923 warn('Failure executing file: <%s>' % fname)
1923 warn('Failure executing file: <%s>' % fname)
1924 except SystemExit, status:
1924 except SystemExit, status:
1925 # Code that correctly sets the exit status flag to success (0)
1925 # Code that correctly sets the exit status flag to success (0)
1926 # shouldn't be bothered with a traceback. Note that a plain
1926 # shouldn't be bothered with a traceback. Note that a plain
1927 # sys.exit() does NOT set the message to 0 (it's empty) so that
1927 # sys.exit() does NOT set the message to 0 (it's empty) so that
1928 # will still get a traceback. Note that the structure of the
1928 # will still get a traceback. Note that the structure of the
1929 # SystemExit exception changed between Python 2.4 and 2.5, so
1929 # SystemExit exception changed between Python 2.4 and 2.5, so
1930 # the checks must be done in a version-dependent way.
1930 # the checks must be done in a version-dependent way.
1931 show = False
1931 show = False
1932 if status.args[0]==0 and not kw['exit_ignore']:
1932 if status.args[0]==0 and not kw['exit_ignore']:
1933 show = True
1933 show = True
1934 if show:
1934 if show:
1935 self.showtraceback()
1935 self.showtraceback()
1936 warn('Failure executing file: <%s>' % fname)
1936 warn('Failure executing file: <%s>' % fname)
1937 except:
1937 except:
1938 self.showtraceback()
1938 self.showtraceback()
1939 warn('Failure executing file: <%s>' % fname)
1939 warn('Failure executing file: <%s>' % fname)
1940
1940
1941 def safe_execfile_ipy(self, fname):
1941 def safe_execfile_ipy(self, fname):
1942 """Like safe_execfile, but for .ipy files with IPython syntax.
1942 """Like safe_execfile, but for .ipy files with IPython syntax.
1943
1943
1944 Parameters
1944 Parameters
1945 ----------
1945 ----------
1946 fname : str
1946 fname : str
1947 The name of the file to execute. The filename must have a
1947 The name of the file to execute. The filename must have a
1948 .ipy extension.
1948 .ipy extension.
1949 """
1949 """
1950 fname = os.path.abspath(os.path.expanduser(fname))
1950 fname = os.path.abspath(os.path.expanduser(fname))
1951
1951
1952 # Make sure we have a .py file
1952 # Make sure we have a .py file
1953 if not fname.endswith('.ipy'):
1953 if not fname.endswith('.ipy'):
1954 warn('File must end with .py to be run using execfile: <%s>' % fname)
1954 warn('File must end with .py to be run using execfile: <%s>' % fname)
1955
1955
1956 # Make sure we can open the file
1956 # Make sure we can open the file
1957 try:
1957 try:
1958 with open(fname) as thefile:
1958 with open(fname) as thefile:
1959 pass
1959 pass
1960 except:
1960 except:
1961 warn('Could not open file <%s> for safe execution.' % fname)
1961 warn('Could not open file <%s> for safe execution.' % fname)
1962 return
1962 return
1963
1963
1964 # Find things also in current directory. This is needed to mimic the
1964 # Find things also in current directory. This is needed to mimic the
1965 # behavior of running a script from the system command line, where
1965 # behavior of running a script from the system command line, where
1966 # Python inserts the script's directory into sys.path
1966 # Python inserts the script's directory into sys.path
1967 dname = os.path.dirname(fname)
1967 dname = os.path.dirname(fname)
1968
1968
1969 with prepended_to_syspath(dname):
1969 with prepended_to_syspath(dname):
1970 try:
1970 try:
1971 with open(fname) as thefile:
1971 with open(fname) as thefile:
1972 script = thefile.read()
1972 script = thefile.read()
1973 # self.runlines currently captures all exceptions
1973 # self.runlines currently captures all exceptions
1974 # raise in user code. It would be nice if there were
1974 # raise in user code. It would be nice if there were
1975 # versions of runlines, execfile that did raise, so
1975 # versions of runlines, execfile that did raise, so
1976 # we could catch the errors.
1976 # we could catch the errors.
1977 self.runlines(script, clean=True)
1977 self.runlines(script, clean=True)
1978 except:
1978 except:
1979 self.showtraceback()
1979 self.showtraceback()
1980 warn('Unknown failure executing file: <%s>' % fname)
1980 warn('Unknown failure executing file: <%s>' % fname)
1981
1981
1982 def _is_secondary_block_start(self, s):
1982 def _is_secondary_block_start(self, s):
1983 if not s.endswith(':'):
1983 if not s.endswith(':'):
1984 return False
1984 return False
1985 if (s.startswith('elif') or
1985 if (s.startswith('elif') or
1986 s.startswith('else') or
1986 s.startswith('else') or
1987 s.startswith('except') or
1987 s.startswith('except') or
1988 s.startswith('finally')):
1988 s.startswith('finally')):
1989 return True
1989 return True
1990
1990
1991 def cleanup_ipy_script(self, script):
1991 def cleanup_ipy_script(self, script):
1992 """Make a script safe for self.runlines()
1992 """Make a script safe for self.runlines()
1993
1993
1994 Currently, IPython is lines based, with blocks being detected by
1994 Currently, IPython is lines based, with blocks being detected by
1995 empty lines. This is a problem for block based scripts that may
1995 empty lines. This is a problem for block based scripts that may
1996 not have empty lines after blocks. This script adds those empty
1996 not have empty lines after blocks. This script adds those empty
1997 lines to make scripts safe for running in the current line based
1997 lines to make scripts safe for running in the current line based
1998 IPython.
1998 IPython.
1999 """
1999 """
2000 res = []
2000 res = []
2001 lines = script.splitlines()
2001 lines = script.splitlines()
2002 level = 0
2002 level = 0
2003
2003
2004 for l in lines:
2004 for l in lines:
2005 lstripped = l.lstrip()
2005 lstripped = l.lstrip()
2006 stripped = l.strip()
2006 stripped = l.strip()
2007 if not stripped:
2007 if not stripped:
2008 continue
2008 continue
2009 newlevel = len(l) - len(lstripped)
2009 newlevel = len(l) - len(lstripped)
2010 if level > 0 and newlevel == 0 and \
2010 if level > 0 and newlevel == 0 and \
2011 not self._is_secondary_block_start(stripped):
2011 not self._is_secondary_block_start(stripped):
2012 # add empty line
2012 # add empty line
2013 res.append('')
2013 res.append('')
2014 res.append(l)
2014 res.append(l)
2015 level = newlevel
2015 level = newlevel
2016
2016
2017 return '\n'.join(res) + '\n'
2017 return '\n'.join(res) + '\n'
2018
2018
2019 def runlines(self, lines, clean=False):
2019 def runlines(self, lines, clean=False):
2020 """Run a string of one or more lines of source.
2020 """Run a string of one or more lines of source.
2021
2021
2022 This method is capable of running a string containing multiple source
2022 This method is capable of running a string containing multiple source
2023 lines, as if they had been entered at the IPython prompt. Since it
2023 lines, as if they had been entered at the IPython prompt. Since it
2024 exposes IPython's processing machinery, the given strings can contain
2024 exposes IPython's processing machinery, the given strings can contain
2025 magic calls (%magic), special shell access (!cmd), etc.
2025 magic calls (%magic), special shell access (!cmd), etc.
2026 """
2026 """
2027
2027
2028 if isinstance(lines, (list, tuple)):
2028 if isinstance(lines, (list, tuple)):
2029 lines = '\n'.join(lines)
2029 lines = '\n'.join(lines)
2030
2030
2031 if clean:
2031 if clean:
2032 lines = self.cleanup_ipy_script(lines)
2032 lines = self.cleanup_ipy_script(lines)
2033
2033
2034 # We must start with a clean buffer, in case this is run from an
2034 # We must start with a clean buffer, in case this is run from an
2035 # interactive IPython session (via a magic, for example).
2035 # interactive IPython session (via a magic, for example).
2036 self.resetbuffer()
2036 self.resetbuffer()
2037 lines = lines.splitlines()
2037 lines = lines.splitlines()
2038 more = 0
2038 more = 0
2039
2039
2040 with nested(self.builtin_trap, self.display_trap):
2040 with nested(self.builtin_trap, self.display_trap):
2041 for line in lines:
2041 for line in lines:
2042 # skip blank lines so we don't mess up the prompt counter, but do
2042 # skip blank lines so we don't mess up the prompt counter, but do
2043 # NOT skip even a blank line if we are in a code block (more is
2043 # NOT skip even a blank line if we are in a code block (more is
2044 # true)
2044 # true)
2045
2045
2046 if line or more:
2046 if line or more:
2047 # push to raw history, so hist line numbers stay in sync
2047 # push to raw history, so hist line numbers stay in sync
2048 self.input_hist_raw.append("# " + line + "\n")
2048 self.input_hist_raw.append("# " + line + "\n")
2049 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
2049 prefiltered = self.prefilter_manager.prefilter_lines(line,more)
2050 more = self.push_line(prefiltered)
2050 more = self.push_line(prefiltered)
2051 # IPython's runsource returns None if there was an error
2051 # IPython's runsource returns None if there was an error
2052 # compiling the code. This allows us to stop processing right
2052 # compiling the code. This allows us to stop processing right
2053 # away, so the user gets the error message at the right place.
2053 # away, so the user gets the error message at the right place.
2054 if more is None:
2054 if more is None:
2055 break
2055 break
2056 else:
2056 else:
2057 self.input_hist_raw.append("\n")
2057 self.input_hist_raw.append("\n")
2058 # final newline in case the input didn't have it, so that the code
2058 # final newline in case the input didn't have it, so that the code
2059 # actually does get executed
2059 # actually does get executed
2060 if more:
2060 if more:
2061 self.push_line('\n')
2061 self.push_line('\n')
2062
2062
2063 def runsource(self, source, filename='<input>', symbol='single'):
2063 def runsource(self, source, filename='<input>', symbol='single'):
2064 """Compile and run some source in the interpreter.
2064 """Compile and run some source in the interpreter.
2065
2065
2066 Arguments are as for compile_command().
2066 Arguments are as for compile_command().
2067
2067
2068 One several things can happen:
2068 One several things can happen:
2069
2069
2070 1) The input is incorrect; compile_command() raised an
2070 1) The input is incorrect; compile_command() raised an
2071 exception (SyntaxError or OverflowError). A syntax traceback
2071 exception (SyntaxError or OverflowError). A syntax traceback
2072 will be printed by calling the showsyntaxerror() method.
2072 will be printed by calling the showsyntaxerror() method.
2073
2073
2074 2) The input is incomplete, and more input is required;
2074 2) The input is incomplete, and more input is required;
2075 compile_command() returned None. Nothing happens.
2075 compile_command() returned None. Nothing happens.
2076
2076
2077 3) The input is complete; compile_command() returned a code
2077 3) The input is complete; compile_command() returned a code
2078 object. The code is executed by calling self.runcode() (which
2078 object. The code is executed by calling self.runcode() (which
2079 also handles run-time exceptions, except for SystemExit).
2079 also handles run-time exceptions, except for SystemExit).
2080
2080
2081 The return value is:
2081 The return value is:
2082
2082
2083 - True in case 2
2083 - True in case 2
2084
2084
2085 - False in the other cases, unless an exception is raised, where
2085 - False in the other cases, unless an exception is raised, where
2086 None is returned instead. This can be used by external callers to
2086 None is returned instead. This can be used by external callers to
2087 know whether to continue feeding input or not.
2087 know whether to continue feeding input or not.
2088
2088
2089 The return value can be used to decide whether to use sys.ps1 or
2089 The return value can be used to decide whether to use sys.ps1 or
2090 sys.ps2 to prompt the next line."""
2090 sys.ps2 to prompt the next line."""
2091
2091
2092 # if the source code has leading blanks, add 'if 1:\n' to it
2092 # if the source code has leading blanks, add 'if 1:\n' to it
2093 # this allows execution of indented pasted code. It is tempting
2093 # this allows execution of indented pasted code. It is tempting
2094 # to add '\n' at the end of source to run commands like ' a=1'
2094 # to add '\n' at the end of source to run commands like ' a=1'
2095 # directly, but this fails for more complicated scenarios
2095 # directly, but this fails for more complicated scenarios
2096 source=source.encode(self.stdin_encoding)
2096 source=source.encode(self.stdin_encoding)
2097 if source[:1] in [' ', '\t']:
2097 if source[:1] in [' ', '\t']:
2098 source = 'if 1:\n%s' % source
2098 source = 'if 1:\n%s' % source
2099
2099
2100 try:
2100 try:
2101 code = self.compile(source,filename,symbol)
2101 code = self.compile(source,filename,symbol)
2102 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2102 except (OverflowError, SyntaxError, ValueError, TypeError, MemoryError):
2103 # Case 1
2103 # Case 1
2104 self.showsyntaxerror(filename)
2104 self.showsyntaxerror(filename)
2105 return None
2105 return None
2106
2106
2107 if code is None:
2107 if code is None:
2108 # Case 2
2108 # Case 2
2109 return True
2109 return True
2110
2110
2111 # Case 3
2111 # Case 3
2112 # We store the code object so that threaded shells and
2112 # We store the code object so that threaded shells and
2113 # custom exception handlers can access all this info if needed.
2113 # custom exception handlers can access all this info if needed.
2114 # The source corresponding to this can be obtained from the
2114 # The source corresponding to this can be obtained from the
2115 # buffer attribute as '\n'.join(self.buffer).
2115 # buffer attribute as '\n'.join(self.buffer).
2116 self.code_to_run = code
2116 self.code_to_run = code
2117 # now actually execute the code object
2117 # now actually execute the code object
2118 if self.runcode(code) == 0:
2118 if self.runcode(code) == 0:
2119 return False
2119 return False
2120 else:
2120 else:
2121 return None
2121 return None
2122
2122
2123 def runcode(self,code_obj):
2123 def runcode(self,code_obj):
2124 """Execute a code object.
2124 """Execute a code object.
2125
2125
2126 When an exception occurs, self.showtraceback() is called to display a
2126 When an exception occurs, self.showtraceback() is called to display a
2127 traceback.
2127 traceback.
2128
2128
2129 Return value: a flag indicating whether the code to be run completed
2129 Return value: a flag indicating whether the code to be run completed
2130 successfully:
2130 successfully:
2131
2131
2132 - 0: successful execution.
2132 - 0: successful execution.
2133 - 1: an error occurred.
2133 - 1: an error occurred.
2134 """
2134 """
2135
2135
2136 # Set our own excepthook in case the user code tries to call it
2136 # Set our own excepthook in case the user code tries to call it
2137 # directly, so that the IPython crash handler doesn't get triggered
2137 # directly, so that the IPython crash handler doesn't get triggered
2138 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2138 old_excepthook,sys.excepthook = sys.excepthook, self.excepthook
2139
2139
2140 # we save the original sys.excepthook in the instance, in case config
2140 # we save the original sys.excepthook in the instance, in case config
2141 # code (such as magics) needs access to it.
2141 # code (such as magics) needs access to it.
2142 self.sys_excepthook = old_excepthook
2142 self.sys_excepthook = old_excepthook
2143 outflag = 1 # happens in more places, so it's easier as default
2143 outflag = 1 # happens in more places, so it's easier as default
2144 try:
2144 try:
2145 try:
2145 try:
2146 self.hooks.pre_runcode_hook()
2146 self.hooks.pre_runcode_hook()
2147 exec code_obj in self.user_global_ns, self.user_ns
2147 exec code_obj in self.user_global_ns, self.user_ns
2148 finally:
2148 finally:
2149 # Reset our crash handler in place
2149 # Reset our crash handler in place
2150 sys.excepthook = old_excepthook
2150 sys.excepthook = old_excepthook
2151 except SystemExit:
2151 except SystemExit:
2152 self.resetbuffer()
2152 self.resetbuffer()
2153 self.showtraceback()
2153 self.showtraceback()
2154 warn("Type %exit or %quit to exit IPython "
2154 warn("Type %exit or %quit to exit IPython "
2155 "(%Exit or %Quit do so unconditionally).",level=1)
2155 "(%Exit or %Quit do so unconditionally).",level=1)
2156 except self.custom_exceptions:
2156 except self.custom_exceptions:
2157 etype,value,tb = sys.exc_info()
2157 etype,value,tb = sys.exc_info()
2158 self.CustomTB(etype,value,tb)
2158 self.CustomTB(etype,value,tb)
2159 except:
2159 except:
2160 self.showtraceback()
2160 self.showtraceback()
2161 else:
2161 else:
2162 outflag = 0
2162 outflag = 0
2163 if softspace(sys.stdout, 0):
2163 if softspace(sys.stdout, 0):
2164 print
2164 print
2165 # Flush out code object which has been run (and source)
2165 # Flush out code object which has been run (and source)
2166 self.code_to_run = None
2166 self.code_to_run = None
2167 return outflag
2167 return outflag
2168
2168
2169 def push_line(self, line):
2169 def push_line(self, line):
2170 """Push a line to the interpreter.
2170 """Push a line to the interpreter.
2171
2171
2172 The line should not have a trailing newline; it may have
2172 The line should not have a trailing newline; it may have
2173 internal newlines. The line is appended to a buffer and the
2173 internal newlines. The line is appended to a buffer and the
2174 interpreter's runsource() method is called with the
2174 interpreter's runsource() method is called with the
2175 concatenated contents of the buffer as source. If this
2175 concatenated contents of the buffer as source. If this
2176 indicates that the command was executed or invalid, the buffer
2176 indicates that the command was executed or invalid, the buffer
2177 is reset; otherwise, the command is incomplete, and the buffer
2177 is reset; otherwise, the command is incomplete, and the buffer
2178 is left as it was after the line was appended. The return
2178 is left as it was after the line was appended. The return
2179 value is 1 if more input is required, 0 if the line was dealt
2179 value is 1 if more input is required, 0 if the line was dealt
2180 with in some way (this is the same as runsource()).
2180 with in some way (this is the same as runsource()).
2181 """
2181 """
2182
2182
2183 # autoindent management should be done here, and not in the
2183 # autoindent management should be done here, and not in the
2184 # interactive loop, since that one is only seen by keyboard input. We
2184 # interactive loop, since that one is only seen by keyboard input. We
2185 # need this done correctly even for code run via runlines (which uses
2185 # need this done correctly even for code run via runlines (which uses
2186 # push).
2186 # push).
2187
2187
2188 #print 'push line: <%s>' % line # dbg
2188 #print 'push line: <%s>' % line # dbg
2189 for subline in line.splitlines():
2189 for subline in line.splitlines():
2190 self._autoindent_update(subline)
2190 self._autoindent_update(subline)
2191 self.buffer.append(line)
2191 self.buffer.append(line)
2192 more = self.runsource('\n'.join(self.buffer), self.filename)
2192 more = self.runsource('\n'.join(self.buffer), self.filename)
2193 if not more:
2193 if not more:
2194 self.resetbuffer()
2194 self.resetbuffer()
2195 return more
2195 return more
2196
2196
2197 def _autoindent_update(self,line):
2197 def _autoindent_update(self,line):
2198 """Keep track of the indent level."""
2198 """Keep track of the indent level."""
2199
2199
2200 #debugx('line')
2200 #debugx('line')
2201 #debugx('self.indent_current_nsp')
2201 #debugx('self.indent_current_nsp')
2202 if self.autoindent:
2202 if self.autoindent:
2203 if line:
2203 if line:
2204 inisp = num_ini_spaces(line)
2204 inisp = num_ini_spaces(line)
2205 if inisp < self.indent_current_nsp:
2205 if inisp < self.indent_current_nsp:
2206 self.indent_current_nsp = inisp
2206 self.indent_current_nsp = inisp
2207
2207
2208 if line[-1] == ':':
2208 if line[-1] == ':':
2209 self.indent_current_nsp += 4
2209 self.indent_current_nsp += 4
2210 elif dedent_re.match(line):
2210 elif dedent_re.match(line):
2211 self.indent_current_nsp -= 4
2211 self.indent_current_nsp -= 4
2212 else:
2212 else:
2213 self.indent_current_nsp = 0
2213 self.indent_current_nsp = 0
2214
2214
2215 def resetbuffer(self):
2215 def resetbuffer(self):
2216 """Reset the input buffer."""
2216 """Reset the input buffer."""
2217 self.buffer[:] = []
2217 self.buffer[:] = []
2218
2218
2219 def raw_input(self,prompt='',continue_prompt=False):
2219 def raw_input(self,prompt='',continue_prompt=False):
2220 """Write a prompt and read a line.
2220 """Write a prompt and read a line.
2221
2221
2222 The returned line does not include the trailing newline.
2222 The returned line does not include the trailing newline.
2223 When the user enters the EOF key sequence, EOFError is raised.
2223 When the user enters the EOF key sequence, EOFError is raised.
2224
2224
2225 Optional inputs:
2225 Optional inputs:
2226
2226
2227 - prompt(''): a string to be printed to prompt the user.
2227 - prompt(''): a string to be printed to prompt the user.
2228
2228
2229 - continue_prompt(False): whether this line is the first one or a
2229 - continue_prompt(False): whether this line is the first one or a
2230 continuation in a sequence of inputs.
2230 continuation in a sequence of inputs.
2231 """
2231 """
2232 # growl.notify("raw_input: ", "prompt = %r\ncontinue_prompt = %s" % (prompt, continue_prompt))
2232 # growl.notify("raw_input: ", "prompt = %r\ncontinue_prompt = %s" % (prompt, continue_prompt))
2233
2233
2234 # Code run by the user may have modified the readline completer state.
2234 # Code run by the user may have modified the readline completer state.
2235 # We must ensure that our completer is back in place.
2235 # We must ensure that our completer is back in place.
2236
2236
2237 if self.has_readline:
2237 if self.has_readline:
2238 self.set_completer()
2238 self.set_completer()
2239
2239
2240 try:
2240 try:
2241 line = raw_input_original(prompt).decode(self.stdin_encoding)
2241 line = raw_input_original(prompt).decode(self.stdin_encoding)
2242 except ValueError:
2242 except ValueError:
2243 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2243 warn("\n********\nYou or a %run:ed script called sys.stdin.close()"
2244 " or sys.stdout.close()!\nExiting IPython!")
2244 " or sys.stdout.close()!\nExiting IPython!")
2245 self.ask_exit()
2245 self.ask_exit()
2246 return ""
2246 return ""
2247
2247
2248 # Try to be reasonably smart about not re-indenting pasted input more
2248 # Try to be reasonably smart about not re-indenting pasted input more
2249 # than necessary. We do this by trimming out the auto-indent initial
2249 # than necessary. We do this by trimming out the auto-indent initial
2250 # spaces, if the user's actual input started itself with whitespace.
2250 # spaces, if the user's actual input started itself with whitespace.
2251 #debugx('self.buffer[-1]')
2251 #debugx('self.buffer[-1]')
2252
2252
2253 if self.autoindent:
2253 if self.autoindent:
2254 if num_ini_spaces(line) > self.indent_current_nsp:
2254 if num_ini_spaces(line) > self.indent_current_nsp:
2255 line = line[self.indent_current_nsp:]
2255 line = line[self.indent_current_nsp:]
2256 self.indent_current_nsp = 0
2256 self.indent_current_nsp = 0
2257
2257
2258 # store the unfiltered input before the user has any chance to modify
2258 # store the unfiltered input before the user has any chance to modify
2259 # it.
2259 # it.
2260 if line.strip():
2260 if line.strip():
2261 if continue_prompt:
2261 if continue_prompt:
2262 self.input_hist_raw[-1] += '%s\n' % line
2262 self.input_hist_raw[-1] += '%s\n' % line
2263 if self.has_readline and self.readline_use:
2263 if self.has_readline and self.readline_use:
2264 try:
2264 try:
2265 histlen = self.readline.get_current_history_length()
2265 histlen = self.readline.get_current_history_length()
2266 if histlen > 1:
2266 if histlen > 1:
2267 newhist = self.input_hist_raw[-1].rstrip()
2267 newhist = self.input_hist_raw[-1].rstrip()
2268 self.readline.remove_history_item(histlen-1)
2268 self.readline.remove_history_item(histlen-1)
2269 self.readline.replace_history_item(histlen-2,
2269 self.readline.replace_history_item(histlen-2,
2270 newhist.encode(self.stdin_encoding))
2270 newhist.encode(self.stdin_encoding))
2271 except AttributeError:
2271 except AttributeError:
2272 pass # re{move,place}_history_item are new in 2.4.
2272 pass # re{move,place}_history_item are new in 2.4.
2273 else:
2273 else:
2274 self.input_hist_raw.append('%s\n' % line)
2274 self.input_hist_raw.append('%s\n' % line)
2275 # only entries starting at first column go to shadow history
2275 # only entries starting at first column go to shadow history
2276 if line.lstrip() == line:
2276 if line.lstrip() == line:
2277 self.shadowhist.add(line.strip())
2277 self.shadowhist.add(line.strip())
2278 elif not continue_prompt:
2278 elif not continue_prompt:
2279 self.input_hist_raw.append('\n')
2279 self.input_hist_raw.append('\n')
2280 try:
2280 try:
2281 lineout = self.prefilter_manager.prefilter_lines(line,continue_prompt)
2281 lineout = self.prefilter_manager.prefilter_lines(line,continue_prompt)
2282 except:
2282 except:
2283 # blanket except, in case a user-defined prefilter crashes, so it
2283 # blanket except, in case a user-defined prefilter crashes, so it
2284 # can't take all of ipython with it.
2284 # can't take all of ipython with it.
2285 self.showtraceback()
2285 self.showtraceback()
2286 return ''
2286 return ''
2287 else:
2287 else:
2288 return lineout
2288 return lineout
2289
2289
2290 #-------------------------------------------------------------------------
2290 #-------------------------------------------------------------------------
2291 # Working with components
2291 # Working with components
2292 #-------------------------------------------------------------------------
2292 #-------------------------------------------------------------------------
2293
2293
2294 def get_component(self, name=None, klass=None):
2294 def get_component(self, name=None, klass=None):
2295 """Fetch a component by name and klass in my tree."""
2295 """Fetch a component by name and klass in my tree."""
2296 c = Component.get_instances(root=self, name=name, klass=klass)
2296 c = Component.get_instances(root=self, name=name, klass=klass)
2297 if len(c) == 0:
2297 if len(c) == 0:
2298 return None
2298 return None
2299 if len(c) == 1:
2299 if len(c) == 1:
2300 return c[0]
2300 return c[0]
2301 else:
2301 else:
2302 return c
2302 return c
2303
2303
2304 #-------------------------------------------------------------------------
2304 #-------------------------------------------------------------------------
2305 # IPython extensions
2305 # IPython extensions
2306 #-------------------------------------------------------------------------
2306 #-------------------------------------------------------------------------
2307
2307
2308 def load_extension(self, module_str):
2308 def load_extension(self, module_str):
2309 """Load an IPython extension by its module name.
2309 """Load an IPython extension by its module name.
2310
2310
2311 An IPython extension is an importable Python module that has
2311 An IPython extension is an importable Python module that has
2312 a function with the signature::
2312 a function with the signature::
2313
2313
2314 def load_ipython_extension(ipython):
2314 def load_ipython_extension(ipython):
2315 # Do things with ipython
2315 # Do things with ipython
2316
2316
2317 This function is called after your extension is imported and the
2317 This function is called after your extension is imported and the
2318 currently active :class:`InteractiveShell` instance is passed as
2318 currently active :class:`InteractiveShell` instance is passed as
2319 the only argument. You can do anything you want with IPython at
2319 the only argument. You can do anything you want with IPython at
2320 that point, including defining new magic and aliases, adding new
2320 that point, including defining new magic and aliases, adding new
2321 components, etc.
2321 components, etc.
2322
2322
2323 The :func:`load_ipython_extension` will be called again is you
2323 The :func:`load_ipython_extension` will be called again is you
2324 load or reload the extension again. It is up to the extension
2324 load or reload the extension again. It is up to the extension
2325 author to add code to manage that.
2325 author to add code to manage that.
2326
2326
2327 You can put your extension modules anywhere you want, as long as
2327 You can put your extension modules anywhere you want, as long as
2328 they can be imported by Python's standard import mechanism. However,
2328 they can be imported by Python's standard import mechanism. However,
2329 to make it easy to write extensions, you can also put your extensions
2329 to make it easy to write extensions, you can also put your extensions
2330 in ``os.path.join(self.ipython_dir, 'extensions')``. This directory
2330 in ``os.path.join(self.ipython_dir, 'extensions')``. This directory
2331 is added to ``sys.path`` automatically.
2331 is added to ``sys.path`` automatically.
2332 """
2332 """
2333 from IPython.utils.syspathcontext import prepended_to_syspath
2333 from IPython.utils.syspathcontext import prepended_to_syspath
2334
2334
2335 if module_str not in sys.modules:
2335 if module_str not in sys.modules:
2336 with prepended_to_syspath(self.ipython_extension_dir):
2336 with prepended_to_syspath(self.ipython_extension_dir):
2337 __import__(module_str)
2337 __import__(module_str)
2338 mod = sys.modules[module_str]
2338 mod = sys.modules[module_str]
2339 self._call_load_ipython_extension(mod)
2339 self._call_load_ipython_extension(mod)
2340
2340
2341 def unload_extension(self, module_str):
2341 def unload_extension(self, module_str):
2342 """Unload an IPython extension by its module name.
2342 """Unload an IPython extension by its module name.
2343
2343
2344 This function looks up the extension's name in ``sys.modules`` and
2344 This function looks up the extension's name in ``sys.modules`` and
2345 simply calls ``mod.unload_ipython_extension(self)``.
2345 simply calls ``mod.unload_ipython_extension(self)``.
2346 """
2346 """
2347 if module_str in sys.modules:
2347 if module_str in sys.modules:
2348 mod = sys.modules[module_str]
2348 mod = sys.modules[module_str]
2349 self._call_unload_ipython_extension(mod)
2349 self._call_unload_ipython_extension(mod)
2350
2350
2351 def reload_extension(self, module_str):
2351 def reload_extension(self, module_str):
2352 """Reload an IPython extension by calling reload.
2352 """Reload an IPython extension by calling reload.
2353
2353
2354 If the module has not been loaded before,
2354 If the module has not been loaded before,
2355 :meth:`InteractiveShell.load_extension` is called. Otherwise
2355 :meth:`InteractiveShell.load_extension` is called. Otherwise
2356 :func:`reload` is called and then the :func:`load_ipython_extension`
2356 :func:`reload` is called and then the :func:`load_ipython_extension`
2357 function of the module, if it exists is called.
2357 function of the module, if it exists is called.
2358 """
2358 """
2359 from IPython.utils.syspathcontext import prepended_to_syspath
2359 from IPython.utils.syspathcontext import prepended_to_syspath
2360
2360
2361 with prepended_to_syspath(self.ipython_extension_dir):
2361 with prepended_to_syspath(self.ipython_extension_dir):
2362 if module_str in sys.modules:
2362 if module_str in sys.modules:
2363 mod = sys.modules[module_str]
2363 mod = sys.modules[module_str]
2364 reload(mod)
2364 reload(mod)
2365 self._call_load_ipython_extension(mod)
2365 self._call_load_ipython_extension(mod)
2366 else:
2366 else:
2367 self.load_extension(module_str)
2367 self.load_extension(module_str)
2368
2368
2369 def _call_load_ipython_extension(self, mod):
2369 def _call_load_ipython_extension(self, mod):
2370 if hasattr(mod, 'load_ipython_extension'):
2370 if hasattr(mod, 'load_ipython_extension'):
2371 mod.load_ipython_extension(self)
2371 mod.load_ipython_extension(self)
2372
2372
2373 def _call_unload_ipython_extension(self, mod):
2373 def _call_unload_ipython_extension(self, mod):
2374 if hasattr(mod, 'unload_ipython_extension'):
2374 if hasattr(mod, 'unload_ipython_extension'):
2375 mod.unload_ipython_extension(self)
2375 mod.unload_ipython_extension(self)
2376
2376
2377 #-------------------------------------------------------------------------
2377 #-------------------------------------------------------------------------
2378 # Things related to the prefilter
2378 # Things related to the prefilter
2379 #-------------------------------------------------------------------------
2379 #-------------------------------------------------------------------------
2380
2380
2381 def init_prefilter(self):
2381 def init_prefilter(self):
2382 self.prefilter_manager = PrefilterManager(self, config=self.config)
2382 self.prefilter_manager = PrefilterManager(self, config=self.config)
2383
2383
2384 #-------------------------------------------------------------------------
2384 #-------------------------------------------------------------------------
2385 # Utilities
2385 # Utilities
2386 #-------------------------------------------------------------------------
2386 #-------------------------------------------------------------------------
2387
2387
2388 def getoutput(self, cmd):
2388 def getoutput(self, cmd):
2389 return getoutput(self.var_expand(cmd,depth=2),
2389 return getoutput(self.var_expand(cmd,depth=2),
2390 header=self.system_header,
2390 header=self.system_header,
2391 verbose=self.system_verbose)
2391 verbose=self.system_verbose)
2392
2392
2393 def getoutputerror(self, cmd):
2393 def getoutputerror(self, cmd):
2394 return getoutputerror(self.var_expand(cmd,depth=2),
2394 return getoutputerror(self.var_expand(cmd,depth=2),
2395 header=self.system_header,
2395 header=self.system_header,
2396 verbose=self.system_verbose)
2396 verbose=self.system_verbose)
2397
2397
2398 def var_expand(self,cmd,depth=0):
2398 def var_expand(self,cmd,depth=0):
2399 """Expand python variables in a string.
2399 """Expand python variables in a string.
2400
2400
2401 The depth argument indicates how many frames above the caller should
2401 The depth argument indicates how many frames above the caller should
2402 be walked to look for the local namespace where to expand variables.
2402 be walked to look for the local namespace where to expand variables.
2403
2403
2404 The global namespace for expansion is always the user's interactive
2404 The global namespace for expansion is always the user's interactive
2405 namespace.
2405 namespace.
2406 """
2406 """
2407
2407
2408 return str(ItplNS(cmd,
2408 return str(ItplNS(cmd,
2409 self.user_ns, # globals
2409 self.user_ns, # globals
2410 # Skip our own frame in searching for locals:
2410 # Skip our own frame in searching for locals:
2411 sys._getframe(depth+1).f_locals # locals
2411 sys._getframe(depth+1).f_locals # locals
2412 ))
2412 ))
2413
2413
2414 def mktempfile(self,data=None):
2414 def mktempfile(self,data=None):
2415 """Make a new tempfile and return its filename.
2415 """Make a new tempfile and return its filename.
2416
2416
2417 This makes a call to tempfile.mktemp, but it registers the created
2417 This makes a call to tempfile.mktemp, but it registers the created
2418 filename internally so ipython cleans it up at exit time.
2418 filename internally so ipython cleans it up at exit time.
2419
2419
2420 Optional inputs:
2420 Optional inputs:
2421
2421
2422 - data(None): if data is given, it gets written out to the temp file
2422 - data(None): if data is given, it gets written out to the temp file
2423 immediately, and the file is closed again."""
2423 immediately, and the file is closed again."""
2424
2424
2425 filename = tempfile.mktemp('.py','ipython_edit_')
2425 filename = tempfile.mktemp('.py','ipython_edit_')
2426 self.tempfiles.append(filename)
2426 self.tempfiles.append(filename)
2427
2427
2428 if data:
2428 if data:
2429 tmp_file = open(filename,'w')
2429 tmp_file = open(filename,'w')
2430 tmp_file.write(data)
2430 tmp_file.write(data)
2431 tmp_file.close()
2431 tmp_file.close()
2432 return filename
2432 return filename
2433
2433
2434 def write(self,data):
2434 def write(self,data):
2435 """Write a string to the default output"""
2435 """Write a string to the default output"""
2436 Term.cout.write(data)
2436 Term.cout.write(data)
2437
2437
2438 def write_err(self,data):
2438 def write_err(self,data):
2439 """Write a string to the default error output"""
2439 """Write a string to the default error output"""
2440 Term.cerr.write(data)
2440 Term.cerr.write(data)
2441
2441
2442 def ask_yes_no(self,prompt,default=True):
2442 def ask_yes_no(self,prompt,default=True):
2443 if self.quiet:
2443 if self.quiet:
2444 return True
2444 return True
2445 return ask_yes_no(prompt,default)
2445 return ask_yes_no(prompt,default)
2446
2446
2447 #-------------------------------------------------------------------------
2447 #-------------------------------------------------------------------------
2448 # Things related to GUI support and pylab
2449 #-------------------------------------------------------------------------
2450
2451 def enable_pylab(self, gui=None):
2452 """
2453 """
2454 gui = pylab_activate(self.user_ns, gui)
2455 enable_gui(gui)
2456 self.magic_run = self._pylab_magic_run
2457
2458
2459 #-------------------------------------------------------------------------
2448 # Things related to IPython exiting
2460 # Things related to IPython exiting
2449 #-------------------------------------------------------------------------
2461 #-------------------------------------------------------------------------
2450
2462
2451 def ask_exit(self):
2463 def ask_exit(self):
2452 """ Call for exiting. Can be overiden and used as a callback. """
2464 """ Call for exiting. Can be overiden and used as a callback. """
2453 self.exit_now = True
2465 self.exit_now = True
2454
2466
2455 def exit(self):
2467 def exit(self):
2456 """Handle interactive exit.
2468 """Handle interactive exit.
2457
2469
2458 This method calls the ask_exit callback."""
2470 This method calls the ask_exit callback."""
2459 if self.confirm_exit:
2471 if self.confirm_exit:
2460 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2472 if self.ask_yes_no('Do you really want to exit ([y]/n)?','y'):
2461 self.ask_exit()
2473 self.ask_exit()
2462 else:
2474 else:
2463 self.ask_exit()
2475 self.ask_exit()
2464
2476
2465 def atexit_operations(self):
2477 def atexit_operations(self):
2466 """This will be executed at the time of exit.
2478 """This will be executed at the time of exit.
2467
2479
2468 Saving of persistent data should be performed here.
2480 Saving of persistent data should be performed here.
2469 """
2481 """
2470 self.savehist()
2482 self.savehist()
2471
2483
2472 # Cleanup all tempfiles left around
2484 # Cleanup all tempfiles left around
2473 for tfile in self.tempfiles:
2485 for tfile in self.tempfiles:
2474 try:
2486 try:
2475 os.unlink(tfile)
2487 os.unlink(tfile)
2476 except OSError:
2488 except OSError:
2477 pass
2489 pass
2478
2490
2479 # Clear all user namespaces to release all references cleanly.
2491 # Clear all user namespaces to release all references cleanly.
2480 self.reset()
2492 self.reset()
2481
2493
2482 # Run user hooks
2494 # Run user hooks
2483 self.hooks.shutdown_hook()
2495 self.hooks.shutdown_hook()
2484
2496
2485 def cleanup(self):
2497 def cleanup(self):
2486 self.restore_sys_module_state()
2498 self.restore_sys_module_state()
2487
2499
2488
2500
@@ -1,3765 +1,3626 b''
1 # -*- coding: utf-8 -*-
1 # -*- coding: utf-8 -*-
2 """Magic functions for InteractiveShell.
2 """Magic functions for InteractiveShell.
3 """
3 """
4
4
5 #*****************************************************************************
5 #*****************************************************************************
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
7 # Copyright (C) 2001-2006 Fernando Perez <fperez@colorado.edu>
8 #
8 #
9 # Distributed under the terms of the BSD License. The full license is in
9 # Distributed under the terms of the BSD License. The full license is in
10 # the file COPYING, distributed as part of this software.
10 # the file COPYING, distributed as part of this software.
11 #*****************************************************************************
11 #*****************************************************************************
12
12
13 #****************************************************************************
13 #****************************************************************************
14 # Modules and globals
14 # Modules and globals
15
15
16 # Python standard modules
16 # Python standard modules
17 import __builtin__
17 import __builtin__
18 import bdb
18 import bdb
19 import inspect
19 import inspect
20 import os
20 import os
21 import pdb
21 import pdb
22 import pydoc
22 import pydoc
23 import sys
23 import sys
24 import shutil
24 import shutil
25 import re
25 import re
26 import tempfile
26 import tempfile
27 import time
27 import time
28 import cPickle as pickle
28 import cPickle as pickle
29 import textwrap
29 import textwrap
30 from cStringIO import StringIO
30 from cStringIO import StringIO
31 from getopt import getopt,GetoptError
31 from getopt import getopt,GetoptError
32 from pprint import pprint, pformat
32 from pprint import pprint, pformat
33
33
34 # cProfile was added in Python2.5
34 # cProfile was added in Python2.5
35 try:
35 try:
36 import cProfile as profile
36 import cProfile as profile
37 import pstats
37 import pstats
38 except ImportError:
38 except ImportError:
39 # profile isn't bundled by default in Debian for license reasons
39 # profile isn't bundled by default in Debian for license reasons
40 try:
40 try:
41 import profile,pstats
41 import profile,pstats
42 except ImportError:
42 except ImportError:
43 profile = pstats = None
43 profile = pstats = None
44
44
45 # Homebrewed
45 # Homebrewed
46 import IPython
46 import IPython
47 from IPython.utils import wildcard
47 import IPython.utils.generics
48
48 from IPython.core import debugger, oinspect
49 from IPython.core import debugger, oinspect
49 from IPython.core.error import TryNext
50 from IPython.core.error import TryNext
51 from IPython.core.error import UsageError
50 from IPython.core.fakemodule import FakeModule
52 from IPython.core.fakemodule import FakeModule
53 from IPython.core.macro import Macro
54 from IPython.core.page import page
51 from IPython.core.prefilter import ESC_MAGIC
55 from IPython.core.prefilter import ESC_MAGIC
56 from IPython.core.pylabtools import mpl_runner
57 from IPython.lib.inputhook import enable_gui
52 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
58 from IPython.external.Itpl import Itpl, itpl, printpl,itplns
59 from IPython.testing import decorators as testdec
60 from IPython.utils import platutils
61 from IPython.utils import wildcard
53 from IPython.utils.PyColorize import Parser
62 from IPython.utils.PyColorize import Parser
54 from IPython.utils.ipstruct import Struct
63 from IPython.utils.ipstruct import Struct
55 from IPython.core.macro import Macro
64
65 # XXX - We need to switch to explicit imports here with genutils
56 from IPython.utils.genutils import *
66 from IPython.utils.genutils import *
57 from IPython.core.page import page
58 from IPython.utils import platutils
59 import IPython.utils.generics
60 from IPython.core.error import UsageError
61 from IPython.testing import decorators as testdec
62
67
63 #***************************************************************************
68 #***************************************************************************
64 # Utility functions
69 # Utility functions
65 def on_off(tag):
70 def on_off(tag):
66 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
71 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
67 return ['OFF','ON'][tag]
72 return ['OFF','ON'][tag]
68
73
69 class Bunch: pass
74 class Bunch: pass
70
75
71 def compress_dhist(dh):
76 def compress_dhist(dh):
72 head, tail = dh[:-10], dh[-10:]
77 head, tail = dh[:-10], dh[-10:]
73
78
74 newhead = []
79 newhead = []
75 done = set()
80 done = set()
76 for h in head:
81 for h in head:
77 if h in done:
82 if h in done:
78 continue
83 continue
79 newhead.append(h)
84 newhead.append(h)
80 done.add(h)
85 done.add(h)
81
86
82 return newhead + tail
87 return newhead + tail
83
88
84
89
85 def pylab_activate(user_ns, gui=None, import_all=True):
86 """Activate pylab mode in the user's namespace.
87
88 Loads and initializes numpy, matplotlib and friends for interactive use.
89
90 Parameters
91 ----------
92 user_ns : dict
93 Namespace where the imports will occur.
94
95 gui : optional, string
96 A valid gui name following the conventions of the %gui magic.
97
98 import_all : optional, boolean
99 If true, an 'import *' is done from numpy and pylab.
100
101 Returns
102 -------
103 The actual gui used (if not given as input, it was obtained from matplotlib
104 itself, and will be needed next to configure IPython's gui integration.
105 """
106
107 # Initialize matplotlib to interactive mode always
108 import matplotlib
109
110 # If user specifies a GUI, that dictates the backend, otherwise we read the
111 # user's mpl default from the mpl rc structure
112 g2b = {'tk': 'TkAgg',
113 'gtk': 'GTKAgg',
114 'wx': 'WXAgg',
115 'qt': 'Qt4Agg', # qt3 not supported
116 'qt4': 'Qt4Agg' }
117
118 if gui:
119 # select backend based on requested gui
120 backend = g2b[gui]
121 else:
122 backend = matplotlib.rcParams['backend']
123 # In this case, we need to find what the appropriate gui selection call
124 # should be for IPython, so we can activate inputhook accordingly
125 b2g = dict(zip(g2b.values(),g2b.keys()))
126 gui = b2g[backend]
127
128 # We must set the desired backend before importing pylab
129 matplotlib.use(backend)
130
131 # This must be imported last in the matplotlib series, after
132 # backend/interactivity choices have been made
133 import matplotlib.pylab as pylab
134
135 # XXX For now leave this commented out, but depending on discussions with
136 # mpl-dev, we may be able to allow interactive switching...
137 #import matplotlib.pyplot
138 #matplotlib.pyplot.switch_backend(backend)
139
140 pylab.show._needmain = False
141 # We need to detect at runtime whether show() is called by the user.
142 # For this, we wrap it into a decorator which adds a 'called' flag.
143 pylab.draw_if_interactive = flag_calls(pylab.draw_if_interactive)
144
145 # Import numpy as np/pyplot as plt are conventions we're trying to
146 # somewhat standardize on. Making them available to users by default
147 # will greatly help this.
148 exec ("import numpy\n"
149 "import numpy as np\n"
150 "import matplotlib\n"
151 "from matplotlib import pylab, mlab, pyplot as plt\n"
152 ) in user_ns
153
154 if import_all:
155 exec("from matplotlib.pylab import *\n"
156 "from numpy import *\n") in user_ns
157
158 matplotlib.interactive(True)
159
160 print """
161 Welcome to pylab, a matplotlib-based Python environment.
162 Backend in use: %s
163 For more information, type 'help(pylab)'.""" % backend
164
165 return gui
166
167 # We need a little factory function here to create the closure where
168 # safe_execfile can live.
169 def mpl_runner(safe_execfile):
170 """Factory to return a matplotlib-enabled runner for %run.
171
172 Parameters
173 ----------
174 safe_execfile : function
175 This must be a function with the same interface as the
176 :meth:`safe_execfile` method of IPython.
177
178 Returns
179 -------
180 A function suitable for use as the ``runner`` argument of the %run magic
181 function.
182 """
183
184 def mpl_execfile(fname,*where,**kw):
185 """matplotlib-aware wrapper around safe_execfile.
186
187 Its interface is identical to that of the :func:`execfile` builtin.
188
189 This is ultimately a call to execfile(), but wrapped in safeties to
190 properly handle interactive rendering."""
191
192 import matplotlib
193 import matplotlib.pylab as pylab
194
195 #print '*** Matplotlib runner ***' # dbg
196 # turn off rendering until end of script
197 is_interactive = matplotlib.rcParams['interactive']
198 matplotlib.interactive(False)
199 safe_execfile(fname,*where,**kw)
200 matplotlib.interactive(is_interactive)
201 # make rendering call now, if the user tried to do it
202 if pylab.draw_if_interactive.called:
203 pylab.draw()
204 pylab.draw_if_interactive.called = False
205
206 return mpl_execfile
207
208
209 #***************************************************************************
90 #***************************************************************************
210 # Main class implementing Magic functionality
91 # Main class implementing Magic functionality
211
92
212 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
93 # XXX - for some odd reason, if Magic is made a new-style class, we get errors
213 # on construction of the main InteractiveShell object. Something odd is going
94 # on construction of the main InteractiveShell object. Something odd is going
214 # on with super() calls, Component and the MRO... For now leave it as-is, but
95 # on with super() calls, Component and the MRO... For now leave it as-is, but
215 # eventually this needs to be clarified.
96 # eventually this needs to be clarified.
216
97
217 class Magic:
98 class Magic:
218 """Magic functions for InteractiveShell.
99 """Magic functions for InteractiveShell.
219
100
220 Shell functions which can be reached as %function_name. All magic
101 Shell functions which can be reached as %function_name. All magic
221 functions should accept a string, which they can parse for their own
102 functions should accept a string, which they can parse for their own
222 needs. This can make some functions easier to type, eg `%cd ../`
103 needs. This can make some functions easier to type, eg `%cd ../`
223 vs. `%cd("../")`
104 vs. `%cd("../")`
224
105
225 ALL definitions MUST begin with the prefix magic_. The user won't need it
106 ALL definitions MUST begin with the prefix magic_. The user won't need it
226 at the command line, but it is is needed in the definition. """
107 at the command line, but it is is needed in the definition. """
227
108
228 # class globals
109 # class globals
229 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
110 auto_status = ['Automagic is OFF, % prefix IS needed for magic functions.',
230 'Automagic is ON, % prefix NOT needed for magic functions.']
111 'Automagic is ON, % prefix NOT needed for magic functions.']
231
112
232 #......................................................................
113 #......................................................................
233 # some utility functions
114 # some utility functions
234
115
235 def __init__(self,shell):
116 def __init__(self,shell):
236
117
237 self.options_table = {}
118 self.options_table = {}
238 if profile is None:
119 if profile is None:
239 self.magic_prun = self.profile_missing_notice
120 self.magic_prun = self.profile_missing_notice
240 self.shell = shell
121 self.shell = shell
241
122
242 # namespace for holding state we may need
123 # namespace for holding state we may need
243 self._magic_state = Bunch()
124 self._magic_state = Bunch()
244
125
245 def profile_missing_notice(self, *args, **kwargs):
126 def profile_missing_notice(self, *args, **kwargs):
246 error("""\
127 error("""\
247 The profile module could not be found. It has been removed from the standard
128 The profile module could not be found. It has been removed from the standard
248 python packages because of its non-free license. To use profiling, install the
129 python packages because of its non-free license. To use profiling, install the
249 python-profiler package from non-free.""")
130 python-profiler package from non-free.""")
250
131
251 def default_option(self,fn,optstr):
132 def default_option(self,fn,optstr):
252 """Make an entry in the options_table for fn, with value optstr"""
133 """Make an entry in the options_table for fn, with value optstr"""
253
134
254 if fn not in self.lsmagic():
135 if fn not in self.lsmagic():
255 error("%s is not a magic function" % fn)
136 error("%s is not a magic function" % fn)
256 self.options_table[fn] = optstr
137 self.options_table[fn] = optstr
257
138
258 def lsmagic(self):
139 def lsmagic(self):
259 """Return a list of currently available magic functions.
140 """Return a list of currently available magic functions.
260
141
261 Gives a list of the bare names after mangling (['ls','cd', ...], not
142 Gives a list of the bare names after mangling (['ls','cd', ...], not
262 ['magic_ls','magic_cd',...]"""
143 ['magic_ls','magic_cd',...]"""
263
144
264 # FIXME. This needs a cleanup, in the way the magics list is built.
145 # FIXME. This needs a cleanup, in the way the magics list is built.
265
146
266 # magics in class definition
147 # magics in class definition
267 class_magic = lambda fn: fn.startswith('magic_') and \
148 class_magic = lambda fn: fn.startswith('magic_') and \
268 callable(Magic.__dict__[fn])
149 callable(Magic.__dict__[fn])
269 # in instance namespace (run-time user additions)
150 # in instance namespace (run-time user additions)
270 inst_magic = lambda fn: fn.startswith('magic_') and \
151 inst_magic = lambda fn: fn.startswith('magic_') and \
271 callable(self.__dict__[fn])
152 callable(self.__dict__[fn])
272 # and bound magics by user (so they can access self):
153 # and bound magics by user (so they can access self):
273 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
154 inst_bound_magic = lambda fn: fn.startswith('magic_') and \
274 callable(self.__class__.__dict__[fn])
155 callable(self.__class__.__dict__[fn])
275 magics = filter(class_magic,Magic.__dict__.keys()) + \
156 magics = filter(class_magic,Magic.__dict__.keys()) + \
276 filter(inst_magic,self.__dict__.keys()) + \
157 filter(inst_magic,self.__dict__.keys()) + \
277 filter(inst_bound_magic,self.__class__.__dict__.keys())
158 filter(inst_bound_magic,self.__class__.__dict__.keys())
278 out = []
159 out = []
279 for fn in set(magics):
160 for fn in set(magics):
280 out.append(fn.replace('magic_','',1))
161 out.append(fn.replace('magic_','',1))
281 out.sort()
162 out.sort()
282 return out
163 return out
283
164
284 def extract_input_slices(self,slices,raw=False):
165 def extract_input_slices(self,slices,raw=False):
285 """Return as a string a set of input history slices.
166 """Return as a string a set of input history slices.
286
167
287 Inputs:
168 Inputs:
288
169
289 - slices: the set of slices is given as a list of strings (like
170 - slices: the set of slices is given as a list of strings (like
290 ['1','4:8','9'], since this function is for use by magic functions
171 ['1','4:8','9'], since this function is for use by magic functions
291 which get their arguments as strings.
172 which get their arguments as strings.
292
173
293 Optional inputs:
174 Optional inputs:
294
175
295 - raw(False): by default, the processed input is used. If this is
176 - raw(False): by default, the processed input is used. If this is
296 true, the raw input history is used instead.
177 true, the raw input history is used instead.
297
178
298 Note that slices can be called with two notations:
179 Note that slices can be called with two notations:
299
180
300 N:M -> standard python form, means including items N...(M-1).
181 N:M -> standard python form, means including items N...(M-1).
301
182
302 N-M -> include items N..M (closed endpoint)."""
183 N-M -> include items N..M (closed endpoint)."""
303
184
304 if raw:
185 if raw:
305 hist = self.shell.input_hist_raw
186 hist = self.shell.input_hist_raw
306 else:
187 else:
307 hist = self.shell.input_hist
188 hist = self.shell.input_hist
308
189
309 cmds = []
190 cmds = []
310 for chunk in slices:
191 for chunk in slices:
311 if ':' in chunk:
192 if ':' in chunk:
312 ini,fin = map(int,chunk.split(':'))
193 ini,fin = map(int,chunk.split(':'))
313 elif '-' in chunk:
194 elif '-' in chunk:
314 ini,fin = map(int,chunk.split('-'))
195 ini,fin = map(int,chunk.split('-'))
315 fin += 1
196 fin += 1
316 else:
197 else:
317 ini = int(chunk)
198 ini = int(chunk)
318 fin = ini+1
199 fin = ini+1
319 cmds.append(hist[ini:fin])
200 cmds.append(hist[ini:fin])
320 return cmds
201 return cmds
321
202
322 def _ofind(self, oname, namespaces=None):
203 def _ofind(self, oname, namespaces=None):
323 """Find an object in the available namespaces.
204 """Find an object in the available namespaces.
324
205
325 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
206 self._ofind(oname) -> dict with keys: found,obj,ospace,ismagic
326
207
327 Has special code to detect magic functions.
208 Has special code to detect magic functions.
328 """
209 """
329
210
330 oname = oname.strip()
211 oname = oname.strip()
331
212
332 alias_ns = None
213 alias_ns = None
333 if namespaces is None:
214 if namespaces is None:
334 # Namespaces to search in:
215 # Namespaces to search in:
335 # Put them in a list. The order is important so that we
216 # Put them in a list. The order is important so that we
336 # find things in the same order that Python finds them.
217 # find things in the same order that Python finds them.
337 namespaces = [ ('Interactive', self.shell.user_ns),
218 namespaces = [ ('Interactive', self.shell.user_ns),
338 ('IPython internal', self.shell.internal_ns),
219 ('IPython internal', self.shell.internal_ns),
339 ('Python builtin', __builtin__.__dict__),
220 ('Python builtin', __builtin__.__dict__),
340 ('Alias', self.shell.alias_manager.alias_table),
221 ('Alias', self.shell.alias_manager.alias_table),
341 ]
222 ]
342 alias_ns = self.shell.alias_manager.alias_table
223 alias_ns = self.shell.alias_manager.alias_table
343
224
344 # initialize results to 'null'
225 # initialize results to 'null'
345 found = 0; obj = None; ospace = None; ds = None;
226 found = 0; obj = None; ospace = None; ds = None;
346 ismagic = 0; isalias = 0; parent = None
227 ismagic = 0; isalias = 0; parent = None
347
228
348 # Look for the given name by splitting it in parts. If the head is
229 # Look for the given name by splitting it in parts. If the head is
349 # found, then we look for all the remaining parts as members, and only
230 # found, then we look for all the remaining parts as members, and only
350 # declare success if we can find them all.
231 # declare success if we can find them all.
351 oname_parts = oname.split('.')
232 oname_parts = oname.split('.')
352 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
233 oname_head, oname_rest = oname_parts[0],oname_parts[1:]
353 for nsname,ns in namespaces:
234 for nsname,ns in namespaces:
354 try:
235 try:
355 obj = ns[oname_head]
236 obj = ns[oname_head]
356 except KeyError:
237 except KeyError:
357 continue
238 continue
358 else:
239 else:
359 #print 'oname_rest:', oname_rest # dbg
240 #print 'oname_rest:', oname_rest # dbg
360 for part in oname_rest:
241 for part in oname_rest:
361 try:
242 try:
362 parent = obj
243 parent = obj
363 obj = getattr(obj,part)
244 obj = getattr(obj,part)
364 except:
245 except:
365 # Blanket except b/c some badly implemented objects
246 # Blanket except b/c some badly implemented objects
366 # allow __getattr__ to raise exceptions other than
247 # allow __getattr__ to raise exceptions other than
367 # AttributeError, which then crashes IPython.
248 # AttributeError, which then crashes IPython.
368 break
249 break
369 else:
250 else:
370 # If we finish the for loop (no break), we got all members
251 # If we finish the for loop (no break), we got all members
371 found = 1
252 found = 1
372 ospace = nsname
253 ospace = nsname
373 if ns == alias_ns:
254 if ns == alias_ns:
374 isalias = 1
255 isalias = 1
375 break # namespace loop
256 break # namespace loop
376
257
377 # Try to see if it's magic
258 # Try to see if it's magic
378 if not found:
259 if not found:
379 if oname.startswith(ESC_MAGIC):
260 if oname.startswith(ESC_MAGIC):
380 oname = oname[1:]
261 oname = oname[1:]
381 obj = getattr(self,'magic_'+oname,None)
262 obj = getattr(self,'magic_'+oname,None)
382 if obj is not None:
263 if obj is not None:
383 found = 1
264 found = 1
384 ospace = 'IPython internal'
265 ospace = 'IPython internal'
385 ismagic = 1
266 ismagic = 1
386
267
387 # Last try: special-case some literals like '', [], {}, etc:
268 # Last try: special-case some literals like '', [], {}, etc:
388 if not found and oname_head in ["''",'""','[]','{}','()']:
269 if not found and oname_head in ["''",'""','[]','{}','()']:
389 obj = eval(oname_head)
270 obj = eval(oname_head)
390 found = 1
271 found = 1
391 ospace = 'Interactive'
272 ospace = 'Interactive'
392
273
393 return {'found':found, 'obj':obj, 'namespace':ospace,
274 return {'found':found, 'obj':obj, 'namespace':ospace,
394 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
275 'ismagic':ismagic, 'isalias':isalias, 'parent':parent}
395
276
396 def arg_err(self,func):
277 def arg_err(self,func):
397 """Print docstring if incorrect arguments were passed"""
278 """Print docstring if incorrect arguments were passed"""
398 print 'Error in arguments:'
279 print 'Error in arguments:'
399 print OInspect.getdoc(func)
280 print OInspect.getdoc(func)
400
281
401 def format_latex(self,strng):
282 def format_latex(self,strng):
402 """Format a string for latex inclusion."""
283 """Format a string for latex inclusion."""
403
284
404 # Characters that need to be escaped for latex:
285 # Characters that need to be escaped for latex:
405 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
286 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
406 # Magic command names as headers:
287 # Magic command names as headers:
407 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
288 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
408 re.MULTILINE)
289 re.MULTILINE)
409 # Magic commands
290 # Magic commands
410 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
291 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
411 re.MULTILINE)
292 re.MULTILINE)
412 # Paragraph continue
293 # Paragraph continue
413 par_re = re.compile(r'\\$',re.MULTILINE)
294 par_re = re.compile(r'\\$',re.MULTILINE)
414
295
415 # The "\n" symbol
296 # The "\n" symbol
416 newline_re = re.compile(r'\\n')
297 newline_re = re.compile(r'\\n')
417
298
418 # Now build the string for output:
299 # Now build the string for output:
419 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
300 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
420 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
301 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
421 strng)
302 strng)
422 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
303 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
423 strng = par_re.sub(r'\\\\',strng)
304 strng = par_re.sub(r'\\\\',strng)
424 strng = escape_re.sub(r'\\\1',strng)
305 strng = escape_re.sub(r'\\\1',strng)
425 strng = newline_re.sub(r'\\textbackslash{}n',strng)
306 strng = newline_re.sub(r'\\textbackslash{}n',strng)
426 return strng
307 return strng
427
308
428 def format_screen(self,strng):
309 def format_screen(self,strng):
429 """Format a string for screen printing.
310 """Format a string for screen printing.
430
311
431 This removes some latex-type format codes."""
312 This removes some latex-type format codes."""
432 # Paragraph continue
313 # Paragraph continue
433 par_re = re.compile(r'\\$',re.MULTILINE)
314 par_re = re.compile(r'\\$',re.MULTILINE)
434 strng = par_re.sub('',strng)
315 strng = par_re.sub('',strng)
435 return strng
316 return strng
436
317
437 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
318 def parse_options(self,arg_str,opt_str,*long_opts,**kw):
438 """Parse options passed to an argument string.
319 """Parse options passed to an argument string.
439
320
440 The interface is similar to that of getopt(), but it returns back a
321 The interface is similar to that of getopt(), but it returns back a
441 Struct with the options as keys and the stripped argument string still
322 Struct with the options as keys and the stripped argument string still
442 as a string.
323 as a string.
443
324
444 arg_str is quoted as a true sys.argv vector by using shlex.split.
325 arg_str is quoted as a true sys.argv vector by using shlex.split.
445 This allows us to easily expand variables, glob files, quote
326 This allows us to easily expand variables, glob files, quote
446 arguments, etc.
327 arguments, etc.
447
328
448 Options:
329 Options:
449 -mode: default 'string'. If given as 'list', the argument string is
330 -mode: default 'string'. If given as 'list', the argument string is
450 returned as a list (split on whitespace) instead of a string.
331 returned as a list (split on whitespace) instead of a string.
451
332
452 -list_all: put all option values in lists. Normally only options
333 -list_all: put all option values in lists. Normally only options
453 appearing more than once are put in a list.
334 appearing more than once are put in a list.
454
335
455 -posix (True): whether to split the input line in POSIX mode or not,
336 -posix (True): whether to split the input line in POSIX mode or not,
456 as per the conventions outlined in the shlex module from the
337 as per the conventions outlined in the shlex module from the
457 standard library."""
338 standard library."""
458
339
459 # inject default options at the beginning of the input line
340 # inject default options at the beginning of the input line
460 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
341 caller = sys._getframe(1).f_code.co_name.replace('magic_','')
461 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
342 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
462
343
463 mode = kw.get('mode','string')
344 mode = kw.get('mode','string')
464 if mode not in ['string','list']:
345 if mode not in ['string','list']:
465 raise ValueError,'incorrect mode given: %s' % mode
346 raise ValueError,'incorrect mode given: %s' % mode
466 # Get options
347 # Get options
467 list_all = kw.get('list_all',0)
348 list_all = kw.get('list_all',0)
468 posix = kw.get('posix',True)
349 posix = kw.get('posix',True)
469
350
470 # Check if we have more than one argument to warrant extra processing:
351 # Check if we have more than one argument to warrant extra processing:
471 odict = {} # Dictionary with options
352 odict = {} # Dictionary with options
472 args = arg_str.split()
353 args = arg_str.split()
473 if len(args) >= 1:
354 if len(args) >= 1:
474 # If the list of inputs only has 0 or 1 thing in it, there's no
355 # If the list of inputs only has 0 or 1 thing in it, there's no
475 # need to look for options
356 # need to look for options
476 argv = arg_split(arg_str,posix)
357 argv = arg_split(arg_str,posix)
477 # Do regular option processing
358 # Do regular option processing
478 try:
359 try:
479 opts,args = getopt(argv,opt_str,*long_opts)
360 opts,args = getopt(argv,opt_str,*long_opts)
480 except GetoptError,e:
361 except GetoptError,e:
481 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
362 raise UsageError('%s ( allowed: "%s" %s)' % (e.msg,opt_str,
482 " ".join(long_opts)))
363 " ".join(long_opts)))
483 for o,a in opts:
364 for o,a in opts:
484 if o.startswith('--'):
365 if o.startswith('--'):
485 o = o[2:]
366 o = o[2:]
486 else:
367 else:
487 o = o[1:]
368 o = o[1:]
488 try:
369 try:
489 odict[o].append(a)
370 odict[o].append(a)
490 except AttributeError:
371 except AttributeError:
491 odict[o] = [odict[o],a]
372 odict[o] = [odict[o],a]
492 except KeyError:
373 except KeyError:
493 if list_all:
374 if list_all:
494 odict[o] = [a]
375 odict[o] = [a]
495 else:
376 else:
496 odict[o] = a
377 odict[o] = a
497
378
498 # Prepare opts,args for return
379 # Prepare opts,args for return
499 opts = Struct(odict)
380 opts = Struct(odict)
500 if mode == 'string':
381 if mode == 'string':
501 args = ' '.join(args)
382 args = ' '.join(args)
502
383
503 return opts,args
384 return opts,args
504
385
505 #......................................................................
386 #......................................................................
506 # And now the actual magic functions
387 # And now the actual magic functions
507
388
508 # Functions for IPython shell work (vars,funcs, config, etc)
389 # Functions for IPython shell work (vars,funcs, config, etc)
509 def magic_lsmagic(self, parameter_s = ''):
390 def magic_lsmagic(self, parameter_s = ''):
510 """List currently available magic functions."""
391 """List currently available magic functions."""
511 mesc = ESC_MAGIC
392 mesc = ESC_MAGIC
512 print 'Available magic functions:\n'+mesc+\
393 print 'Available magic functions:\n'+mesc+\
513 (' '+mesc).join(self.lsmagic())
394 (' '+mesc).join(self.lsmagic())
514 print '\n' + Magic.auto_status[self.shell.automagic]
395 print '\n' + Magic.auto_status[self.shell.automagic]
515 return None
396 return None
516
397
517 def magic_magic(self, parameter_s = ''):
398 def magic_magic(self, parameter_s = ''):
518 """Print information about the magic function system.
399 """Print information about the magic function system.
519
400
520 Supported formats: -latex, -brief, -rest
401 Supported formats: -latex, -brief, -rest
521 """
402 """
522
403
523 mode = ''
404 mode = ''
524 try:
405 try:
525 if parameter_s.split()[0] == '-latex':
406 if parameter_s.split()[0] == '-latex':
526 mode = 'latex'
407 mode = 'latex'
527 if parameter_s.split()[0] == '-brief':
408 if parameter_s.split()[0] == '-brief':
528 mode = 'brief'
409 mode = 'brief'
529 if parameter_s.split()[0] == '-rest':
410 if parameter_s.split()[0] == '-rest':
530 mode = 'rest'
411 mode = 'rest'
531 rest_docs = []
412 rest_docs = []
532 except:
413 except:
533 pass
414 pass
534
415
535 magic_docs = []
416 magic_docs = []
536 for fname in self.lsmagic():
417 for fname in self.lsmagic():
537 mname = 'magic_' + fname
418 mname = 'magic_' + fname
538 for space in (Magic,self,self.__class__):
419 for space in (Magic,self,self.__class__):
539 try:
420 try:
540 fn = space.__dict__[mname]
421 fn = space.__dict__[mname]
541 except KeyError:
422 except KeyError:
542 pass
423 pass
543 else:
424 else:
544 break
425 break
545 if mode == 'brief':
426 if mode == 'brief':
546 # only first line
427 # only first line
547 if fn.__doc__:
428 if fn.__doc__:
548 fndoc = fn.__doc__.split('\n',1)[0]
429 fndoc = fn.__doc__.split('\n',1)[0]
549 else:
430 else:
550 fndoc = 'No documentation'
431 fndoc = 'No documentation'
551 else:
432 else:
552 if fn.__doc__:
433 if fn.__doc__:
553 fndoc = fn.__doc__.rstrip()
434 fndoc = fn.__doc__.rstrip()
554 else:
435 else:
555 fndoc = 'No documentation'
436 fndoc = 'No documentation'
556
437
557
438
558 if mode == 'rest':
439 if mode == 'rest':
559 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
440 rest_docs.append('**%s%s**::\n\n\t%s\n\n' %(ESC_MAGIC,
560 fname,fndoc))
441 fname,fndoc))
561
442
562 else:
443 else:
563 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
444 magic_docs.append('%s%s:\n\t%s\n' %(ESC_MAGIC,
564 fname,fndoc))
445 fname,fndoc))
565
446
566 magic_docs = ''.join(magic_docs)
447 magic_docs = ''.join(magic_docs)
567
448
568 if mode == 'rest':
449 if mode == 'rest':
569 return "".join(rest_docs)
450 return "".join(rest_docs)
570
451
571 if mode == 'latex':
452 if mode == 'latex':
572 print self.format_latex(magic_docs)
453 print self.format_latex(magic_docs)
573 return
454 return
574 else:
455 else:
575 magic_docs = self.format_screen(magic_docs)
456 magic_docs = self.format_screen(magic_docs)
576 if mode == 'brief':
457 if mode == 'brief':
577 return magic_docs
458 return magic_docs
578
459
579 outmsg = """
460 outmsg = """
580 IPython's 'magic' functions
461 IPython's 'magic' functions
581 ===========================
462 ===========================
582
463
583 The magic function system provides a series of functions which allow you to
464 The magic function system provides a series of functions which allow you to
584 control the behavior of IPython itself, plus a lot of system-type
465 control the behavior of IPython itself, plus a lot of system-type
585 features. All these functions are prefixed with a % character, but parameters
466 features. All these functions are prefixed with a % character, but parameters
586 are given without parentheses or quotes.
467 are given without parentheses or quotes.
587
468
588 NOTE: If you have 'automagic' enabled (via the command line option or with the
469 NOTE: If you have 'automagic' enabled (via the command line option or with the
589 %automagic function), you don't need to type in the % explicitly. By default,
470 %automagic function), you don't need to type in the % explicitly. By default,
590 IPython ships with automagic on, so you should only rarely need the % escape.
471 IPython ships with automagic on, so you should only rarely need the % escape.
591
472
592 Example: typing '%cd mydir' (without the quotes) changes you working directory
473 Example: typing '%cd mydir' (without the quotes) changes you working directory
593 to 'mydir', if it exists.
474 to 'mydir', if it exists.
594
475
595 You can define your own magic functions to extend the system. See the supplied
476 You can define your own magic functions to extend the system. See the supplied
596 ipythonrc and example-magic.py files for details (in your ipython
477 ipythonrc and example-magic.py files for details (in your ipython
597 configuration directory, typically $HOME/.ipython/).
478 configuration directory, typically $HOME/.ipython/).
598
479
599 You can also define your own aliased names for magic functions. In your
480 You can also define your own aliased names for magic functions. In your
600 ipythonrc file, placing a line like:
481 ipythonrc file, placing a line like:
601
482
602 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
483 execute __IPYTHON__.magic_pf = __IPYTHON__.magic_profile
603
484
604 will define %pf as a new name for %profile.
485 will define %pf as a new name for %profile.
605
486
606 You can also call magics in code using the magic() function, which IPython
487 You can also call magics in code using the magic() function, which IPython
607 automatically adds to the builtin namespace. Type 'magic?' for details.
488 automatically adds to the builtin namespace. Type 'magic?' for details.
608
489
609 For a list of the available magic functions, use %lsmagic. For a description
490 For a list of the available magic functions, use %lsmagic. For a description
610 of any of them, type %magic_name?, e.g. '%cd?'.
491 of any of them, type %magic_name?, e.g. '%cd?'.
611
492
612 Currently the magic system has the following functions:\n"""
493 Currently the magic system has the following functions:\n"""
613
494
614 mesc = ESC_MAGIC
495 mesc = ESC_MAGIC
615 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
496 outmsg = ("%s\n%s\n\nSummary of magic functions (from %slsmagic):"
616 "\n\n%s%s\n\n%s" % (outmsg,
497 "\n\n%s%s\n\n%s" % (outmsg,
617 magic_docs,mesc,mesc,
498 magic_docs,mesc,mesc,
618 (' '+mesc).join(self.lsmagic()),
499 (' '+mesc).join(self.lsmagic()),
619 Magic.auto_status[self.shell.automagic] ) )
500 Magic.auto_status[self.shell.automagic] ) )
620
501
621 page(outmsg,screen_lines=self.shell.usable_screen_length)
502 page(outmsg,screen_lines=self.shell.usable_screen_length)
622
503
623
504
624 def magic_autoindent(self, parameter_s = ''):
505 def magic_autoindent(self, parameter_s = ''):
625 """Toggle autoindent on/off (if available)."""
506 """Toggle autoindent on/off (if available)."""
626
507
627 self.shell.set_autoindent()
508 self.shell.set_autoindent()
628 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
509 print "Automatic indentation is:",['OFF','ON'][self.shell.autoindent]
629
510
630
511
631 def magic_automagic(self, parameter_s = ''):
512 def magic_automagic(self, parameter_s = ''):
632 """Make magic functions callable without having to type the initial %.
513 """Make magic functions callable without having to type the initial %.
633
514
634 Without argumentsl toggles on/off (when off, you must call it as
515 Without argumentsl toggles on/off (when off, you must call it as
635 %automagic, of course). With arguments it sets the value, and you can
516 %automagic, of course). With arguments it sets the value, and you can
636 use any of (case insensitive):
517 use any of (case insensitive):
637
518
638 - on,1,True: to activate
519 - on,1,True: to activate
639
520
640 - off,0,False: to deactivate.
521 - off,0,False: to deactivate.
641
522
642 Note that magic functions have lowest priority, so if there's a
523 Note that magic functions have lowest priority, so if there's a
643 variable whose name collides with that of a magic fn, automagic won't
524 variable whose name collides with that of a magic fn, automagic won't
644 work for that function (you get the variable instead). However, if you
525 work for that function (you get the variable instead). However, if you
645 delete the variable (del var), the previously shadowed magic function
526 delete the variable (del var), the previously shadowed magic function
646 becomes visible to automagic again."""
527 becomes visible to automagic again."""
647
528
648 arg = parameter_s.lower()
529 arg = parameter_s.lower()
649 if parameter_s in ('on','1','true'):
530 if parameter_s in ('on','1','true'):
650 self.shell.automagic = True
531 self.shell.automagic = True
651 elif parameter_s in ('off','0','false'):
532 elif parameter_s in ('off','0','false'):
652 self.shell.automagic = False
533 self.shell.automagic = False
653 else:
534 else:
654 self.shell.automagic = not self.shell.automagic
535 self.shell.automagic = not self.shell.automagic
655 print '\n' + Magic.auto_status[self.shell.automagic]
536 print '\n' + Magic.auto_status[self.shell.automagic]
656
537
657 @testdec.skip_doctest
538 @testdec.skip_doctest
658 def magic_autocall(self, parameter_s = ''):
539 def magic_autocall(self, parameter_s = ''):
659 """Make functions callable without having to type parentheses.
540 """Make functions callable without having to type parentheses.
660
541
661 Usage:
542 Usage:
662
543
663 %autocall [mode]
544 %autocall [mode]
664
545
665 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
546 The mode can be one of: 0->Off, 1->Smart, 2->Full. If not given, the
666 value is toggled on and off (remembering the previous state).
547 value is toggled on and off (remembering the previous state).
667
548
668 In more detail, these values mean:
549 In more detail, these values mean:
669
550
670 0 -> fully disabled
551 0 -> fully disabled
671
552
672 1 -> active, but do not apply if there are no arguments on the line.
553 1 -> active, but do not apply if there are no arguments on the line.
673
554
674 In this mode, you get:
555 In this mode, you get:
675
556
676 In [1]: callable
557 In [1]: callable
677 Out[1]: <built-in function callable>
558 Out[1]: <built-in function callable>
678
559
679 In [2]: callable 'hello'
560 In [2]: callable 'hello'
680 ------> callable('hello')
561 ------> callable('hello')
681 Out[2]: False
562 Out[2]: False
682
563
683 2 -> Active always. Even if no arguments are present, the callable
564 2 -> Active always. Even if no arguments are present, the callable
684 object is called:
565 object is called:
685
566
686 In [2]: float
567 In [2]: float
687 ------> float()
568 ------> float()
688 Out[2]: 0.0
569 Out[2]: 0.0
689
570
690 Note that even with autocall off, you can still use '/' at the start of
571 Note that even with autocall off, you can still use '/' at the start of
691 a line to treat the first argument on the command line as a function
572 a line to treat the first argument on the command line as a function
692 and add parentheses to it:
573 and add parentheses to it:
693
574
694 In [8]: /str 43
575 In [8]: /str 43
695 ------> str(43)
576 ------> str(43)
696 Out[8]: '43'
577 Out[8]: '43'
697
578
698 # all-random (note for auto-testing)
579 # all-random (note for auto-testing)
699 """
580 """
700
581
701 if parameter_s:
582 if parameter_s:
702 arg = int(parameter_s)
583 arg = int(parameter_s)
703 else:
584 else:
704 arg = 'toggle'
585 arg = 'toggle'
705
586
706 if not arg in (0,1,2,'toggle'):
587 if not arg in (0,1,2,'toggle'):
707 error('Valid modes: (0->Off, 1->Smart, 2->Full')
588 error('Valid modes: (0->Off, 1->Smart, 2->Full')
708 return
589 return
709
590
710 if arg in (0,1,2):
591 if arg in (0,1,2):
711 self.shell.autocall = arg
592 self.shell.autocall = arg
712 else: # toggle
593 else: # toggle
713 if self.shell.autocall:
594 if self.shell.autocall:
714 self._magic_state.autocall_save = self.shell.autocall
595 self._magic_state.autocall_save = self.shell.autocall
715 self.shell.autocall = 0
596 self.shell.autocall = 0
716 else:
597 else:
717 try:
598 try:
718 self.shell.autocall = self._magic_state.autocall_save
599 self.shell.autocall = self._magic_state.autocall_save
719 except AttributeError:
600 except AttributeError:
720 self.shell.autocall = self._magic_state.autocall_save = 1
601 self.shell.autocall = self._magic_state.autocall_save = 1
721
602
722 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
603 print "Automatic calling is:",['OFF','Smart','Full'][self.shell.autocall]
723
604
724 def magic_system_verbose(self, parameter_s = ''):
605 def magic_system_verbose(self, parameter_s = ''):
725 """Set verbose printing of system calls.
606 """Set verbose printing of system calls.
726
607
727 If called without an argument, act as a toggle"""
608 If called without an argument, act as a toggle"""
728
609
729 if parameter_s:
610 if parameter_s:
730 val = bool(eval(parameter_s))
611 val = bool(eval(parameter_s))
731 else:
612 else:
732 val = None
613 val = None
733
614
734 if self.shell.system_verbose:
615 if self.shell.system_verbose:
735 self.shell.system_verbose = False
616 self.shell.system_verbose = False
736 else:
617 else:
737 self.shell.system_verbose = True
618 self.shell.system_verbose = True
738 print "System verbose printing is:",\
619 print "System verbose printing is:",\
739 ['OFF','ON'][self.shell.system_verbose]
620 ['OFF','ON'][self.shell.system_verbose]
740
621
741
622
742 def magic_page(self, parameter_s=''):
623 def magic_page(self, parameter_s=''):
743 """Pretty print the object and display it through a pager.
624 """Pretty print the object and display it through a pager.
744
625
745 %page [options] OBJECT
626 %page [options] OBJECT
746
627
747 If no object is given, use _ (last output).
628 If no object is given, use _ (last output).
748
629
749 Options:
630 Options:
750
631
751 -r: page str(object), don't pretty-print it."""
632 -r: page str(object), don't pretty-print it."""
752
633
753 # After a function contributed by Olivier Aubert, slightly modified.
634 # After a function contributed by Olivier Aubert, slightly modified.
754
635
755 # Process options/args
636 # Process options/args
756 opts,args = self.parse_options(parameter_s,'r')
637 opts,args = self.parse_options(parameter_s,'r')
757 raw = 'r' in opts
638 raw = 'r' in opts
758
639
759 oname = args and args or '_'
640 oname = args and args or '_'
760 info = self._ofind(oname)
641 info = self._ofind(oname)
761 if info['found']:
642 if info['found']:
762 txt = (raw and str or pformat)( info['obj'] )
643 txt = (raw and str or pformat)( info['obj'] )
763 page(txt)
644 page(txt)
764 else:
645 else:
765 print 'Object `%s` not found' % oname
646 print 'Object `%s` not found' % oname
766
647
767 def magic_profile(self, parameter_s=''):
648 def magic_profile(self, parameter_s=''):
768 """Print your currently active IPyhton profile."""
649 """Print your currently active IPyhton profile."""
769 if self.shell.profile:
650 if self.shell.profile:
770 printpl('Current IPython profile: $self.shell.profile.')
651 printpl('Current IPython profile: $self.shell.profile.')
771 else:
652 else:
772 print 'No profile active.'
653 print 'No profile active.'
773
654
774 def magic_pinfo(self, parameter_s='', namespaces=None):
655 def magic_pinfo(self, parameter_s='', namespaces=None):
775 """Provide detailed information about an object.
656 """Provide detailed information about an object.
776
657
777 '%pinfo object' is just a synonym for object? or ?object."""
658 '%pinfo object' is just a synonym for object? or ?object."""
778
659
779 #print 'pinfo par: <%s>' % parameter_s # dbg
660 #print 'pinfo par: <%s>' % parameter_s # dbg
780
661
781
662
782 # detail_level: 0 -> obj? , 1 -> obj??
663 # detail_level: 0 -> obj? , 1 -> obj??
783 detail_level = 0
664 detail_level = 0
784 # We need to detect if we got called as 'pinfo pinfo foo', which can
665 # We need to detect if we got called as 'pinfo pinfo foo', which can
785 # happen if the user types 'pinfo foo?' at the cmd line.
666 # happen if the user types 'pinfo foo?' at the cmd line.
786 pinfo,qmark1,oname,qmark2 = \
667 pinfo,qmark1,oname,qmark2 = \
787 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
668 re.match('(pinfo )?(\?*)(.*?)(\??$)',parameter_s).groups()
788 if pinfo or qmark1 or qmark2:
669 if pinfo or qmark1 or qmark2:
789 detail_level = 1
670 detail_level = 1
790 if "*" in oname:
671 if "*" in oname:
791 self.magic_psearch(oname)
672 self.magic_psearch(oname)
792 else:
673 else:
793 self._inspect('pinfo', oname, detail_level=detail_level,
674 self._inspect('pinfo', oname, detail_level=detail_level,
794 namespaces=namespaces)
675 namespaces=namespaces)
795
676
796 def magic_pdef(self, parameter_s='', namespaces=None):
677 def magic_pdef(self, parameter_s='', namespaces=None):
797 """Print the definition header for any callable object.
678 """Print the definition header for any callable object.
798
679
799 If the object is a class, print the constructor information."""
680 If the object is a class, print the constructor information."""
800 self._inspect('pdef',parameter_s, namespaces)
681 self._inspect('pdef',parameter_s, namespaces)
801
682
802 def magic_pdoc(self, parameter_s='', namespaces=None):
683 def magic_pdoc(self, parameter_s='', namespaces=None):
803 """Print the docstring for an object.
684 """Print the docstring for an object.
804
685
805 If the given object is a class, it will print both the class and the
686 If the given object is a class, it will print both the class and the
806 constructor docstrings."""
687 constructor docstrings."""
807 self._inspect('pdoc',parameter_s, namespaces)
688 self._inspect('pdoc',parameter_s, namespaces)
808
689
809 def magic_psource(self, parameter_s='', namespaces=None):
690 def magic_psource(self, parameter_s='', namespaces=None):
810 """Print (or run through pager) the source code for an object."""
691 """Print (or run through pager) the source code for an object."""
811 self._inspect('psource',parameter_s, namespaces)
692 self._inspect('psource',parameter_s, namespaces)
812
693
813 def magic_pfile(self, parameter_s=''):
694 def magic_pfile(self, parameter_s=''):
814 """Print (or run through pager) the file where an object is defined.
695 """Print (or run through pager) the file where an object is defined.
815
696
816 The file opens at the line where the object definition begins. IPython
697 The file opens at the line where the object definition begins. IPython
817 will honor the environment variable PAGER if set, and otherwise will
698 will honor the environment variable PAGER if set, and otherwise will
818 do its best to print the file in a convenient form.
699 do its best to print the file in a convenient form.
819
700
820 If the given argument is not an object currently defined, IPython will
701 If the given argument is not an object currently defined, IPython will
821 try to interpret it as a filename (automatically adding a .py extension
702 try to interpret it as a filename (automatically adding a .py extension
822 if needed). You can thus use %pfile as a syntax highlighting code
703 if needed). You can thus use %pfile as a syntax highlighting code
823 viewer."""
704 viewer."""
824
705
825 # first interpret argument as an object name
706 # first interpret argument as an object name
826 out = self._inspect('pfile',parameter_s)
707 out = self._inspect('pfile',parameter_s)
827 # if not, try the input as a filename
708 # if not, try the input as a filename
828 if out == 'not found':
709 if out == 'not found':
829 try:
710 try:
830 filename = get_py_filename(parameter_s)
711 filename = get_py_filename(parameter_s)
831 except IOError,msg:
712 except IOError,msg:
832 print msg
713 print msg
833 return
714 return
834 page(self.shell.inspector.format(file(filename).read()))
715 page(self.shell.inspector.format(file(filename).read()))
835
716
836 def _inspect(self,meth,oname,namespaces=None,**kw):
717 def _inspect(self,meth,oname,namespaces=None,**kw):
837 """Generic interface to the inspector system.
718 """Generic interface to the inspector system.
838
719
839 This function is meant to be called by pdef, pdoc & friends."""
720 This function is meant to be called by pdef, pdoc & friends."""
840
721
841 #oname = oname.strip()
722 #oname = oname.strip()
842 #print '1- oname: <%r>' % oname # dbg
723 #print '1- oname: <%r>' % oname # dbg
843 try:
724 try:
844 oname = oname.strip().encode('ascii')
725 oname = oname.strip().encode('ascii')
845 #print '2- oname: <%r>' % oname # dbg
726 #print '2- oname: <%r>' % oname # dbg
846 except UnicodeEncodeError:
727 except UnicodeEncodeError:
847 print 'Python identifiers can only contain ascii characters.'
728 print 'Python identifiers can only contain ascii characters.'
848 return 'not found'
729 return 'not found'
849
730
850 info = Struct(self._ofind(oname, namespaces))
731 info = Struct(self._ofind(oname, namespaces))
851
732
852 if info.found:
733 if info.found:
853 try:
734 try:
854 IPython.utils.generics.inspect_object(info.obj)
735 IPython.utils.generics.inspect_object(info.obj)
855 return
736 return
856 except TryNext:
737 except TryNext:
857 pass
738 pass
858 # Get the docstring of the class property if it exists.
739 # Get the docstring of the class property if it exists.
859 path = oname.split('.')
740 path = oname.split('.')
860 root = '.'.join(path[:-1])
741 root = '.'.join(path[:-1])
861 if info.parent is not None:
742 if info.parent is not None:
862 try:
743 try:
863 target = getattr(info.parent, '__class__')
744 target = getattr(info.parent, '__class__')
864 # The object belongs to a class instance.
745 # The object belongs to a class instance.
865 try:
746 try:
866 target = getattr(target, path[-1])
747 target = getattr(target, path[-1])
867 # The class defines the object.
748 # The class defines the object.
868 if isinstance(target, property):
749 if isinstance(target, property):
869 oname = root + '.__class__.' + path[-1]
750 oname = root + '.__class__.' + path[-1]
870 info = Struct(self._ofind(oname))
751 info = Struct(self._ofind(oname))
871 except AttributeError: pass
752 except AttributeError: pass
872 except AttributeError: pass
753 except AttributeError: pass
873
754
874 pmethod = getattr(self.shell.inspector,meth)
755 pmethod = getattr(self.shell.inspector,meth)
875 formatter = info.ismagic and self.format_screen or None
756 formatter = info.ismagic and self.format_screen or None
876 if meth == 'pdoc':
757 if meth == 'pdoc':
877 pmethod(info.obj,oname,formatter)
758 pmethod(info.obj,oname,formatter)
878 elif meth == 'pinfo':
759 elif meth == 'pinfo':
879 pmethod(info.obj,oname,formatter,info,**kw)
760 pmethod(info.obj,oname,formatter,info,**kw)
880 else:
761 else:
881 pmethod(info.obj,oname)
762 pmethod(info.obj,oname)
882 else:
763 else:
883 print 'Object `%s` not found.' % oname
764 print 'Object `%s` not found.' % oname
884 return 'not found' # so callers can take other action
765 return 'not found' # so callers can take other action
885
766
886 def magic_psearch(self, parameter_s=''):
767 def magic_psearch(self, parameter_s=''):
887 """Search for object in namespaces by wildcard.
768 """Search for object in namespaces by wildcard.
888
769
889 %psearch [options] PATTERN [OBJECT TYPE]
770 %psearch [options] PATTERN [OBJECT TYPE]
890
771
891 Note: ? can be used as a synonym for %psearch, at the beginning or at
772 Note: ? can be used as a synonym for %psearch, at the beginning or at
892 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
773 the end: both a*? and ?a* are equivalent to '%psearch a*'. Still, the
893 rest of the command line must be unchanged (options come first), so
774 rest of the command line must be unchanged (options come first), so
894 for example the following forms are equivalent
775 for example the following forms are equivalent
895
776
896 %psearch -i a* function
777 %psearch -i a* function
897 -i a* function?
778 -i a* function?
898 ?-i a* function
779 ?-i a* function
899
780
900 Arguments:
781 Arguments:
901
782
902 PATTERN
783 PATTERN
903
784
904 where PATTERN is a string containing * as a wildcard similar to its
785 where PATTERN is a string containing * as a wildcard similar to its
905 use in a shell. The pattern is matched in all namespaces on the
786 use in a shell. The pattern is matched in all namespaces on the
906 search path. By default objects starting with a single _ are not
787 search path. By default objects starting with a single _ are not
907 matched, many IPython generated objects have a single
788 matched, many IPython generated objects have a single
908 underscore. The default is case insensitive matching. Matching is
789 underscore. The default is case insensitive matching. Matching is
909 also done on the attributes of objects and not only on the objects
790 also done on the attributes of objects and not only on the objects
910 in a module.
791 in a module.
911
792
912 [OBJECT TYPE]
793 [OBJECT TYPE]
913
794
914 Is the name of a python type from the types module. The name is
795 Is the name of a python type from the types module. The name is
915 given in lowercase without the ending type, ex. StringType is
796 given in lowercase without the ending type, ex. StringType is
916 written string. By adding a type here only objects matching the
797 written string. By adding a type here only objects matching the
917 given type are matched. Using all here makes the pattern match all
798 given type are matched. Using all here makes the pattern match all
918 types (this is the default).
799 types (this is the default).
919
800
920 Options:
801 Options:
921
802
922 -a: makes the pattern match even objects whose names start with a
803 -a: makes the pattern match even objects whose names start with a
923 single underscore. These names are normally ommitted from the
804 single underscore. These names are normally ommitted from the
924 search.
805 search.
925
806
926 -i/-c: make the pattern case insensitive/sensitive. If neither of
807 -i/-c: make the pattern case insensitive/sensitive. If neither of
927 these options is given, the default is read from your ipythonrc
808 these options is given, the default is read from your ipythonrc
928 file. The option name which sets this value is
809 file. The option name which sets this value is
929 'wildcards_case_sensitive'. If this option is not specified in your
810 'wildcards_case_sensitive'. If this option is not specified in your
930 ipythonrc file, IPython's internal default is to do a case sensitive
811 ipythonrc file, IPython's internal default is to do a case sensitive
931 search.
812 search.
932
813
933 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
814 -e/-s NAMESPACE: exclude/search a given namespace. The pattern you
934 specifiy can be searched in any of the following namespaces:
815 specifiy can be searched in any of the following namespaces:
935 'builtin', 'user', 'user_global','internal', 'alias', where
816 'builtin', 'user', 'user_global','internal', 'alias', where
936 'builtin' and 'user' are the search defaults. Note that you should
817 'builtin' and 'user' are the search defaults. Note that you should
937 not use quotes when specifying namespaces.
818 not use quotes when specifying namespaces.
938
819
939 'Builtin' contains the python module builtin, 'user' contains all
820 'Builtin' contains the python module builtin, 'user' contains all
940 user data, 'alias' only contain the shell aliases and no python
821 user data, 'alias' only contain the shell aliases and no python
941 objects, 'internal' contains objects used by IPython. The
822 objects, 'internal' contains objects used by IPython. The
942 'user_global' namespace is only used by embedded IPython instances,
823 'user_global' namespace is only used by embedded IPython instances,
943 and it contains module-level globals. You can add namespaces to the
824 and it contains module-level globals. You can add namespaces to the
944 search with -s or exclude them with -e (these options can be given
825 search with -s or exclude them with -e (these options can be given
945 more than once).
826 more than once).
946
827
947 Examples:
828 Examples:
948
829
949 %psearch a* -> objects beginning with an a
830 %psearch a* -> objects beginning with an a
950 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
831 %psearch -e builtin a* -> objects NOT in the builtin space starting in a
951 %psearch a* function -> all functions beginning with an a
832 %psearch a* function -> all functions beginning with an a
952 %psearch re.e* -> objects beginning with an e in module re
833 %psearch re.e* -> objects beginning with an e in module re
953 %psearch r*.e* -> objects that start with e in modules starting in r
834 %psearch r*.e* -> objects that start with e in modules starting in r
954 %psearch r*.* string -> all strings in modules beginning with r
835 %psearch r*.* string -> all strings in modules beginning with r
955
836
956 Case sensitve search:
837 Case sensitve search:
957
838
958 %psearch -c a* list all object beginning with lower case a
839 %psearch -c a* list all object beginning with lower case a
959
840
960 Show objects beginning with a single _:
841 Show objects beginning with a single _:
961
842
962 %psearch -a _* list objects beginning with a single underscore"""
843 %psearch -a _* list objects beginning with a single underscore"""
963 try:
844 try:
964 parameter_s = parameter_s.encode('ascii')
845 parameter_s = parameter_s.encode('ascii')
965 except UnicodeEncodeError:
846 except UnicodeEncodeError:
966 print 'Python identifiers can only contain ascii characters.'
847 print 'Python identifiers can only contain ascii characters.'
967 return
848 return
968
849
969 # default namespaces to be searched
850 # default namespaces to be searched
970 def_search = ['user','builtin']
851 def_search = ['user','builtin']
971
852
972 # Process options/args
853 # Process options/args
973 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
854 opts,args = self.parse_options(parameter_s,'cias:e:',list_all=True)
974 opt = opts.get
855 opt = opts.get
975 shell = self.shell
856 shell = self.shell
976 psearch = shell.inspector.psearch
857 psearch = shell.inspector.psearch
977
858
978 # select case options
859 # select case options
979 if opts.has_key('i'):
860 if opts.has_key('i'):
980 ignore_case = True
861 ignore_case = True
981 elif opts.has_key('c'):
862 elif opts.has_key('c'):
982 ignore_case = False
863 ignore_case = False
983 else:
864 else:
984 ignore_case = not shell.wildcards_case_sensitive
865 ignore_case = not shell.wildcards_case_sensitive
985
866
986 # Build list of namespaces to search from user options
867 # Build list of namespaces to search from user options
987 def_search.extend(opt('s',[]))
868 def_search.extend(opt('s',[]))
988 ns_exclude = ns_exclude=opt('e',[])
869 ns_exclude = ns_exclude=opt('e',[])
989 ns_search = [nm for nm in def_search if nm not in ns_exclude]
870 ns_search = [nm for nm in def_search if nm not in ns_exclude]
990
871
991 # Call the actual search
872 # Call the actual search
992 try:
873 try:
993 psearch(args,shell.ns_table,ns_search,
874 psearch(args,shell.ns_table,ns_search,
994 show_all=opt('a'),ignore_case=ignore_case)
875 show_all=opt('a'),ignore_case=ignore_case)
995 except:
876 except:
996 shell.showtraceback()
877 shell.showtraceback()
997
878
998 def magic_who_ls(self, parameter_s=''):
879 def magic_who_ls(self, parameter_s=''):
999 """Return a sorted list of all interactive variables.
880 """Return a sorted list of all interactive variables.
1000
881
1001 If arguments are given, only variables of types matching these
882 If arguments are given, only variables of types matching these
1002 arguments are returned."""
883 arguments are returned."""
1003
884
1004 user_ns = self.shell.user_ns
885 user_ns = self.shell.user_ns
1005 internal_ns = self.shell.internal_ns
886 internal_ns = self.shell.internal_ns
1006 user_config_ns = self.shell.user_config_ns
887 user_config_ns = self.shell.user_config_ns
1007 out = []
888 out = []
1008 typelist = parameter_s.split()
889 typelist = parameter_s.split()
1009
890
1010 for i in user_ns:
891 for i in user_ns:
1011 if not (i.startswith('_') or i.startswith('_i')) \
892 if not (i.startswith('_') or i.startswith('_i')) \
1012 and not (i in internal_ns or i in user_config_ns):
893 and not (i in internal_ns or i in user_config_ns):
1013 if typelist:
894 if typelist:
1014 if type(user_ns[i]).__name__ in typelist:
895 if type(user_ns[i]).__name__ in typelist:
1015 out.append(i)
896 out.append(i)
1016 else:
897 else:
1017 out.append(i)
898 out.append(i)
1018 out.sort()
899 out.sort()
1019 return out
900 return out
1020
901
1021 def magic_who(self, parameter_s=''):
902 def magic_who(self, parameter_s=''):
1022 """Print all interactive variables, with some minimal formatting.
903 """Print all interactive variables, with some minimal formatting.
1023
904
1024 If any arguments are given, only variables whose type matches one of
905 If any arguments are given, only variables whose type matches one of
1025 these are printed. For example:
906 these are printed. For example:
1026
907
1027 %who function str
908 %who function str
1028
909
1029 will only list functions and strings, excluding all other types of
910 will only list functions and strings, excluding all other types of
1030 variables. To find the proper type names, simply use type(var) at a
911 variables. To find the proper type names, simply use type(var) at a
1031 command line to see how python prints type names. For example:
912 command line to see how python prints type names. For example:
1032
913
1033 In [1]: type('hello')\\
914 In [1]: type('hello')\\
1034 Out[1]: <type 'str'>
915 Out[1]: <type 'str'>
1035
916
1036 indicates that the type name for strings is 'str'.
917 indicates that the type name for strings is 'str'.
1037
918
1038 %who always excludes executed names loaded through your configuration
919 %who always excludes executed names loaded through your configuration
1039 file and things which are internal to IPython.
920 file and things which are internal to IPython.
1040
921
1041 This is deliberate, as typically you may load many modules and the
922 This is deliberate, as typically you may load many modules and the
1042 purpose of %who is to show you only what you've manually defined."""
923 purpose of %who is to show you only what you've manually defined."""
1043
924
1044 varlist = self.magic_who_ls(parameter_s)
925 varlist = self.magic_who_ls(parameter_s)
1045 if not varlist:
926 if not varlist:
1046 if parameter_s:
927 if parameter_s:
1047 print 'No variables match your requested type.'
928 print 'No variables match your requested type.'
1048 else:
929 else:
1049 print 'Interactive namespace is empty.'
930 print 'Interactive namespace is empty.'
1050 return
931 return
1051
932
1052 # if we have variables, move on...
933 # if we have variables, move on...
1053 count = 0
934 count = 0
1054 for i in varlist:
935 for i in varlist:
1055 print i+'\t',
936 print i+'\t',
1056 count += 1
937 count += 1
1057 if count > 8:
938 if count > 8:
1058 count = 0
939 count = 0
1059 print
940 print
1060 print
941 print
1061
942
1062 def magic_whos(self, parameter_s=''):
943 def magic_whos(self, parameter_s=''):
1063 """Like %who, but gives some extra information about each variable.
944 """Like %who, but gives some extra information about each variable.
1064
945
1065 The same type filtering of %who can be applied here.
946 The same type filtering of %who can be applied here.
1066
947
1067 For all variables, the type is printed. Additionally it prints:
948 For all variables, the type is printed. Additionally it prints:
1068
949
1069 - For {},[],(): their length.
950 - For {},[],(): their length.
1070
951
1071 - For numpy and Numeric arrays, a summary with shape, number of
952 - For numpy and Numeric arrays, a summary with shape, number of
1072 elements, typecode and size in memory.
953 elements, typecode and size in memory.
1073
954
1074 - Everything else: a string representation, snipping their middle if
955 - Everything else: a string representation, snipping their middle if
1075 too long."""
956 too long."""
1076
957
1077 varnames = self.magic_who_ls(parameter_s)
958 varnames = self.magic_who_ls(parameter_s)
1078 if not varnames:
959 if not varnames:
1079 if parameter_s:
960 if parameter_s:
1080 print 'No variables match your requested type.'
961 print 'No variables match your requested type.'
1081 else:
962 else:
1082 print 'Interactive namespace is empty.'
963 print 'Interactive namespace is empty.'
1083 return
964 return
1084
965
1085 # if we have variables, move on...
966 # if we have variables, move on...
1086
967
1087 # for these types, show len() instead of data:
968 # for these types, show len() instead of data:
1088 seq_types = [types.DictType,types.ListType,types.TupleType]
969 seq_types = [types.DictType,types.ListType,types.TupleType]
1089
970
1090 # for numpy/Numeric arrays, display summary info
971 # for numpy/Numeric arrays, display summary info
1091 try:
972 try:
1092 import numpy
973 import numpy
1093 except ImportError:
974 except ImportError:
1094 ndarray_type = None
975 ndarray_type = None
1095 else:
976 else:
1096 ndarray_type = numpy.ndarray.__name__
977 ndarray_type = numpy.ndarray.__name__
1097 try:
978 try:
1098 import Numeric
979 import Numeric
1099 except ImportError:
980 except ImportError:
1100 array_type = None
981 array_type = None
1101 else:
982 else:
1102 array_type = Numeric.ArrayType.__name__
983 array_type = Numeric.ArrayType.__name__
1103
984
1104 # Find all variable names and types so we can figure out column sizes
985 # Find all variable names and types so we can figure out column sizes
1105 def get_vars(i):
986 def get_vars(i):
1106 return self.shell.user_ns[i]
987 return self.shell.user_ns[i]
1107
988
1108 # some types are well known and can be shorter
989 # some types are well known and can be shorter
1109 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
990 abbrevs = {'IPython.core.macro.Macro' : 'Macro'}
1110 def type_name(v):
991 def type_name(v):
1111 tn = type(v).__name__
992 tn = type(v).__name__
1112 return abbrevs.get(tn,tn)
993 return abbrevs.get(tn,tn)
1113
994
1114 varlist = map(get_vars,varnames)
995 varlist = map(get_vars,varnames)
1115
996
1116 typelist = []
997 typelist = []
1117 for vv in varlist:
998 for vv in varlist:
1118 tt = type_name(vv)
999 tt = type_name(vv)
1119
1000
1120 if tt=='instance':
1001 if tt=='instance':
1121 typelist.append( abbrevs.get(str(vv.__class__),
1002 typelist.append( abbrevs.get(str(vv.__class__),
1122 str(vv.__class__)))
1003 str(vv.__class__)))
1123 else:
1004 else:
1124 typelist.append(tt)
1005 typelist.append(tt)
1125
1006
1126 # column labels and # of spaces as separator
1007 # column labels and # of spaces as separator
1127 varlabel = 'Variable'
1008 varlabel = 'Variable'
1128 typelabel = 'Type'
1009 typelabel = 'Type'
1129 datalabel = 'Data/Info'
1010 datalabel = 'Data/Info'
1130 colsep = 3
1011 colsep = 3
1131 # variable format strings
1012 # variable format strings
1132 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1013 vformat = "$vname.ljust(varwidth)$vtype.ljust(typewidth)"
1133 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1014 vfmt_short = '$vstr[:25]<...>$vstr[-25:]'
1134 aformat = "%s: %s elems, type `%s`, %s bytes"
1015 aformat = "%s: %s elems, type `%s`, %s bytes"
1135 # find the size of the columns to format the output nicely
1016 # find the size of the columns to format the output nicely
1136 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1017 varwidth = max(max(map(len,varnames)), len(varlabel)) + colsep
1137 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1018 typewidth = max(max(map(len,typelist)), len(typelabel)) + colsep
1138 # table header
1019 # table header
1139 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1020 print varlabel.ljust(varwidth) + typelabel.ljust(typewidth) + \
1140 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1021 ' '+datalabel+'\n' + '-'*(varwidth+typewidth+len(datalabel)+1)
1141 # and the table itself
1022 # and the table itself
1142 kb = 1024
1023 kb = 1024
1143 Mb = 1048576 # kb**2
1024 Mb = 1048576 # kb**2
1144 for vname,var,vtype in zip(varnames,varlist,typelist):
1025 for vname,var,vtype in zip(varnames,varlist,typelist):
1145 print itpl(vformat),
1026 print itpl(vformat),
1146 if vtype in seq_types:
1027 if vtype in seq_types:
1147 print len(var)
1028 print len(var)
1148 elif vtype in [array_type,ndarray_type]:
1029 elif vtype in [array_type,ndarray_type]:
1149 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1030 vshape = str(var.shape).replace(',','').replace(' ','x')[1:-1]
1150 if vtype==ndarray_type:
1031 if vtype==ndarray_type:
1151 # numpy
1032 # numpy
1152 vsize = var.size
1033 vsize = var.size
1153 vbytes = vsize*var.itemsize
1034 vbytes = vsize*var.itemsize
1154 vdtype = var.dtype
1035 vdtype = var.dtype
1155 else:
1036 else:
1156 # Numeric
1037 # Numeric
1157 vsize = Numeric.size(var)
1038 vsize = Numeric.size(var)
1158 vbytes = vsize*var.itemsize()
1039 vbytes = vsize*var.itemsize()
1159 vdtype = var.typecode()
1040 vdtype = var.typecode()
1160
1041
1161 if vbytes < 100000:
1042 if vbytes < 100000:
1162 print aformat % (vshape,vsize,vdtype,vbytes)
1043 print aformat % (vshape,vsize,vdtype,vbytes)
1163 else:
1044 else:
1164 print aformat % (vshape,vsize,vdtype,vbytes),
1045 print aformat % (vshape,vsize,vdtype,vbytes),
1165 if vbytes < Mb:
1046 if vbytes < Mb:
1166 print '(%s kb)' % (vbytes/kb,)
1047 print '(%s kb)' % (vbytes/kb,)
1167 else:
1048 else:
1168 print '(%s Mb)' % (vbytes/Mb,)
1049 print '(%s Mb)' % (vbytes/Mb,)
1169 else:
1050 else:
1170 try:
1051 try:
1171 vstr = str(var)
1052 vstr = str(var)
1172 except UnicodeEncodeError:
1053 except UnicodeEncodeError:
1173 vstr = unicode(var).encode(sys.getdefaultencoding(),
1054 vstr = unicode(var).encode(sys.getdefaultencoding(),
1174 'backslashreplace')
1055 'backslashreplace')
1175 vstr = vstr.replace('\n','\\n')
1056 vstr = vstr.replace('\n','\\n')
1176 if len(vstr) < 50:
1057 if len(vstr) < 50:
1177 print vstr
1058 print vstr
1178 else:
1059 else:
1179 printpl(vfmt_short)
1060 printpl(vfmt_short)
1180
1061
1181 def magic_reset(self, parameter_s=''):
1062 def magic_reset(self, parameter_s=''):
1182 """Resets the namespace by removing all names defined by the user.
1063 """Resets the namespace by removing all names defined by the user.
1183
1064
1184 Input/Output history are left around in case you need them.
1065 Input/Output history are left around in case you need them.
1185
1066
1186 Parameters
1067 Parameters
1187 ----------
1068 ----------
1188 -y : force reset without asking for confirmation.
1069 -y : force reset without asking for confirmation.
1189
1070
1190 Examples
1071 Examples
1191 --------
1072 --------
1192 In [6]: a = 1
1073 In [6]: a = 1
1193
1074
1194 In [7]: a
1075 In [7]: a
1195 Out[7]: 1
1076 Out[7]: 1
1196
1077
1197 In [8]: 'a' in _ip.user_ns
1078 In [8]: 'a' in _ip.user_ns
1198 Out[8]: True
1079 Out[8]: True
1199
1080
1200 In [9]: %reset -f
1081 In [9]: %reset -f
1201
1082
1202 In [10]: 'a' in _ip.user_ns
1083 In [10]: 'a' in _ip.user_ns
1203 Out[10]: False
1084 Out[10]: False
1204 """
1085 """
1205
1086
1206 if parameter_s == '-f':
1087 if parameter_s == '-f':
1207 ans = True
1088 ans = True
1208 else:
1089 else:
1209 ans = self.shell.ask_yes_no(
1090 ans = self.shell.ask_yes_no(
1210 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1091 "Once deleted, variables cannot be recovered. Proceed (y/[n])? ")
1211 if not ans:
1092 if not ans:
1212 print 'Nothing done.'
1093 print 'Nothing done.'
1213 return
1094 return
1214 user_ns = self.shell.user_ns
1095 user_ns = self.shell.user_ns
1215 for i in self.magic_who_ls():
1096 for i in self.magic_who_ls():
1216 del(user_ns[i])
1097 del(user_ns[i])
1217
1098
1218 # Also flush the private list of module references kept for script
1099 # Also flush the private list of module references kept for script
1219 # execution protection
1100 # execution protection
1220 self.shell.clear_main_mod_cache()
1101 self.shell.clear_main_mod_cache()
1221
1102
1222 def magic_logstart(self,parameter_s=''):
1103 def magic_logstart(self,parameter_s=''):
1223 """Start logging anywhere in a session.
1104 """Start logging anywhere in a session.
1224
1105
1225 %logstart [-o|-r|-t] [log_name [log_mode]]
1106 %logstart [-o|-r|-t] [log_name [log_mode]]
1226
1107
1227 If no name is given, it defaults to a file named 'ipython_log.py' in your
1108 If no name is given, it defaults to a file named 'ipython_log.py' in your
1228 current directory, in 'rotate' mode (see below).
1109 current directory, in 'rotate' mode (see below).
1229
1110
1230 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1111 '%logstart name' saves to file 'name' in 'backup' mode. It saves your
1231 history up to that point and then continues logging.
1112 history up to that point and then continues logging.
1232
1113
1233 %logstart takes a second optional parameter: logging mode. This can be one
1114 %logstart takes a second optional parameter: logging mode. This can be one
1234 of (note that the modes are given unquoted):\\
1115 of (note that the modes are given unquoted):\\
1235 append: well, that says it.\\
1116 append: well, that says it.\\
1236 backup: rename (if exists) to name~ and start name.\\
1117 backup: rename (if exists) to name~ and start name.\\
1237 global: single logfile in your home dir, appended to.\\
1118 global: single logfile in your home dir, appended to.\\
1238 over : overwrite existing log.\\
1119 over : overwrite existing log.\\
1239 rotate: create rotating logs name.1~, name.2~, etc.
1120 rotate: create rotating logs name.1~, name.2~, etc.
1240
1121
1241 Options:
1122 Options:
1242
1123
1243 -o: log also IPython's output. In this mode, all commands which
1124 -o: log also IPython's output. In this mode, all commands which
1244 generate an Out[NN] prompt are recorded to the logfile, right after
1125 generate an Out[NN] prompt are recorded to the logfile, right after
1245 their corresponding input line. The output lines are always
1126 their corresponding input line. The output lines are always
1246 prepended with a '#[Out]# ' marker, so that the log remains valid
1127 prepended with a '#[Out]# ' marker, so that the log remains valid
1247 Python code.
1128 Python code.
1248
1129
1249 Since this marker is always the same, filtering only the output from
1130 Since this marker is always the same, filtering only the output from
1250 a log is very easy, using for example a simple awk call:
1131 a log is very easy, using for example a simple awk call:
1251
1132
1252 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1133 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
1253
1134
1254 -r: log 'raw' input. Normally, IPython's logs contain the processed
1135 -r: log 'raw' input. Normally, IPython's logs contain the processed
1255 input, so that user lines are logged in their final form, converted
1136 input, so that user lines are logged in their final form, converted
1256 into valid Python. For example, %Exit is logged as
1137 into valid Python. For example, %Exit is logged as
1257 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1138 '_ip.magic("Exit"). If the -r flag is given, all input is logged
1258 exactly as typed, with no transformations applied.
1139 exactly as typed, with no transformations applied.
1259
1140
1260 -t: put timestamps before each input line logged (these are put in
1141 -t: put timestamps before each input line logged (these are put in
1261 comments)."""
1142 comments)."""
1262
1143
1263 opts,par = self.parse_options(parameter_s,'ort')
1144 opts,par = self.parse_options(parameter_s,'ort')
1264 log_output = 'o' in opts
1145 log_output = 'o' in opts
1265 log_raw_input = 'r' in opts
1146 log_raw_input = 'r' in opts
1266 timestamp = 't' in opts
1147 timestamp = 't' in opts
1267
1148
1268 logger = self.shell.logger
1149 logger = self.shell.logger
1269
1150
1270 # if no args are given, the defaults set in the logger constructor by
1151 # if no args are given, the defaults set in the logger constructor by
1271 # ipytohn remain valid
1152 # ipytohn remain valid
1272 if par:
1153 if par:
1273 try:
1154 try:
1274 logfname,logmode = par.split()
1155 logfname,logmode = par.split()
1275 except:
1156 except:
1276 logfname = par
1157 logfname = par
1277 logmode = 'backup'
1158 logmode = 'backup'
1278 else:
1159 else:
1279 logfname = logger.logfname
1160 logfname = logger.logfname
1280 logmode = logger.logmode
1161 logmode = logger.logmode
1281 # put logfname into rc struct as if it had been called on the command
1162 # put logfname into rc struct as if it had been called on the command
1282 # line, so it ends up saved in the log header Save it in case we need
1163 # line, so it ends up saved in the log header Save it in case we need
1283 # to restore it...
1164 # to restore it...
1284 old_logfile = self.shell.logfile
1165 old_logfile = self.shell.logfile
1285 if logfname:
1166 if logfname:
1286 logfname = os.path.expanduser(logfname)
1167 logfname = os.path.expanduser(logfname)
1287 self.shell.logfile = logfname
1168 self.shell.logfile = logfname
1288
1169
1289 loghead = '# IPython log file\n\n'
1170 loghead = '# IPython log file\n\n'
1290 try:
1171 try:
1291 started = logger.logstart(logfname,loghead,logmode,
1172 started = logger.logstart(logfname,loghead,logmode,
1292 log_output,timestamp,log_raw_input)
1173 log_output,timestamp,log_raw_input)
1293 except:
1174 except:
1294 rc.opts.logfile = old_logfile
1175 rc.opts.logfile = old_logfile
1295 warn("Couldn't start log: %s" % sys.exc_info()[1])
1176 warn("Couldn't start log: %s" % sys.exc_info()[1])
1296 else:
1177 else:
1297 # log input history up to this point, optionally interleaving
1178 # log input history up to this point, optionally interleaving
1298 # output if requested
1179 # output if requested
1299
1180
1300 if timestamp:
1181 if timestamp:
1301 # disable timestamping for the previous history, since we've
1182 # disable timestamping for the previous history, since we've
1302 # lost those already (no time machine here).
1183 # lost those already (no time machine here).
1303 logger.timestamp = False
1184 logger.timestamp = False
1304
1185
1305 if log_raw_input:
1186 if log_raw_input:
1306 input_hist = self.shell.input_hist_raw
1187 input_hist = self.shell.input_hist_raw
1307 else:
1188 else:
1308 input_hist = self.shell.input_hist
1189 input_hist = self.shell.input_hist
1309
1190
1310 if log_output:
1191 if log_output:
1311 log_write = logger.log_write
1192 log_write = logger.log_write
1312 output_hist = self.shell.output_hist
1193 output_hist = self.shell.output_hist
1313 for n in range(1,len(input_hist)-1):
1194 for n in range(1,len(input_hist)-1):
1314 log_write(input_hist[n].rstrip())
1195 log_write(input_hist[n].rstrip())
1315 if n in output_hist:
1196 if n in output_hist:
1316 log_write(repr(output_hist[n]),'output')
1197 log_write(repr(output_hist[n]),'output')
1317 else:
1198 else:
1318 logger.log_write(input_hist[1:])
1199 logger.log_write(input_hist[1:])
1319 if timestamp:
1200 if timestamp:
1320 # re-enable timestamping
1201 # re-enable timestamping
1321 logger.timestamp = True
1202 logger.timestamp = True
1322
1203
1323 print ('Activating auto-logging. '
1204 print ('Activating auto-logging. '
1324 'Current session state plus future input saved.')
1205 'Current session state plus future input saved.')
1325 logger.logstate()
1206 logger.logstate()
1326
1207
1327 def magic_logstop(self,parameter_s=''):
1208 def magic_logstop(self,parameter_s=''):
1328 """Fully stop logging and close log file.
1209 """Fully stop logging and close log file.
1329
1210
1330 In order to start logging again, a new %logstart call needs to be made,
1211 In order to start logging again, a new %logstart call needs to be made,
1331 possibly (though not necessarily) with a new filename, mode and other
1212 possibly (though not necessarily) with a new filename, mode and other
1332 options."""
1213 options."""
1333 self.logger.logstop()
1214 self.logger.logstop()
1334
1215
1335 def magic_logoff(self,parameter_s=''):
1216 def magic_logoff(self,parameter_s=''):
1336 """Temporarily stop logging.
1217 """Temporarily stop logging.
1337
1218
1338 You must have previously started logging."""
1219 You must have previously started logging."""
1339 self.shell.logger.switch_log(0)
1220 self.shell.logger.switch_log(0)
1340
1221
1341 def magic_logon(self,parameter_s=''):
1222 def magic_logon(self,parameter_s=''):
1342 """Restart logging.
1223 """Restart logging.
1343
1224
1344 This function is for restarting logging which you've temporarily
1225 This function is for restarting logging which you've temporarily
1345 stopped with %logoff. For starting logging for the first time, you
1226 stopped with %logoff. For starting logging for the first time, you
1346 must use the %logstart function, which allows you to specify an
1227 must use the %logstart function, which allows you to specify an
1347 optional log filename."""
1228 optional log filename."""
1348
1229
1349 self.shell.logger.switch_log(1)
1230 self.shell.logger.switch_log(1)
1350
1231
1351 def magic_logstate(self,parameter_s=''):
1232 def magic_logstate(self,parameter_s=''):
1352 """Print the status of the logging system."""
1233 """Print the status of the logging system."""
1353
1234
1354 self.shell.logger.logstate()
1235 self.shell.logger.logstate()
1355
1236
1356 def magic_pdb(self, parameter_s=''):
1237 def magic_pdb(self, parameter_s=''):
1357 """Control the automatic calling of the pdb interactive debugger.
1238 """Control the automatic calling of the pdb interactive debugger.
1358
1239
1359 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1240 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
1360 argument it works as a toggle.
1241 argument it works as a toggle.
1361
1242
1362 When an exception is triggered, IPython can optionally call the
1243 When an exception is triggered, IPython can optionally call the
1363 interactive pdb debugger after the traceback printout. %pdb toggles
1244 interactive pdb debugger after the traceback printout. %pdb toggles
1364 this feature on and off.
1245 this feature on and off.
1365
1246
1366 The initial state of this feature is set in your ipythonrc
1247 The initial state of this feature is set in your ipythonrc
1367 configuration file (the variable is called 'pdb').
1248 configuration file (the variable is called 'pdb').
1368
1249
1369 If you want to just activate the debugger AFTER an exception has fired,
1250 If you want to just activate the debugger AFTER an exception has fired,
1370 without having to type '%pdb on' and rerunning your code, you can use
1251 without having to type '%pdb on' and rerunning your code, you can use
1371 the %debug magic."""
1252 the %debug magic."""
1372
1253
1373 par = parameter_s.strip().lower()
1254 par = parameter_s.strip().lower()
1374
1255
1375 if par:
1256 if par:
1376 try:
1257 try:
1377 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1258 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
1378 except KeyError:
1259 except KeyError:
1379 print ('Incorrect argument. Use on/1, off/0, '
1260 print ('Incorrect argument. Use on/1, off/0, '
1380 'or nothing for a toggle.')
1261 'or nothing for a toggle.')
1381 return
1262 return
1382 else:
1263 else:
1383 # toggle
1264 # toggle
1384 new_pdb = not self.shell.call_pdb
1265 new_pdb = not self.shell.call_pdb
1385
1266
1386 # set on the shell
1267 # set on the shell
1387 self.shell.call_pdb = new_pdb
1268 self.shell.call_pdb = new_pdb
1388 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1269 print 'Automatic pdb calling has been turned',on_off(new_pdb)
1389
1270
1390 def magic_debug(self, parameter_s=''):
1271 def magic_debug(self, parameter_s=''):
1391 """Activate the interactive debugger in post-mortem mode.
1272 """Activate the interactive debugger in post-mortem mode.
1392
1273
1393 If an exception has just occurred, this lets you inspect its stack
1274 If an exception has just occurred, this lets you inspect its stack
1394 frames interactively. Note that this will always work only on the last
1275 frames interactively. Note that this will always work only on the last
1395 traceback that occurred, so you must call this quickly after an
1276 traceback that occurred, so you must call this quickly after an
1396 exception that you wish to inspect has fired, because if another one
1277 exception that you wish to inspect has fired, because if another one
1397 occurs, it clobbers the previous one.
1278 occurs, it clobbers the previous one.
1398
1279
1399 If you want IPython to automatically do this on every exception, see
1280 If you want IPython to automatically do this on every exception, see
1400 the %pdb magic for more details.
1281 the %pdb magic for more details.
1401 """
1282 """
1402 self.shell.debugger(force=True)
1283 self.shell.debugger(force=True)
1403
1284
1404 @testdec.skip_doctest
1285 @testdec.skip_doctest
1405 def magic_prun(self, parameter_s ='',user_mode=1,
1286 def magic_prun(self, parameter_s ='',user_mode=1,
1406 opts=None,arg_lst=None,prog_ns=None):
1287 opts=None,arg_lst=None,prog_ns=None):
1407
1288
1408 """Run a statement through the python code profiler.
1289 """Run a statement through the python code profiler.
1409
1290
1410 Usage:
1291 Usage:
1411 %prun [options] statement
1292 %prun [options] statement
1412
1293
1413 The given statement (which doesn't require quote marks) is run via the
1294 The given statement (which doesn't require quote marks) is run via the
1414 python profiler in a manner similar to the profile.run() function.
1295 python profiler in a manner similar to the profile.run() function.
1415 Namespaces are internally managed to work correctly; profile.run
1296 Namespaces are internally managed to work correctly; profile.run
1416 cannot be used in IPython because it makes certain assumptions about
1297 cannot be used in IPython because it makes certain assumptions about
1417 namespaces which do not hold under IPython.
1298 namespaces which do not hold under IPython.
1418
1299
1419 Options:
1300 Options:
1420
1301
1421 -l <limit>: you can place restrictions on what or how much of the
1302 -l <limit>: you can place restrictions on what or how much of the
1422 profile gets printed. The limit value can be:
1303 profile gets printed. The limit value can be:
1423
1304
1424 * A string: only information for function names containing this string
1305 * A string: only information for function names containing this string
1425 is printed.
1306 is printed.
1426
1307
1427 * An integer: only these many lines are printed.
1308 * An integer: only these many lines are printed.
1428
1309
1429 * A float (between 0 and 1): this fraction of the report is printed
1310 * A float (between 0 and 1): this fraction of the report is printed
1430 (for example, use a limit of 0.4 to see the topmost 40% only).
1311 (for example, use a limit of 0.4 to see the topmost 40% only).
1431
1312
1432 You can combine several limits with repeated use of the option. For
1313 You can combine several limits with repeated use of the option. For
1433 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1314 example, '-l __init__ -l 5' will print only the topmost 5 lines of
1434 information about class constructors.
1315 information about class constructors.
1435
1316
1436 -r: return the pstats.Stats object generated by the profiling. This
1317 -r: return the pstats.Stats object generated by the profiling. This
1437 object has all the information about the profile in it, and you can
1318 object has all the information about the profile in it, and you can
1438 later use it for further analysis or in other functions.
1319 later use it for further analysis or in other functions.
1439
1320
1440 -s <key>: sort profile by given key. You can provide more than one key
1321 -s <key>: sort profile by given key. You can provide more than one key
1441 by using the option several times: '-s key1 -s key2 -s key3...'. The
1322 by using the option several times: '-s key1 -s key2 -s key3...'. The
1442 default sorting key is 'time'.
1323 default sorting key is 'time'.
1443
1324
1444 The following is copied verbatim from the profile documentation
1325 The following is copied verbatim from the profile documentation
1445 referenced below:
1326 referenced below:
1446
1327
1447 When more than one key is provided, additional keys are used as
1328 When more than one key is provided, additional keys are used as
1448 secondary criteria when the there is equality in all keys selected
1329 secondary criteria when the there is equality in all keys selected
1449 before them.
1330 before them.
1450
1331
1451 Abbreviations can be used for any key names, as long as the
1332 Abbreviations can be used for any key names, as long as the
1452 abbreviation is unambiguous. The following are the keys currently
1333 abbreviation is unambiguous. The following are the keys currently
1453 defined:
1334 defined:
1454
1335
1455 Valid Arg Meaning
1336 Valid Arg Meaning
1456 "calls" call count
1337 "calls" call count
1457 "cumulative" cumulative time
1338 "cumulative" cumulative time
1458 "file" file name
1339 "file" file name
1459 "module" file name
1340 "module" file name
1460 "pcalls" primitive call count
1341 "pcalls" primitive call count
1461 "line" line number
1342 "line" line number
1462 "name" function name
1343 "name" function name
1463 "nfl" name/file/line
1344 "nfl" name/file/line
1464 "stdname" standard name
1345 "stdname" standard name
1465 "time" internal time
1346 "time" internal time
1466
1347
1467 Note that all sorts on statistics are in descending order (placing
1348 Note that all sorts on statistics are in descending order (placing
1468 most time consuming items first), where as name, file, and line number
1349 most time consuming items first), where as name, file, and line number
1469 searches are in ascending order (i.e., alphabetical). The subtle
1350 searches are in ascending order (i.e., alphabetical). The subtle
1470 distinction between "nfl" and "stdname" is that the standard name is a
1351 distinction between "nfl" and "stdname" is that the standard name is a
1471 sort of the name as printed, which means that the embedded line
1352 sort of the name as printed, which means that the embedded line
1472 numbers get compared in an odd way. For example, lines 3, 20, and 40
1353 numbers get compared in an odd way. For example, lines 3, 20, and 40
1473 would (if the file names were the same) appear in the string order
1354 would (if the file names were the same) appear in the string order
1474 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1355 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
1475 line numbers. In fact, sort_stats("nfl") is the same as
1356 line numbers. In fact, sort_stats("nfl") is the same as
1476 sort_stats("name", "file", "line").
1357 sort_stats("name", "file", "line").
1477
1358
1478 -T <filename>: save profile results as shown on screen to a text
1359 -T <filename>: save profile results as shown on screen to a text
1479 file. The profile is still shown on screen.
1360 file. The profile is still shown on screen.
1480
1361
1481 -D <filename>: save (via dump_stats) profile statistics to given
1362 -D <filename>: save (via dump_stats) profile statistics to given
1482 filename. This data is in a format understod by the pstats module, and
1363 filename. This data is in a format understod by the pstats module, and
1483 is generated by a call to the dump_stats() method of profile
1364 is generated by a call to the dump_stats() method of profile
1484 objects. The profile is still shown on screen.
1365 objects. The profile is still shown on screen.
1485
1366
1486 If you want to run complete programs under the profiler's control, use
1367 If you want to run complete programs under the profiler's control, use
1487 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1368 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
1488 contains profiler specific options as described here.
1369 contains profiler specific options as described here.
1489
1370
1490 You can read the complete documentation for the profile module with::
1371 You can read the complete documentation for the profile module with::
1491
1372
1492 In [1]: import profile; profile.help()
1373 In [1]: import profile; profile.help()
1493 """
1374 """
1494
1375
1495 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1376 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
1496 # protect user quote marks
1377 # protect user quote marks
1497 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1378 parameter_s = parameter_s.replace('"',r'\"').replace("'",r"\'")
1498
1379
1499 if user_mode: # regular user call
1380 if user_mode: # regular user call
1500 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1381 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:',
1501 list_all=1)
1382 list_all=1)
1502 namespace = self.shell.user_ns
1383 namespace = self.shell.user_ns
1503 else: # called to run a program by %run -p
1384 else: # called to run a program by %run -p
1504 try:
1385 try:
1505 filename = get_py_filename(arg_lst[0])
1386 filename = get_py_filename(arg_lst[0])
1506 except IOError,msg:
1387 except IOError,msg:
1507 error(msg)
1388 error(msg)
1508 return
1389 return
1509
1390
1510 arg_str = 'execfile(filename,prog_ns)'
1391 arg_str = 'execfile(filename,prog_ns)'
1511 namespace = locals()
1392 namespace = locals()
1512
1393
1513 opts.merge(opts_def)
1394 opts.merge(opts_def)
1514
1395
1515 prof = profile.Profile()
1396 prof = profile.Profile()
1516 try:
1397 try:
1517 prof = prof.runctx(arg_str,namespace,namespace)
1398 prof = prof.runctx(arg_str,namespace,namespace)
1518 sys_exit = ''
1399 sys_exit = ''
1519 except SystemExit:
1400 except SystemExit:
1520 sys_exit = """*** SystemExit exception caught in code being profiled."""
1401 sys_exit = """*** SystemExit exception caught in code being profiled."""
1521
1402
1522 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1403 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
1523
1404
1524 lims = opts.l
1405 lims = opts.l
1525 if lims:
1406 if lims:
1526 lims = [] # rebuild lims with ints/floats/strings
1407 lims = [] # rebuild lims with ints/floats/strings
1527 for lim in opts.l:
1408 for lim in opts.l:
1528 try:
1409 try:
1529 lims.append(int(lim))
1410 lims.append(int(lim))
1530 except ValueError:
1411 except ValueError:
1531 try:
1412 try:
1532 lims.append(float(lim))
1413 lims.append(float(lim))
1533 except ValueError:
1414 except ValueError:
1534 lims.append(lim)
1415 lims.append(lim)
1535
1416
1536 # Trap output.
1417 # Trap output.
1537 stdout_trap = StringIO()
1418 stdout_trap = StringIO()
1538
1419
1539 if hasattr(stats,'stream'):
1420 if hasattr(stats,'stream'):
1540 # In newer versions of python, the stats object has a 'stream'
1421 # In newer versions of python, the stats object has a 'stream'
1541 # attribute to write into.
1422 # attribute to write into.
1542 stats.stream = stdout_trap
1423 stats.stream = stdout_trap
1543 stats.print_stats(*lims)
1424 stats.print_stats(*lims)
1544 else:
1425 else:
1545 # For older versions, we manually redirect stdout during printing
1426 # For older versions, we manually redirect stdout during printing
1546 sys_stdout = sys.stdout
1427 sys_stdout = sys.stdout
1547 try:
1428 try:
1548 sys.stdout = stdout_trap
1429 sys.stdout = stdout_trap
1549 stats.print_stats(*lims)
1430 stats.print_stats(*lims)
1550 finally:
1431 finally:
1551 sys.stdout = sys_stdout
1432 sys.stdout = sys_stdout
1552
1433
1553 output = stdout_trap.getvalue()
1434 output = stdout_trap.getvalue()
1554 output = output.rstrip()
1435 output = output.rstrip()
1555
1436
1556 page(output,screen_lines=self.shell.usable_screen_length)
1437 page(output,screen_lines=self.shell.usable_screen_length)
1557 print sys_exit,
1438 print sys_exit,
1558
1439
1559 dump_file = opts.D[0]
1440 dump_file = opts.D[0]
1560 text_file = opts.T[0]
1441 text_file = opts.T[0]
1561 if dump_file:
1442 if dump_file:
1562 prof.dump_stats(dump_file)
1443 prof.dump_stats(dump_file)
1563 print '\n*** Profile stats marshalled to file',\
1444 print '\n*** Profile stats marshalled to file',\
1564 `dump_file`+'.',sys_exit
1445 `dump_file`+'.',sys_exit
1565 if text_file:
1446 if text_file:
1566 pfile = file(text_file,'w')
1447 pfile = file(text_file,'w')
1567 pfile.write(output)
1448 pfile.write(output)
1568 pfile.close()
1449 pfile.close()
1569 print '\n*** Profile printout saved to text file',\
1450 print '\n*** Profile printout saved to text file',\
1570 `text_file`+'.',sys_exit
1451 `text_file`+'.',sys_exit
1571
1452
1572 if opts.has_key('r'):
1453 if opts.has_key('r'):
1573 return stats
1454 return stats
1574 else:
1455 else:
1575 return None
1456 return None
1576
1457
1577 @testdec.skip_doctest
1458 @testdec.skip_doctest
1578 def magic_run(self, parameter_s ='',runner=None,
1459 def magic_run(self, parameter_s ='',runner=None,
1579 file_finder=get_py_filename):
1460 file_finder=get_py_filename):
1580 """Run the named file inside IPython as a program.
1461 """Run the named file inside IPython as a program.
1581
1462
1582 Usage:\\
1463 Usage:\\
1583 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1464 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
1584
1465
1585 Parameters after the filename are passed as command-line arguments to
1466 Parameters after the filename are passed as command-line arguments to
1586 the program (put in sys.argv). Then, control returns to IPython's
1467 the program (put in sys.argv). Then, control returns to IPython's
1587 prompt.
1468 prompt.
1588
1469
1589 This is similar to running at a system prompt:\\
1470 This is similar to running at a system prompt:\\
1590 $ python file args\\
1471 $ python file args\\
1591 but with the advantage of giving you IPython's tracebacks, and of
1472 but with the advantage of giving you IPython's tracebacks, and of
1592 loading all variables into your interactive namespace for further use
1473 loading all variables into your interactive namespace for further use
1593 (unless -p is used, see below).
1474 (unless -p is used, see below).
1594
1475
1595 The file is executed in a namespace initially consisting only of
1476 The file is executed in a namespace initially consisting only of
1596 __name__=='__main__' and sys.argv constructed as indicated. It thus
1477 __name__=='__main__' and sys.argv constructed as indicated. It thus
1597 sees its environment as if it were being run as a stand-alone program
1478 sees its environment as if it were being run as a stand-alone program
1598 (except for sharing global objects such as previously imported
1479 (except for sharing global objects such as previously imported
1599 modules). But after execution, the IPython interactive namespace gets
1480 modules). But after execution, the IPython interactive namespace gets
1600 updated with all variables defined in the program (except for __name__
1481 updated with all variables defined in the program (except for __name__
1601 and sys.argv). This allows for very convenient loading of code for
1482 and sys.argv). This allows for very convenient loading of code for
1602 interactive work, while giving each program a 'clean sheet' to run in.
1483 interactive work, while giving each program a 'clean sheet' to run in.
1603
1484
1604 Options:
1485 Options:
1605
1486
1606 -n: __name__ is NOT set to '__main__', but to the running file's name
1487 -n: __name__ is NOT set to '__main__', but to the running file's name
1607 without extension (as python does under import). This allows running
1488 without extension (as python does under import). This allows running
1608 scripts and reloading the definitions in them without calling code
1489 scripts and reloading the definitions in them without calling code
1609 protected by an ' if __name__ == "__main__" ' clause.
1490 protected by an ' if __name__ == "__main__" ' clause.
1610
1491
1611 -i: run the file in IPython's namespace instead of an empty one. This
1492 -i: run the file in IPython's namespace instead of an empty one. This
1612 is useful if you are experimenting with code written in a text editor
1493 is useful if you are experimenting with code written in a text editor
1613 which depends on variables defined interactively.
1494 which depends on variables defined interactively.
1614
1495
1615 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1496 -e: ignore sys.exit() calls or SystemExit exceptions in the script
1616 being run. This is particularly useful if IPython is being used to
1497 being run. This is particularly useful if IPython is being used to
1617 run unittests, which always exit with a sys.exit() call. In such
1498 run unittests, which always exit with a sys.exit() call. In such
1618 cases you are interested in the output of the test results, not in
1499 cases you are interested in the output of the test results, not in
1619 seeing a traceback of the unittest module.
1500 seeing a traceback of the unittest module.
1620
1501
1621 -t: print timing information at the end of the run. IPython will give
1502 -t: print timing information at the end of the run. IPython will give
1622 you an estimated CPU time consumption for your script, which under
1503 you an estimated CPU time consumption for your script, which under
1623 Unix uses the resource module to avoid the wraparound problems of
1504 Unix uses the resource module to avoid the wraparound problems of
1624 time.clock(). Under Unix, an estimate of time spent on system tasks
1505 time.clock(). Under Unix, an estimate of time spent on system tasks
1625 is also given (for Windows platforms this is reported as 0.0).
1506 is also given (for Windows platforms this is reported as 0.0).
1626
1507
1627 If -t is given, an additional -N<N> option can be given, where <N>
1508 If -t is given, an additional -N<N> option can be given, where <N>
1628 must be an integer indicating how many times you want the script to
1509 must be an integer indicating how many times you want the script to
1629 run. The final timing report will include total and per run results.
1510 run. The final timing report will include total and per run results.
1630
1511
1631 For example (testing the script uniq_stable.py):
1512 For example (testing the script uniq_stable.py):
1632
1513
1633 In [1]: run -t uniq_stable
1514 In [1]: run -t uniq_stable
1634
1515
1635 IPython CPU timings (estimated):\\
1516 IPython CPU timings (estimated):\\
1636 User : 0.19597 s.\\
1517 User : 0.19597 s.\\
1637 System: 0.0 s.\\
1518 System: 0.0 s.\\
1638
1519
1639 In [2]: run -t -N5 uniq_stable
1520 In [2]: run -t -N5 uniq_stable
1640
1521
1641 IPython CPU timings (estimated):\\
1522 IPython CPU timings (estimated):\\
1642 Total runs performed: 5\\
1523 Total runs performed: 5\\
1643 Times : Total Per run\\
1524 Times : Total Per run\\
1644 User : 0.910862 s, 0.1821724 s.\\
1525 User : 0.910862 s, 0.1821724 s.\\
1645 System: 0.0 s, 0.0 s.
1526 System: 0.0 s, 0.0 s.
1646
1527
1647 -d: run your program under the control of pdb, the Python debugger.
1528 -d: run your program under the control of pdb, the Python debugger.
1648 This allows you to execute your program step by step, watch variables,
1529 This allows you to execute your program step by step, watch variables,
1649 etc. Internally, what IPython does is similar to calling:
1530 etc. Internally, what IPython does is similar to calling:
1650
1531
1651 pdb.run('execfile("YOURFILENAME")')
1532 pdb.run('execfile("YOURFILENAME")')
1652
1533
1653 with a breakpoint set on line 1 of your file. You can change the line
1534 with a breakpoint set on line 1 of your file. You can change the line
1654 number for this automatic breakpoint to be <N> by using the -bN option
1535 number for this automatic breakpoint to be <N> by using the -bN option
1655 (where N must be an integer). For example:
1536 (where N must be an integer). For example:
1656
1537
1657 %run -d -b40 myscript
1538 %run -d -b40 myscript
1658
1539
1659 will set the first breakpoint at line 40 in myscript.py. Note that
1540 will set the first breakpoint at line 40 in myscript.py. Note that
1660 the first breakpoint must be set on a line which actually does
1541 the first breakpoint must be set on a line which actually does
1661 something (not a comment or docstring) for it to stop execution.
1542 something (not a comment or docstring) for it to stop execution.
1662
1543
1663 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1544 When the pdb debugger starts, you will see a (Pdb) prompt. You must
1664 first enter 'c' (without qoutes) to start execution up to the first
1545 first enter 'c' (without qoutes) to start execution up to the first
1665 breakpoint.
1546 breakpoint.
1666
1547
1667 Entering 'help' gives information about the use of the debugger. You
1548 Entering 'help' gives information about the use of the debugger. You
1668 can easily see pdb's full documentation with "import pdb;pdb.help()"
1549 can easily see pdb's full documentation with "import pdb;pdb.help()"
1669 at a prompt.
1550 at a prompt.
1670
1551
1671 -p: run program under the control of the Python profiler module (which
1552 -p: run program under the control of the Python profiler module (which
1672 prints a detailed report of execution times, function calls, etc).
1553 prints a detailed report of execution times, function calls, etc).
1673
1554
1674 You can pass other options after -p which affect the behavior of the
1555 You can pass other options after -p which affect the behavior of the
1675 profiler itself. See the docs for %prun for details.
1556 profiler itself. See the docs for %prun for details.
1676
1557
1677 In this mode, the program's variables do NOT propagate back to the
1558 In this mode, the program's variables do NOT propagate back to the
1678 IPython interactive namespace (because they remain in the namespace
1559 IPython interactive namespace (because they remain in the namespace
1679 where the profiler executes them).
1560 where the profiler executes them).
1680
1561
1681 Internally this triggers a call to %prun, see its documentation for
1562 Internally this triggers a call to %prun, see its documentation for
1682 details on the options available specifically for profiling.
1563 details on the options available specifically for profiling.
1683
1564
1684 There is one special usage for which the text above doesn't apply:
1565 There is one special usage for which the text above doesn't apply:
1685 if the filename ends with .ipy, the file is run as ipython script,
1566 if the filename ends with .ipy, the file is run as ipython script,
1686 just as if the commands were written on IPython prompt.
1567 just as if the commands were written on IPython prompt.
1687 """
1568 """
1688
1569
1689 # get arguments and set sys.argv for program to be run.
1570 # get arguments and set sys.argv for program to be run.
1690 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1571 opts,arg_lst = self.parse_options(parameter_s,'nidtN:b:pD:l:rs:T:e',
1691 mode='list',list_all=1)
1572 mode='list',list_all=1)
1692
1573
1693 try:
1574 try:
1694 filename = file_finder(arg_lst[0])
1575 filename = file_finder(arg_lst[0])
1695 except IndexError:
1576 except IndexError:
1696 warn('you must provide at least a filename.')
1577 warn('you must provide at least a filename.')
1697 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1578 print '\n%run:\n',oinspect.getdoc(self.magic_run)
1698 return
1579 return
1699 except IOError,msg:
1580 except IOError,msg:
1700 error(msg)
1581 error(msg)
1701 return
1582 return
1702
1583
1703 if filename.lower().endswith('.ipy'):
1584 if filename.lower().endswith('.ipy'):
1704 self.shell.safe_execfile_ipy(filename)
1585 self.shell.safe_execfile_ipy(filename)
1705 return
1586 return
1706
1587
1707 # Control the response to exit() calls made by the script being run
1588 # Control the response to exit() calls made by the script being run
1708 exit_ignore = opts.has_key('e')
1589 exit_ignore = opts.has_key('e')
1709
1590
1710 # Make sure that the running script gets a proper sys.argv as if it
1591 # Make sure that the running script gets a proper sys.argv as if it
1711 # were run from a system shell.
1592 # were run from a system shell.
1712 save_argv = sys.argv # save it for later restoring
1593 save_argv = sys.argv # save it for later restoring
1713 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1594 sys.argv = [filename]+ arg_lst[1:] # put in the proper filename
1714
1595
1715 if opts.has_key('i'):
1596 if opts.has_key('i'):
1716 # Run in user's interactive namespace
1597 # Run in user's interactive namespace
1717 prog_ns = self.shell.user_ns
1598 prog_ns = self.shell.user_ns
1718 __name__save = self.shell.user_ns['__name__']
1599 __name__save = self.shell.user_ns['__name__']
1719 prog_ns['__name__'] = '__main__'
1600 prog_ns['__name__'] = '__main__'
1720 main_mod = self.shell.new_main_mod(prog_ns)
1601 main_mod = self.shell.new_main_mod(prog_ns)
1721 else:
1602 else:
1722 # Run in a fresh, empty namespace
1603 # Run in a fresh, empty namespace
1723 if opts.has_key('n'):
1604 if opts.has_key('n'):
1724 name = os.path.splitext(os.path.basename(filename))[0]
1605 name = os.path.splitext(os.path.basename(filename))[0]
1725 else:
1606 else:
1726 name = '__main__'
1607 name = '__main__'
1727
1608
1728 main_mod = self.shell.new_main_mod()
1609 main_mod = self.shell.new_main_mod()
1729 prog_ns = main_mod.__dict__
1610 prog_ns = main_mod.__dict__
1730 prog_ns['__name__'] = name
1611 prog_ns['__name__'] = name
1731
1612
1732 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1613 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
1733 # set the __file__ global in the script's namespace
1614 # set the __file__ global in the script's namespace
1734 prog_ns['__file__'] = filename
1615 prog_ns['__file__'] = filename
1735
1616
1736 # pickle fix. See iplib for an explanation. But we need to make sure
1617 # pickle fix. See iplib for an explanation. But we need to make sure
1737 # that, if we overwrite __main__, we replace it at the end
1618 # that, if we overwrite __main__, we replace it at the end
1738 main_mod_name = prog_ns['__name__']
1619 main_mod_name = prog_ns['__name__']
1739
1620
1740 if main_mod_name == '__main__':
1621 if main_mod_name == '__main__':
1741 restore_main = sys.modules['__main__']
1622 restore_main = sys.modules['__main__']
1742 else:
1623 else:
1743 restore_main = False
1624 restore_main = False
1744
1625
1745 # This needs to be undone at the end to prevent holding references to
1626 # This needs to be undone at the end to prevent holding references to
1746 # every single object ever created.
1627 # every single object ever created.
1747 sys.modules[main_mod_name] = main_mod
1628 sys.modules[main_mod_name] = main_mod
1748
1629
1749 stats = None
1630 stats = None
1750 try:
1631 try:
1751 self.shell.savehist()
1632 self.shell.savehist()
1752
1633
1753 if opts.has_key('p'):
1634 if opts.has_key('p'):
1754 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1635 stats = self.magic_prun('',0,opts,arg_lst,prog_ns)
1755 else:
1636 else:
1756 if opts.has_key('d'):
1637 if opts.has_key('d'):
1757 deb = debugger.Pdb(self.shell.colors)
1638 deb = debugger.Pdb(self.shell.colors)
1758 # reset Breakpoint state, which is moronically kept
1639 # reset Breakpoint state, which is moronically kept
1759 # in a class
1640 # in a class
1760 bdb.Breakpoint.next = 1
1641 bdb.Breakpoint.next = 1
1761 bdb.Breakpoint.bplist = {}
1642 bdb.Breakpoint.bplist = {}
1762 bdb.Breakpoint.bpbynumber = [None]
1643 bdb.Breakpoint.bpbynumber = [None]
1763 # Set an initial breakpoint to stop execution
1644 # Set an initial breakpoint to stop execution
1764 maxtries = 10
1645 maxtries = 10
1765 bp = int(opts.get('b',[1])[0])
1646 bp = int(opts.get('b',[1])[0])
1766 checkline = deb.checkline(filename,bp)
1647 checkline = deb.checkline(filename,bp)
1767 if not checkline:
1648 if not checkline:
1768 for bp in range(bp+1,bp+maxtries+1):
1649 for bp in range(bp+1,bp+maxtries+1):
1769 if deb.checkline(filename,bp):
1650 if deb.checkline(filename,bp):
1770 break
1651 break
1771 else:
1652 else:
1772 msg = ("\nI failed to find a valid line to set "
1653 msg = ("\nI failed to find a valid line to set "
1773 "a breakpoint\n"
1654 "a breakpoint\n"
1774 "after trying up to line: %s.\n"
1655 "after trying up to line: %s.\n"
1775 "Please set a valid breakpoint manually "
1656 "Please set a valid breakpoint manually "
1776 "with the -b option." % bp)
1657 "with the -b option." % bp)
1777 error(msg)
1658 error(msg)
1778 return
1659 return
1779 # if we find a good linenumber, set the breakpoint
1660 # if we find a good linenumber, set the breakpoint
1780 deb.do_break('%s:%s' % (filename,bp))
1661 deb.do_break('%s:%s' % (filename,bp))
1781 # Start file run
1662 # Start file run
1782 print "NOTE: Enter 'c' at the",
1663 print "NOTE: Enter 'c' at the",
1783 print "%s prompt to start your script." % deb.prompt
1664 print "%s prompt to start your script." % deb.prompt
1784 try:
1665 try:
1785 deb.run('execfile("%s")' % filename,prog_ns)
1666 deb.run('execfile("%s")' % filename,prog_ns)
1786
1667
1787 except:
1668 except:
1788 etype, value, tb = sys.exc_info()
1669 etype, value, tb = sys.exc_info()
1789 # Skip three frames in the traceback: the %run one,
1670 # Skip three frames in the traceback: the %run one,
1790 # one inside bdb.py, and the command-line typed by the
1671 # one inside bdb.py, and the command-line typed by the
1791 # user (run by exec in pdb itself).
1672 # user (run by exec in pdb itself).
1792 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1673 self.shell.InteractiveTB(etype,value,tb,tb_offset=3)
1793 else:
1674 else:
1794 if runner is None:
1675 if runner is None:
1795 runner = self.shell.safe_execfile
1676 runner = self.shell.safe_execfile
1796 if opts.has_key('t'):
1677 if opts.has_key('t'):
1797 # timed execution
1678 # timed execution
1798 try:
1679 try:
1799 nruns = int(opts['N'][0])
1680 nruns = int(opts['N'][0])
1800 if nruns < 1:
1681 if nruns < 1:
1801 error('Number of runs must be >=1')
1682 error('Number of runs must be >=1')
1802 return
1683 return
1803 except (KeyError):
1684 except (KeyError):
1804 nruns = 1
1685 nruns = 1
1805 if nruns == 1:
1686 if nruns == 1:
1806 t0 = clock2()
1687 t0 = clock2()
1807 runner(filename,prog_ns,prog_ns,
1688 runner(filename,prog_ns,prog_ns,
1808 exit_ignore=exit_ignore)
1689 exit_ignore=exit_ignore)
1809 t1 = clock2()
1690 t1 = clock2()
1810 t_usr = t1[0]-t0[0]
1691 t_usr = t1[0]-t0[0]
1811 t_sys = t1[1]-t0[1]
1692 t_sys = t1[1]-t0[1]
1812 print "\nIPython CPU timings (estimated):"
1693 print "\nIPython CPU timings (estimated):"
1813 print " User : %10s s." % t_usr
1694 print " User : %10s s." % t_usr
1814 print " System: %10s s." % t_sys
1695 print " System: %10s s." % t_sys
1815 else:
1696 else:
1816 runs = range(nruns)
1697 runs = range(nruns)
1817 t0 = clock2()
1698 t0 = clock2()
1818 for nr in runs:
1699 for nr in runs:
1819 runner(filename,prog_ns,prog_ns,
1700 runner(filename,prog_ns,prog_ns,
1820 exit_ignore=exit_ignore)
1701 exit_ignore=exit_ignore)
1821 t1 = clock2()
1702 t1 = clock2()
1822 t_usr = t1[0]-t0[0]
1703 t_usr = t1[0]-t0[0]
1823 t_sys = t1[1]-t0[1]
1704 t_sys = t1[1]-t0[1]
1824 print "\nIPython CPU timings (estimated):"
1705 print "\nIPython CPU timings (estimated):"
1825 print "Total runs performed:",nruns
1706 print "Total runs performed:",nruns
1826 print " Times : %10s %10s" % ('Total','Per run')
1707 print " Times : %10s %10s" % ('Total','Per run')
1827 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1708 print " User : %10s s, %10s s." % (t_usr,t_usr/nruns)
1828 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1709 print " System: %10s s, %10s s." % (t_sys,t_sys/nruns)
1829
1710
1830 else:
1711 else:
1831 # regular execution
1712 # regular execution
1832 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1713 runner(filename,prog_ns,prog_ns,exit_ignore=exit_ignore)
1833
1714
1834 if opts.has_key('i'):
1715 if opts.has_key('i'):
1835 self.shell.user_ns['__name__'] = __name__save
1716 self.shell.user_ns['__name__'] = __name__save
1836 else:
1717 else:
1837 # The shell MUST hold a reference to prog_ns so after %run
1718 # The shell MUST hold a reference to prog_ns so after %run
1838 # exits, the python deletion mechanism doesn't zero it out
1719 # exits, the python deletion mechanism doesn't zero it out
1839 # (leaving dangling references).
1720 # (leaving dangling references).
1840 self.shell.cache_main_mod(prog_ns,filename)
1721 self.shell.cache_main_mod(prog_ns,filename)
1841 # update IPython interactive namespace
1722 # update IPython interactive namespace
1842
1723
1843 # Some forms of read errors on the file may mean the
1724 # Some forms of read errors on the file may mean the
1844 # __name__ key was never set; using pop we don't have to
1725 # __name__ key was never set; using pop we don't have to
1845 # worry about a possible KeyError.
1726 # worry about a possible KeyError.
1846 prog_ns.pop('__name__', None)
1727 prog_ns.pop('__name__', None)
1847
1728
1848 self.shell.user_ns.update(prog_ns)
1729 self.shell.user_ns.update(prog_ns)
1849 finally:
1730 finally:
1850 # It's a bit of a mystery why, but __builtins__ can change from
1731 # It's a bit of a mystery why, but __builtins__ can change from
1851 # being a module to becoming a dict missing some key data after
1732 # being a module to becoming a dict missing some key data after
1852 # %run. As best I can see, this is NOT something IPython is doing
1733 # %run. As best I can see, this is NOT something IPython is doing
1853 # at all, and similar problems have been reported before:
1734 # at all, and similar problems have been reported before:
1854 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1735 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
1855 # Since this seems to be done by the interpreter itself, the best
1736 # Since this seems to be done by the interpreter itself, the best
1856 # we can do is to at least restore __builtins__ for the user on
1737 # we can do is to at least restore __builtins__ for the user on
1857 # exit.
1738 # exit.
1858 self.shell.user_ns['__builtins__'] = __builtin__
1739 self.shell.user_ns['__builtins__'] = __builtin__
1859
1740
1860 # Ensure key global structures are restored
1741 # Ensure key global structures are restored
1861 sys.argv = save_argv
1742 sys.argv = save_argv
1862 if restore_main:
1743 if restore_main:
1863 sys.modules['__main__'] = restore_main
1744 sys.modules['__main__'] = restore_main
1864 else:
1745 else:
1865 # Remove from sys.modules the reference to main_mod we'd
1746 # Remove from sys.modules the reference to main_mod we'd
1866 # added. Otherwise it will trap references to objects
1747 # added. Otherwise it will trap references to objects
1867 # contained therein.
1748 # contained therein.
1868 del sys.modules[main_mod_name]
1749 del sys.modules[main_mod_name]
1869
1750
1870 self.shell.reloadhist()
1751 self.shell.reloadhist()
1871
1752
1872 return stats
1753 return stats
1873
1754
1874 @testdec.skip_doctest
1755 @testdec.skip_doctest
1875 def magic_timeit(self, parameter_s =''):
1756 def magic_timeit(self, parameter_s =''):
1876 """Time execution of a Python statement or expression
1757 """Time execution of a Python statement or expression
1877
1758
1878 Usage:\\
1759 Usage:\\
1879 %timeit [-n<N> -r<R> [-t|-c]] statement
1760 %timeit [-n<N> -r<R> [-t|-c]] statement
1880
1761
1881 Time execution of a Python statement or expression using the timeit
1762 Time execution of a Python statement or expression using the timeit
1882 module.
1763 module.
1883
1764
1884 Options:
1765 Options:
1885 -n<N>: execute the given statement <N> times in a loop. If this value
1766 -n<N>: execute the given statement <N> times in a loop. If this value
1886 is not given, a fitting value is chosen.
1767 is not given, a fitting value is chosen.
1887
1768
1888 -r<R>: repeat the loop iteration <R> times and take the best result.
1769 -r<R>: repeat the loop iteration <R> times and take the best result.
1889 Default: 3
1770 Default: 3
1890
1771
1891 -t: use time.time to measure the time, which is the default on Unix.
1772 -t: use time.time to measure the time, which is the default on Unix.
1892 This function measures wall time.
1773 This function measures wall time.
1893
1774
1894 -c: use time.clock to measure the time, which is the default on
1775 -c: use time.clock to measure the time, which is the default on
1895 Windows and measures wall time. On Unix, resource.getrusage is used
1776 Windows and measures wall time. On Unix, resource.getrusage is used
1896 instead and returns the CPU user time.
1777 instead and returns the CPU user time.
1897
1778
1898 -p<P>: use a precision of <P> digits to display the timing result.
1779 -p<P>: use a precision of <P> digits to display the timing result.
1899 Default: 3
1780 Default: 3
1900
1781
1901
1782
1902 Examples:
1783 Examples:
1903
1784
1904 In [1]: %timeit pass
1785 In [1]: %timeit pass
1905 10000000 loops, best of 3: 53.3 ns per loop
1786 10000000 loops, best of 3: 53.3 ns per loop
1906
1787
1907 In [2]: u = None
1788 In [2]: u = None
1908
1789
1909 In [3]: %timeit u is None
1790 In [3]: %timeit u is None
1910 10000000 loops, best of 3: 184 ns per loop
1791 10000000 loops, best of 3: 184 ns per loop
1911
1792
1912 In [4]: %timeit -r 4 u == None
1793 In [4]: %timeit -r 4 u == None
1913 1000000 loops, best of 4: 242 ns per loop
1794 1000000 loops, best of 4: 242 ns per loop
1914
1795
1915 In [5]: import time
1796 In [5]: import time
1916
1797
1917 In [6]: %timeit -n1 time.sleep(2)
1798 In [6]: %timeit -n1 time.sleep(2)
1918 1 loops, best of 3: 2 s per loop
1799 1 loops, best of 3: 2 s per loop
1919
1800
1920
1801
1921 The times reported by %timeit will be slightly higher than those
1802 The times reported by %timeit will be slightly higher than those
1922 reported by the timeit.py script when variables are accessed. This is
1803 reported by the timeit.py script when variables are accessed. This is
1923 due to the fact that %timeit executes the statement in the namespace
1804 due to the fact that %timeit executes the statement in the namespace
1924 of the shell, compared with timeit.py, which uses a single setup
1805 of the shell, compared with timeit.py, which uses a single setup
1925 statement to import function or create variables. Generally, the bias
1806 statement to import function or create variables. Generally, the bias
1926 does not matter as long as results from timeit.py are not mixed with
1807 does not matter as long as results from timeit.py are not mixed with
1927 those from %timeit."""
1808 those from %timeit."""
1928
1809
1929 import timeit
1810 import timeit
1930 import math
1811 import math
1931
1812
1932 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1813 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
1933 # certain terminals. Until we figure out a robust way of
1814 # certain terminals. Until we figure out a robust way of
1934 # auto-detecting if the terminal can deal with it, use plain 'us' for
1815 # auto-detecting if the terminal can deal with it, use plain 'us' for
1935 # microseconds. I am really NOT happy about disabling the proper
1816 # microseconds. I am really NOT happy about disabling the proper
1936 # 'micro' prefix, but crashing is worse... If anyone knows what the
1817 # 'micro' prefix, but crashing is worse... If anyone knows what the
1937 # right solution for this is, I'm all ears...
1818 # right solution for this is, I'm all ears...
1938 #
1819 #
1939 # Note: using
1820 # Note: using
1940 #
1821 #
1941 # s = u'\xb5'
1822 # s = u'\xb5'
1942 # s.encode(sys.getdefaultencoding())
1823 # s.encode(sys.getdefaultencoding())
1943 #
1824 #
1944 # is not sufficient, as I've seen terminals where that fails but
1825 # is not sufficient, as I've seen terminals where that fails but
1945 # print s
1826 # print s
1946 #
1827 #
1947 # succeeds
1828 # succeeds
1948 #
1829 #
1949 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1830 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1950
1831
1951 #units = [u"s", u"ms",u'\xb5',"ns"]
1832 #units = [u"s", u"ms",u'\xb5',"ns"]
1952 units = [u"s", u"ms",u'us',"ns"]
1833 units = [u"s", u"ms",u'us',"ns"]
1953
1834
1954 scaling = [1, 1e3, 1e6, 1e9]
1835 scaling = [1, 1e3, 1e6, 1e9]
1955
1836
1956 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1837 opts, stmt = self.parse_options(parameter_s,'n:r:tcp:',
1957 posix=False)
1838 posix=False)
1958 if stmt == "":
1839 if stmt == "":
1959 return
1840 return
1960 timefunc = timeit.default_timer
1841 timefunc = timeit.default_timer
1961 number = int(getattr(opts, "n", 0))
1842 number = int(getattr(opts, "n", 0))
1962 repeat = int(getattr(opts, "r", timeit.default_repeat))
1843 repeat = int(getattr(opts, "r", timeit.default_repeat))
1963 precision = int(getattr(opts, "p", 3))
1844 precision = int(getattr(opts, "p", 3))
1964 if hasattr(opts, "t"):
1845 if hasattr(opts, "t"):
1965 timefunc = time.time
1846 timefunc = time.time
1966 if hasattr(opts, "c"):
1847 if hasattr(opts, "c"):
1967 timefunc = clock
1848 timefunc = clock
1968
1849
1969 timer = timeit.Timer(timer=timefunc)
1850 timer = timeit.Timer(timer=timefunc)
1970 # this code has tight coupling to the inner workings of timeit.Timer,
1851 # this code has tight coupling to the inner workings of timeit.Timer,
1971 # but is there a better way to achieve that the code stmt has access
1852 # but is there a better way to achieve that the code stmt has access
1972 # to the shell namespace?
1853 # to the shell namespace?
1973
1854
1974 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1855 src = timeit.template % {'stmt': timeit.reindent(stmt, 8),
1975 'setup': "pass"}
1856 'setup': "pass"}
1976 # Track compilation time so it can be reported if too long
1857 # Track compilation time so it can be reported if too long
1977 # Minimum time above which compilation time will be reported
1858 # Minimum time above which compilation time will be reported
1978 tc_min = 0.1
1859 tc_min = 0.1
1979
1860
1980 t0 = clock()
1861 t0 = clock()
1981 code = compile(src, "<magic-timeit>", "exec")
1862 code = compile(src, "<magic-timeit>", "exec")
1982 tc = clock()-t0
1863 tc = clock()-t0
1983
1864
1984 ns = {}
1865 ns = {}
1985 exec code in self.shell.user_ns, ns
1866 exec code in self.shell.user_ns, ns
1986 timer.inner = ns["inner"]
1867 timer.inner = ns["inner"]
1987
1868
1988 if number == 0:
1869 if number == 0:
1989 # determine number so that 0.2 <= total time < 2.0
1870 # determine number so that 0.2 <= total time < 2.0
1990 number = 1
1871 number = 1
1991 for i in range(1, 10):
1872 for i in range(1, 10):
1992 if timer.timeit(number) >= 0.2:
1873 if timer.timeit(number) >= 0.2:
1993 break
1874 break
1994 number *= 10
1875 number *= 10
1995
1876
1996 best = min(timer.repeat(repeat, number)) / number
1877 best = min(timer.repeat(repeat, number)) / number
1997
1878
1998 if best > 0.0:
1879 if best > 0.0:
1999 order = min(-int(math.floor(math.log10(best)) // 3), 3)
1880 order = min(-int(math.floor(math.log10(best)) // 3), 3)
2000 else:
1881 else:
2001 order = 3
1882 order = 3
2002 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
1883 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
2003 precision,
1884 precision,
2004 best * scaling[order],
1885 best * scaling[order],
2005 units[order])
1886 units[order])
2006 if tc > tc_min:
1887 if tc > tc_min:
2007 print "Compiler time: %.2f s" % tc
1888 print "Compiler time: %.2f s" % tc
2008
1889
2009 @testdec.skip_doctest
1890 @testdec.skip_doctest
2010 def magic_time(self,parameter_s = ''):
1891 def magic_time(self,parameter_s = ''):
2011 """Time execution of a Python statement or expression.
1892 """Time execution of a Python statement or expression.
2012
1893
2013 The CPU and wall clock times are printed, and the value of the
1894 The CPU and wall clock times are printed, and the value of the
2014 expression (if any) is returned. Note that under Win32, system time
1895 expression (if any) is returned. Note that under Win32, system time
2015 is always reported as 0, since it can not be measured.
1896 is always reported as 0, since it can not be measured.
2016
1897
2017 This function provides very basic timing functionality. In Python
1898 This function provides very basic timing functionality. In Python
2018 2.3, the timeit module offers more control and sophistication, so this
1899 2.3, the timeit module offers more control and sophistication, so this
2019 could be rewritten to use it (patches welcome).
1900 could be rewritten to use it (patches welcome).
2020
1901
2021 Some examples:
1902 Some examples:
2022
1903
2023 In [1]: time 2**128
1904 In [1]: time 2**128
2024 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1905 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2025 Wall time: 0.00
1906 Wall time: 0.00
2026 Out[1]: 340282366920938463463374607431768211456L
1907 Out[1]: 340282366920938463463374607431768211456L
2027
1908
2028 In [2]: n = 1000000
1909 In [2]: n = 1000000
2029
1910
2030 In [3]: time sum(range(n))
1911 In [3]: time sum(range(n))
2031 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1912 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
2032 Wall time: 1.37
1913 Wall time: 1.37
2033 Out[3]: 499999500000L
1914 Out[3]: 499999500000L
2034
1915
2035 In [4]: time print 'hello world'
1916 In [4]: time print 'hello world'
2036 hello world
1917 hello world
2037 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1918 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2038 Wall time: 0.00
1919 Wall time: 0.00
2039
1920
2040 Note that the time needed by Python to compile the given expression
1921 Note that the time needed by Python to compile the given expression
2041 will be reported if it is more than 0.1s. In this example, the
1922 will be reported if it is more than 0.1s. In this example, the
2042 actual exponentiation is done by Python at compilation time, so while
1923 actual exponentiation is done by Python at compilation time, so while
2043 the expression can take a noticeable amount of time to compute, that
1924 the expression can take a noticeable amount of time to compute, that
2044 time is purely due to the compilation:
1925 time is purely due to the compilation:
2045
1926
2046 In [5]: time 3**9999;
1927 In [5]: time 3**9999;
2047 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1928 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2048 Wall time: 0.00 s
1929 Wall time: 0.00 s
2049
1930
2050 In [6]: time 3**999999;
1931 In [6]: time 3**999999;
2051 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1932 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
2052 Wall time: 0.00 s
1933 Wall time: 0.00 s
2053 Compiler : 0.78 s
1934 Compiler : 0.78 s
2054 """
1935 """
2055
1936
2056 # fail immediately if the given expression can't be compiled
1937 # fail immediately if the given expression can't be compiled
2057
1938
2058 expr = self.shell.prefilter(parameter_s,False)
1939 expr = self.shell.prefilter(parameter_s,False)
2059
1940
2060 # Minimum time above which compilation time will be reported
1941 # Minimum time above which compilation time will be reported
2061 tc_min = 0.1
1942 tc_min = 0.1
2062
1943
2063 try:
1944 try:
2064 mode = 'eval'
1945 mode = 'eval'
2065 t0 = clock()
1946 t0 = clock()
2066 code = compile(expr,'<timed eval>',mode)
1947 code = compile(expr,'<timed eval>',mode)
2067 tc = clock()-t0
1948 tc = clock()-t0
2068 except SyntaxError:
1949 except SyntaxError:
2069 mode = 'exec'
1950 mode = 'exec'
2070 t0 = clock()
1951 t0 = clock()
2071 code = compile(expr,'<timed exec>',mode)
1952 code = compile(expr,'<timed exec>',mode)
2072 tc = clock()-t0
1953 tc = clock()-t0
2073 # skew measurement as little as possible
1954 # skew measurement as little as possible
2074 glob = self.shell.user_ns
1955 glob = self.shell.user_ns
2075 clk = clock2
1956 clk = clock2
2076 wtime = time.time
1957 wtime = time.time
2077 # time execution
1958 # time execution
2078 wall_st = wtime()
1959 wall_st = wtime()
2079 if mode=='eval':
1960 if mode=='eval':
2080 st = clk()
1961 st = clk()
2081 out = eval(code,glob)
1962 out = eval(code,glob)
2082 end = clk()
1963 end = clk()
2083 else:
1964 else:
2084 st = clk()
1965 st = clk()
2085 exec code in glob
1966 exec code in glob
2086 end = clk()
1967 end = clk()
2087 out = None
1968 out = None
2088 wall_end = wtime()
1969 wall_end = wtime()
2089 # Compute actual times and report
1970 # Compute actual times and report
2090 wall_time = wall_end-wall_st
1971 wall_time = wall_end-wall_st
2091 cpu_user = end[0]-st[0]
1972 cpu_user = end[0]-st[0]
2092 cpu_sys = end[1]-st[1]
1973 cpu_sys = end[1]-st[1]
2093 cpu_tot = cpu_user+cpu_sys
1974 cpu_tot = cpu_user+cpu_sys
2094 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
1975 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
2095 (cpu_user,cpu_sys,cpu_tot)
1976 (cpu_user,cpu_sys,cpu_tot)
2096 print "Wall time: %.2f s" % wall_time
1977 print "Wall time: %.2f s" % wall_time
2097 if tc > tc_min:
1978 if tc > tc_min:
2098 print "Compiler : %.2f s" % tc
1979 print "Compiler : %.2f s" % tc
2099 return out
1980 return out
2100
1981
2101 @testdec.skip_doctest
1982 @testdec.skip_doctest
2102 def magic_macro(self,parameter_s = ''):
1983 def magic_macro(self,parameter_s = ''):
2103 """Define a set of input lines as a macro for future re-execution.
1984 """Define a set of input lines as a macro for future re-execution.
2104
1985
2105 Usage:\\
1986 Usage:\\
2106 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1987 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
2107
1988
2108 Options:
1989 Options:
2109
1990
2110 -r: use 'raw' input. By default, the 'processed' history is used,
1991 -r: use 'raw' input. By default, the 'processed' history is used,
2111 so that magics are loaded in their transformed version to valid
1992 so that magics are loaded in their transformed version to valid
2112 Python. If this option is given, the raw input as typed as the
1993 Python. If this option is given, the raw input as typed as the
2113 command line is used instead.
1994 command line is used instead.
2114
1995
2115 This will define a global variable called `name` which is a string
1996 This will define a global variable called `name` which is a string
2116 made of joining the slices and lines you specify (n1,n2,... numbers
1997 made of joining the slices and lines you specify (n1,n2,... numbers
2117 above) from your input history into a single string. This variable
1998 above) from your input history into a single string. This variable
2118 acts like an automatic function which re-executes those lines as if
1999 acts like an automatic function which re-executes those lines as if
2119 you had typed them. You just type 'name' at the prompt and the code
2000 you had typed them. You just type 'name' at the prompt and the code
2120 executes.
2001 executes.
2121
2002
2122 The notation for indicating number ranges is: n1-n2 means 'use line
2003 The notation for indicating number ranges is: n1-n2 means 'use line
2123 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2004 numbers n1,...n2' (the endpoint is included). That is, '5-7' means
2124 using the lines numbered 5,6 and 7.
2005 using the lines numbered 5,6 and 7.
2125
2006
2126 Note: as a 'hidden' feature, you can also use traditional python slice
2007 Note: as a 'hidden' feature, you can also use traditional python slice
2127 notation, where N:M means numbers N through M-1.
2008 notation, where N:M means numbers N through M-1.
2128
2009
2129 For example, if your history contains (%hist prints it):
2010 For example, if your history contains (%hist prints it):
2130
2011
2131 44: x=1
2012 44: x=1
2132 45: y=3
2013 45: y=3
2133 46: z=x+y
2014 46: z=x+y
2134 47: print x
2015 47: print x
2135 48: a=5
2016 48: a=5
2136 49: print 'x',x,'y',y
2017 49: print 'x',x,'y',y
2137
2018
2138 you can create a macro with lines 44 through 47 (included) and line 49
2019 you can create a macro with lines 44 through 47 (included) and line 49
2139 called my_macro with:
2020 called my_macro with:
2140
2021
2141 In [55]: %macro my_macro 44-47 49
2022 In [55]: %macro my_macro 44-47 49
2142
2023
2143 Now, typing `my_macro` (without quotes) will re-execute all this code
2024 Now, typing `my_macro` (without quotes) will re-execute all this code
2144 in one pass.
2025 in one pass.
2145
2026
2146 You don't need to give the line-numbers in order, and any given line
2027 You don't need to give the line-numbers in order, and any given line
2147 number can appear multiple times. You can assemble macros with any
2028 number can appear multiple times. You can assemble macros with any
2148 lines from your input history in any order.
2029 lines from your input history in any order.
2149
2030
2150 The macro is a simple object which holds its value in an attribute,
2031 The macro is a simple object which holds its value in an attribute,
2151 but IPython's display system checks for macros and executes them as
2032 but IPython's display system checks for macros and executes them as
2152 code instead of printing them when you type their name.
2033 code instead of printing them when you type their name.
2153
2034
2154 You can view a macro's contents by explicitly printing it with:
2035 You can view a macro's contents by explicitly printing it with:
2155
2036
2156 'print macro_name'.
2037 'print macro_name'.
2157
2038
2158 For one-off cases which DON'T contain magic function calls in them you
2039 For one-off cases which DON'T contain magic function calls in them you
2159 can obtain similar results by explicitly executing slices from your
2040 can obtain similar results by explicitly executing slices from your
2160 input history with:
2041 input history with:
2161
2042
2162 In [60]: exec In[44:48]+In[49]"""
2043 In [60]: exec In[44:48]+In[49]"""
2163
2044
2164 opts,args = self.parse_options(parameter_s,'r',mode='list')
2045 opts,args = self.parse_options(parameter_s,'r',mode='list')
2165 if not args:
2046 if not args:
2166 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2047 macs = [k for k,v in self.shell.user_ns.items() if isinstance(v, Macro)]
2167 macs.sort()
2048 macs.sort()
2168 return macs
2049 return macs
2169 if len(args) == 1:
2050 if len(args) == 1:
2170 raise UsageError(
2051 raise UsageError(
2171 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2052 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
2172 name,ranges = args[0], args[1:]
2053 name,ranges = args[0], args[1:]
2173
2054
2174 #print 'rng',ranges # dbg
2055 #print 'rng',ranges # dbg
2175 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2056 lines = self.extract_input_slices(ranges,opts.has_key('r'))
2176 macro = Macro(lines)
2057 macro = Macro(lines)
2177 self.shell.define_macro(name, macro)
2058 self.shell.define_macro(name, macro)
2178 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2059 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
2179 print 'Macro contents:'
2060 print 'Macro contents:'
2180 print macro,
2061 print macro,
2181
2062
2182 def magic_save(self,parameter_s = ''):
2063 def magic_save(self,parameter_s = ''):
2183 """Save a set of lines to a given filename.
2064 """Save a set of lines to a given filename.
2184
2065
2185 Usage:\\
2066 Usage:\\
2186 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2067 %save [options] filename n1-n2 n3-n4 ... n5 .. n6 ...
2187
2068
2188 Options:
2069 Options:
2189
2070
2190 -r: use 'raw' input. By default, the 'processed' history is used,
2071 -r: use 'raw' input. By default, the 'processed' history is used,
2191 so that magics are loaded in their transformed version to valid
2072 so that magics are loaded in their transformed version to valid
2192 Python. If this option is given, the raw input as typed as the
2073 Python. If this option is given, the raw input as typed as the
2193 command line is used instead.
2074 command line is used instead.
2194
2075
2195 This function uses the same syntax as %macro for line extraction, but
2076 This function uses the same syntax as %macro for line extraction, but
2196 instead of creating a macro it saves the resulting string to the
2077 instead of creating a macro it saves the resulting string to the
2197 filename you specify.
2078 filename you specify.
2198
2079
2199 It adds a '.py' extension to the file if you don't do so yourself, and
2080 It adds a '.py' extension to the file if you don't do so yourself, and
2200 it asks for confirmation before overwriting existing files."""
2081 it asks for confirmation before overwriting existing files."""
2201
2082
2202 opts,args = self.parse_options(parameter_s,'r',mode='list')
2083 opts,args = self.parse_options(parameter_s,'r',mode='list')
2203 fname,ranges = args[0], args[1:]
2084 fname,ranges = args[0], args[1:]
2204 if not fname.endswith('.py'):
2085 if not fname.endswith('.py'):
2205 fname += '.py'
2086 fname += '.py'
2206 if os.path.isfile(fname):
2087 if os.path.isfile(fname):
2207 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2088 ans = raw_input('File `%s` exists. Overwrite (y/[N])? ' % fname)
2208 if ans.lower() not in ['y','yes']:
2089 if ans.lower() not in ['y','yes']:
2209 print 'Operation cancelled.'
2090 print 'Operation cancelled.'
2210 return
2091 return
2211 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2092 cmds = ''.join(self.extract_input_slices(ranges,opts.has_key('r')))
2212 f = file(fname,'w')
2093 f = file(fname,'w')
2213 f.write(cmds)
2094 f.write(cmds)
2214 f.close()
2095 f.close()
2215 print 'The following commands were written to file `%s`:' % fname
2096 print 'The following commands were written to file `%s`:' % fname
2216 print cmds
2097 print cmds
2217
2098
2218 def _edit_macro(self,mname,macro):
2099 def _edit_macro(self,mname,macro):
2219 """open an editor with the macro data in a file"""
2100 """open an editor with the macro data in a file"""
2220 filename = self.shell.mktempfile(macro.value)
2101 filename = self.shell.mktempfile(macro.value)
2221 self.shell.hooks.editor(filename)
2102 self.shell.hooks.editor(filename)
2222
2103
2223 # and make a new macro object, to replace the old one
2104 # and make a new macro object, to replace the old one
2224 mfile = open(filename)
2105 mfile = open(filename)
2225 mvalue = mfile.read()
2106 mvalue = mfile.read()
2226 mfile.close()
2107 mfile.close()
2227 self.shell.user_ns[mname] = Macro(mvalue)
2108 self.shell.user_ns[mname] = Macro(mvalue)
2228
2109
2229 def magic_ed(self,parameter_s=''):
2110 def magic_ed(self,parameter_s=''):
2230 """Alias to %edit."""
2111 """Alias to %edit."""
2231 return self.magic_edit(parameter_s)
2112 return self.magic_edit(parameter_s)
2232
2113
2233 @testdec.skip_doctest
2114 @testdec.skip_doctest
2234 def magic_edit(self,parameter_s='',last_call=['','']):
2115 def magic_edit(self,parameter_s='',last_call=['','']):
2235 """Bring up an editor and execute the resulting code.
2116 """Bring up an editor and execute the resulting code.
2236
2117
2237 Usage:
2118 Usage:
2238 %edit [options] [args]
2119 %edit [options] [args]
2239
2120
2240 %edit runs IPython's editor hook. The default version of this hook is
2121 %edit runs IPython's editor hook. The default version of this hook is
2241 set to call the __IPYTHON__.rc.editor command. This is read from your
2122 set to call the __IPYTHON__.rc.editor command. This is read from your
2242 environment variable $EDITOR. If this isn't found, it will default to
2123 environment variable $EDITOR. If this isn't found, it will default to
2243 vi under Linux/Unix and to notepad under Windows. See the end of this
2124 vi under Linux/Unix and to notepad under Windows. See the end of this
2244 docstring for how to change the editor hook.
2125 docstring for how to change the editor hook.
2245
2126
2246 You can also set the value of this editor via the command line option
2127 You can also set the value of this editor via the command line option
2247 '-editor' or in your ipythonrc file. This is useful if you wish to use
2128 '-editor' or in your ipythonrc file. This is useful if you wish to use
2248 specifically for IPython an editor different from your typical default
2129 specifically for IPython an editor different from your typical default
2249 (and for Windows users who typically don't set environment variables).
2130 (and for Windows users who typically don't set environment variables).
2250
2131
2251 This command allows you to conveniently edit multi-line code right in
2132 This command allows you to conveniently edit multi-line code right in
2252 your IPython session.
2133 your IPython session.
2253
2134
2254 If called without arguments, %edit opens up an empty editor with a
2135 If called without arguments, %edit opens up an empty editor with a
2255 temporary file and will execute the contents of this file when you
2136 temporary file and will execute the contents of this file when you
2256 close it (don't forget to save it!).
2137 close it (don't forget to save it!).
2257
2138
2258
2139
2259 Options:
2140 Options:
2260
2141
2261 -n <number>: open the editor at a specified line number. By default,
2142 -n <number>: open the editor at a specified line number. By default,
2262 the IPython editor hook uses the unix syntax 'editor +N filename', but
2143 the IPython editor hook uses the unix syntax 'editor +N filename', but
2263 you can configure this by providing your own modified hook if your
2144 you can configure this by providing your own modified hook if your
2264 favorite editor supports line-number specifications with a different
2145 favorite editor supports line-number specifications with a different
2265 syntax.
2146 syntax.
2266
2147
2267 -p: this will call the editor with the same data as the previous time
2148 -p: this will call the editor with the same data as the previous time
2268 it was used, regardless of how long ago (in your current session) it
2149 it was used, regardless of how long ago (in your current session) it
2269 was.
2150 was.
2270
2151
2271 -r: use 'raw' input. This option only applies to input taken from the
2152 -r: use 'raw' input. This option only applies to input taken from the
2272 user's history. By default, the 'processed' history is used, so that
2153 user's history. By default, the 'processed' history is used, so that
2273 magics are loaded in their transformed version to valid Python. If
2154 magics are loaded in their transformed version to valid Python. If
2274 this option is given, the raw input as typed as the command line is
2155 this option is given, the raw input as typed as the command line is
2275 used instead. When you exit the editor, it will be executed by
2156 used instead. When you exit the editor, it will be executed by
2276 IPython's own processor.
2157 IPython's own processor.
2277
2158
2278 -x: do not execute the edited code immediately upon exit. This is
2159 -x: do not execute the edited code immediately upon exit. This is
2279 mainly useful if you are editing programs which need to be called with
2160 mainly useful if you are editing programs which need to be called with
2280 command line arguments, which you can then do using %run.
2161 command line arguments, which you can then do using %run.
2281
2162
2282
2163
2283 Arguments:
2164 Arguments:
2284
2165
2285 If arguments are given, the following possibilites exist:
2166 If arguments are given, the following possibilites exist:
2286
2167
2287 - The arguments are numbers or pairs of colon-separated numbers (like
2168 - The arguments are numbers or pairs of colon-separated numbers (like
2288 1 4:8 9). These are interpreted as lines of previous input to be
2169 1 4:8 9). These are interpreted as lines of previous input to be
2289 loaded into the editor. The syntax is the same of the %macro command.
2170 loaded into the editor. The syntax is the same of the %macro command.
2290
2171
2291 - If the argument doesn't start with a number, it is evaluated as a
2172 - If the argument doesn't start with a number, it is evaluated as a
2292 variable and its contents loaded into the editor. You can thus edit
2173 variable and its contents loaded into the editor. You can thus edit
2293 any string which contains python code (including the result of
2174 any string which contains python code (including the result of
2294 previous edits).
2175 previous edits).
2295
2176
2296 - If the argument is the name of an object (other than a string),
2177 - If the argument is the name of an object (other than a string),
2297 IPython will try to locate the file where it was defined and open the
2178 IPython will try to locate the file where it was defined and open the
2298 editor at the point where it is defined. You can use `%edit function`
2179 editor at the point where it is defined. You can use `%edit function`
2299 to load an editor exactly at the point where 'function' is defined,
2180 to load an editor exactly at the point where 'function' is defined,
2300 edit it and have the file be executed automatically.
2181 edit it and have the file be executed automatically.
2301
2182
2302 If the object is a macro (see %macro for details), this opens up your
2183 If the object is a macro (see %macro for details), this opens up your
2303 specified editor with a temporary file containing the macro's data.
2184 specified editor with a temporary file containing the macro's data.
2304 Upon exit, the macro is reloaded with the contents of the file.
2185 Upon exit, the macro is reloaded with the contents of the file.
2305
2186
2306 Note: opening at an exact line is only supported under Unix, and some
2187 Note: opening at an exact line is only supported under Unix, and some
2307 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2188 editors (like kedit and gedit up to Gnome 2.8) do not understand the
2308 '+NUMBER' parameter necessary for this feature. Good editors like
2189 '+NUMBER' parameter necessary for this feature. Good editors like
2309 (X)Emacs, vi, jed, pico and joe all do.
2190 (X)Emacs, vi, jed, pico and joe all do.
2310
2191
2311 - If the argument is not found as a variable, IPython will look for a
2192 - If the argument is not found as a variable, IPython will look for a
2312 file with that name (adding .py if necessary) and load it into the
2193 file with that name (adding .py if necessary) and load it into the
2313 editor. It will execute its contents with execfile() when you exit,
2194 editor. It will execute its contents with execfile() when you exit,
2314 loading any code in the file into your interactive namespace.
2195 loading any code in the file into your interactive namespace.
2315
2196
2316 After executing your code, %edit will return as output the code you
2197 After executing your code, %edit will return as output the code you
2317 typed in the editor (except when it was an existing file). This way
2198 typed in the editor (except when it was an existing file). This way
2318 you can reload the code in further invocations of %edit as a variable,
2199 you can reload the code in further invocations of %edit as a variable,
2319 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2200 via _<NUMBER> or Out[<NUMBER>], where <NUMBER> is the prompt number of
2320 the output.
2201 the output.
2321
2202
2322 Note that %edit is also available through the alias %ed.
2203 Note that %edit is also available through the alias %ed.
2323
2204
2324 This is an example of creating a simple function inside the editor and
2205 This is an example of creating a simple function inside the editor and
2325 then modifying it. First, start up the editor:
2206 then modifying it. First, start up the editor:
2326
2207
2327 In [1]: ed
2208 In [1]: ed
2328 Editing... done. Executing edited code...
2209 Editing... done. Executing edited code...
2329 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2210 Out[1]: 'def foo():n print "foo() was defined in an editing session"n'
2330
2211
2331 We can then call the function foo():
2212 We can then call the function foo():
2332
2213
2333 In [2]: foo()
2214 In [2]: foo()
2334 foo() was defined in an editing session
2215 foo() was defined in an editing session
2335
2216
2336 Now we edit foo. IPython automatically loads the editor with the
2217 Now we edit foo. IPython automatically loads the editor with the
2337 (temporary) file where foo() was previously defined:
2218 (temporary) file where foo() was previously defined:
2338
2219
2339 In [3]: ed foo
2220 In [3]: ed foo
2340 Editing... done. Executing edited code...
2221 Editing... done. Executing edited code...
2341
2222
2342 And if we call foo() again we get the modified version:
2223 And if we call foo() again we get the modified version:
2343
2224
2344 In [4]: foo()
2225 In [4]: foo()
2345 foo() has now been changed!
2226 foo() has now been changed!
2346
2227
2347 Here is an example of how to edit a code snippet successive
2228 Here is an example of how to edit a code snippet successive
2348 times. First we call the editor:
2229 times. First we call the editor:
2349
2230
2350 In [5]: ed
2231 In [5]: ed
2351 Editing... done. Executing edited code...
2232 Editing... done. Executing edited code...
2352 hello
2233 hello
2353 Out[5]: "print 'hello'n"
2234 Out[5]: "print 'hello'n"
2354
2235
2355 Now we call it again with the previous output (stored in _):
2236 Now we call it again with the previous output (stored in _):
2356
2237
2357 In [6]: ed _
2238 In [6]: ed _
2358 Editing... done. Executing edited code...
2239 Editing... done. Executing edited code...
2359 hello world
2240 hello world
2360 Out[6]: "print 'hello world'n"
2241 Out[6]: "print 'hello world'n"
2361
2242
2362 Now we call it with the output #8 (stored in _8, also as Out[8]):
2243 Now we call it with the output #8 (stored in _8, also as Out[8]):
2363
2244
2364 In [7]: ed _8
2245 In [7]: ed _8
2365 Editing... done. Executing edited code...
2246 Editing... done. Executing edited code...
2366 hello again
2247 hello again
2367 Out[7]: "print 'hello again'n"
2248 Out[7]: "print 'hello again'n"
2368
2249
2369
2250
2370 Changing the default editor hook:
2251 Changing the default editor hook:
2371
2252
2372 If you wish to write your own editor hook, you can put it in a
2253 If you wish to write your own editor hook, you can put it in a
2373 configuration file which you load at startup time. The default hook
2254 configuration file which you load at startup time. The default hook
2374 is defined in the IPython.core.hooks module, and you can use that as a
2255 is defined in the IPython.core.hooks module, and you can use that as a
2375 starting example for further modifications. That file also has
2256 starting example for further modifications. That file also has
2376 general instructions on how to set a new hook for use once you've
2257 general instructions on how to set a new hook for use once you've
2377 defined it."""
2258 defined it."""
2378
2259
2379 # FIXME: This function has become a convoluted mess. It needs a
2260 # FIXME: This function has become a convoluted mess. It needs a
2380 # ground-up rewrite with clean, simple logic.
2261 # ground-up rewrite with clean, simple logic.
2381
2262
2382 def make_filename(arg):
2263 def make_filename(arg):
2383 "Make a filename from the given args"
2264 "Make a filename from the given args"
2384 try:
2265 try:
2385 filename = get_py_filename(arg)
2266 filename = get_py_filename(arg)
2386 except IOError:
2267 except IOError:
2387 if args.endswith('.py'):
2268 if args.endswith('.py'):
2388 filename = arg
2269 filename = arg
2389 else:
2270 else:
2390 filename = None
2271 filename = None
2391 return filename
2272 return filename
2392
2273
2393 # custom exceptions
2274 # custom exceptions
2394 class DataIsObject(Exception): pass
2275 class DataIsObject(Exception): pass
2395
2276
2396 opts,args = self.parse_options(parameter_s,'prxn:')
2277 opts,args = self.parse_options(parameter_s,'prxn:')
2397 # Set a few locals from the options for convenience:
2278 # Set a few locals from the options for convenience:
2398 opts_p = opts.has_key('p')
2279 opts_p = opts.has_key('p')
2399 opts_r = opts.has_key('r')
2280 opts_r = opts.has_key('r')
2400
2281
2401 # Default line number value
2282 # Default line number value
2402 lineno = opts.get('n',None)
2283 lineno = opts.get('n',None)
2403
2284
2404 if opts_p:
2285 if opts_p:
2405 args = '_%s' % last_call[0]
2286 args = '_%s' % last_call[0]
2406 if not self.shell.user_ns.has_key(args):
2287 if not self.shell.user_ns.has_key(args):
2407 args = last_call[1]
2288 args = last_call[1]
2408
2289
2409 # use last_call to remember the state of the previous call, but don't
2290 # use last_call to remember the state of the previous call, but don't
2410 # let it be clobbered by successive '-p' calls.
2291 # let it be clobbered by successive '-p' calls.
2411 try:
2292 try:
2412 last_call[0] = self.shell.outputcache.prompt_count
2293 last_call[0] = self.shell.outputcache.prompt_count
2413 if not opts_p:
2294 if not opts_p:
2414 last_call[1] = parameter_s
2295 last_call[1] = parameter_s
2415 except:
2296 except:
2416 pass
2297 pass
2417
2298
2418 # by default this is done with temp files, except when the given
2299 # by default this is done with temp files, except when the given
2419 # arg is a filename
2300 # arg is a filename
2420 use_temp = 1
2301 use_temp = 1
2421
2302
2422 if re.match(r'\d',args):
2303 if re.match(r'\d',args):
2423 # Mode where user specifies ranges of lines, like in %macro.
2304 # Mode where user specifies ranges of lines, like in %macro.
2424 # This means that you can't edit files whose names begin with
2305 # This means that you can't edit files whose names begin with
2425 # numbers this way. Tough.
2306 # numbers this way. Tough.
2426 ranges = args.split()
2307 ranges = args.split()
2427 data = ''.join(self.extract_input_slices(ranges,opts_r))
2308 data = ''.join(self.extract_input_slices(ranges,opts_r))
2428 elif args.endswith('.py'):
2309 elif args.endswith('.py'):
2429 filename = make_filename(args)
2310 filename = make_filename(args)
2430 data = ''
2311 data = ''
2431 use_temp = 0
2312 use_temp = 0
2432 elif args:
2313 elif args:
2433 try:
2314 try:
2434 # Load the parameter given as a variable. If not a string,
2315 # Load the parameter given as a variable. If not a string,
2435 # process it as an object instead (below)
2316 # process it as an object instead (below)
2436
2317
2437 #print '*** args',args,'type',type(args) # dbg
2318 #print '*** args',args,'type',type(args) # dbg
2438 data = eval(args,self.shell.user_ns)
2319 data = eval(args,self.shell.user_ns)
2439 if not type(data) in StringTypes:
2320 if not type(data) in StringTypes:
2440 raise DataIsObject
2321 raise DataIsObject
2441
2322
2442 except (NameError,SyntaxError):
2323 except (NameError,SyntaxError):
2443 # given argument is not a variable, try as a filename
2324 # given argument is not a variable, try as a filename
2444 filename = make_filename(args)
2325 filename = make_filename(args)
2445 if filename is None:
2326 if filename is None:
2446 warn("Argument given (%s) can't be found as a variable "
2327 warn("Argument given (%s) can't be found as a variable "
2447 "or as a filename." % args)
2328 "or as a filename." % args)
2448 return
2329 return
2449
2330
2450 data = ''
2331 data = ''
2451 use_temp = 0
2332 use_temp = 0
2452 except DataIsObject:
2333 except DataIsObject:
2453
2334
2454 # macros have a special edit function
2335 # macros have a special edit function
2455 if isinstance(data,Macro):
2336 if isinstance(data,Macro):
2456 self._edit_macro(args,data)
2337 self._edit_macro(args,data)
2457 return
2338 return
2458
2339
2459 # For objects, try to edit the file where they are defined
2340 # For objects, try to edit the file where they are defined
2460 try:
2341 try:
2461 filename = inspect.getabsfile(data)
2342 filename = inspect.getabsfile(data)
2462 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2343 if 'fakemodule' in filename.lower() and inspect.isclass(data):
2463 # class created by %edit? Try to find source
2344 # class created by %edit? Try to find source
2464 # by looking for method definitions instead, the
2345 # by looking for method definitions instead, the
2465 # __module__ in those classes is FakeModule.
2346 # __module__ in those classes is FakeModule.
2466 attrs = [getattr(data, aname) for aname in dir(data)]
2347 attrs = [getattr(data, aname) for aname in dir(data)]
2467 for attr in attrs:
2348 for attr in attrs:
2468 if not inspect.ismethod(attr):
2349 if not inspect.ismethod(attr):
2469 continue
2350 continue
2470 filename = inspect.getabsfile(attr)
2351 filename = inspect.getabsfile(attr)
2471 if filename and 'fakemodule' not in filename.lower():
2352 if filename and 'fakemodule' not in filename.lower():
2472 # change the attribute to be the edit target instead
2353 # change the attribute to be the edit target instead
2473 data = attr
2354 data = attr
2474 break
2355 break
2475
2356
2476 datafile = 1
2357 datafile = 1
2477 except TypeError:
2358 except TypeError:
2478 filename = make_filename(args)
2359 filename = make_filename(args)
2479 datafile = 1
2360 datafile = 1
2480 warn('Could not find file where `%s` is defined.\n'
2361 warn('Could not find file where `%s` is defined.\n'
2481 'Opening a file named `%s`' % (args,filename))
2362 'Opening a file named `%s`' % (args,filename))
2482 # Now, make sure we can actually read the source (if it was in
2363 # Now, make sure we can actually read the source (if it was in
2483 # a temp file it's gone by now).
2364 # a temp file it's gone by now).
2484 if datafile:
2365 if datafile:
2485 try:
2366 try:
2486 if lineno is None:
2367 if lineno is None:
2487 lineno = inspect.getsourcelines(data)[1]
2368 lineno = inspect.getsourcelines(data)[1]
2488 except IOError:
2369 except IOError:
2489 filename = make_filename(args)
2370 filename = make_filename(args)
2490 if filename is None:
2371 if filename is None:
2491 warn('The file `%s` where `%s` was defined cannot '
2372 warn('The file `%s` where `%s` was defined cannot '
2492 'be read.' % (filename,data))
2373 'be read.' % (filename,data))
2493 return
2374 return
2494 use_temp = 0
2375 use_temp = 0
2495 else:
2376 else:
2496 data = ''
2377 data = ''
2497
2378
2498 if use_temp:
2379 if use_temp:
2499 filename = self.shell.mktempfile(data)
2380 filename = self.shell.mktempfile(data)
2500 print 'IPython will make a temporary file named:',filename
2381 print 'IPython will make a temporary file named:',filename
2501
2382
2502 # do actual editing here
2383 # do actual editing here
2503 print 'Editing...',
2384 print 'Editing...',
2504 sys.stdout.flush()
2385 sys.stdout.flush()
2505 try:
2386 try:
2506 self.shell.hooks.editor(filename,lineno)
2387 self.shell.hooks.editor(filename,lineno)
2507 except TryNext:
2388 except TryNext:
2508 warn('Could not open editor')
2389 warn('Could not open editor')
2509 return
2390 return
2510
2391
2511 # XXX TODO: should this be generalized for all string vars?
2392 # XXX TODO: should this be generalized for all string vars?
2512 # For now, this is special-cased to blocks created by cpaste
2393 # For now, this is special-cased to blocks created by cpaste
2513 if args.strip() == 'pasted_block':
2394 if args.strip() == 'pasted_block':
2514 self.shell.user_ns['pasted_block'] = file_read(filename)
2395 self.shell.user_ns['pasted_block'] = file_read(filename)
2515
2396
2516 if opts.has_key('x'): # -x prevents actual execution
2397 if opts.has_key('x'): # -x prevents actual execution
2517 print
2398 print
2518 else:
2399 else:
2519 print 'done. Executing edited code...'
2400 print 'done. Executing edited code...'
2520 if opts_r:
2401 if opts_r:
2521 self.shell.runlines(file_read(filename))
2402 self.shell.runlines(file_read(filename))
2522 else:
2403 else:
2523 self.shell.safe_execfile(filename,self.shell.user_ns,
2404 self.shell.safe_execfile(filename,self.shell.user_ns,
2524 self.shell.user_ns)
2405 self.shell.user_ns)
2525
2406
2526
2407
2527 if use_temp:
2408 if use_temp:
2528 try:
2409 try:
2529 return open(filename).read()
2410 return open(filename).read()
2530 except IOError,msg:
2411 except IOError,msg:
2531 if msg.filename == filename:
2412 if msg.filename == filename:
2532 warn('File not found. Did you forget to save?')
2413 warn('File not found. Did you forget to save?')
2533 return
2414 return
2534 else:
2415 else:
2535 self.shell.showtraceback()
2416 self.shell.showtraceback()
2536
2417
2537 def magic_xmode(self,parameter_s = ''):
2418 def magic_xmode(self,parameter_s = ''):
2538 """Switch modes for the exception handlers.
2419 """Switch modes for the exception handlers.
2539
2420
2540 Valid modes: Plain, Context and Verbose.
2421 Valid modes: Plain, Context and Verbose.
2541
2422
2542 If called without arguments, acts as a toggle."""
2423 If called without arguments, acts as a toggle."""
2543
2424
2544 def xmode_switch_err(name):
2425 def xmode_switch_err(name):
2545 warn('Error changing %s exception modes.\n%s' %
2426 warn('Error changing %s exception modes.\n%s' %
2546 (name,sys.exc_info()[1]))
2427 (name,sys.exc_info()[1]))
2547
2428
2548 shell = self.shell
2429 shell = self.shell
2549 new_mode = parameter_s.strip().capitalize()
2430 new_mode = parameter_s.strip().capitalize()
2550 try:
2431 try:
2551 shell.InteractiveTB.set_mode(mode=new_mode)
2432 shell.InteractiveTB.set_mode(mode=new_mode)
2552 print 'Exception reporting mode:',shell.InteractiveTB.mode
2433 print 'Exception reporting mode:',shell.InteractiveTB.mode
2553 except:
2434 except:
2554 xmode_switch_err('user')
2435 xmode_switch_err('user')
2555
2436
2556 # threaded shells use a special handler in sys.excepthook
2437 # threaded shells use a special handler in sys.excepthook
2557 if shell.isthreaded:
2438 if shell.isthreaded:
2558 try:
2439 try:
2559 shell.sys_excepthook.set_mode(mode=new_mode)
2440 shell.sys_excepthook.set_mode(mode=new_mode)
2560 except:
2441 except:
2561 xmode_switch_err('threaded')
2442 xmode_switch_err('threaded')
2562
2443
2563 def magic_colors(self,parameter_s = ''):
2444 def magic_colors(self,parameter_s = ''):
2564 """Switch color scheme for prompts, info system and exception handlers.
2445 """Switch color scheme for prompts, info system and exception handlers.
2565
2446
2566 Currently implemented schemes: NoColor, Linux, LightBG.
2447 Currently implemented schemes: NoColor, Linux, LightBG.
2567
2448
2568 Color scheme names are not case-sensitive."""
2449 Color scheme names are not case-sensitive."""
2569
2450
2570 def color_switch_err(name):
2451 def color_switch_err(name):
2571 warn('Error changing %s color schemes.\n%s' %
2452 warn('Error changing %s color schemes.\n%s' %
2572 (name,sys.exc_info()[1]))
2453 (name,sys.exc_info()[1]))
2573
2454
2574
2455
2575 new_scheme = parameter_s.strip()
2456 new_scheme = parameter_s.strip()
2576 if not new_scheme:
2457 if not new_scheme:
2577 raise UsageError(
2458 raise UsageError(
2578 "%colors: you must specify a color scheme. See '%colors?'")
2459 "%colors: you must specify a color scheme. See '%colors?'")
2579 return
2460 return
2580 # local shortcut
2461 # local shortcut
2581 shell = self.shell
2462 shell = self.shell
2582
2463
2583 import IPython.utils.rlineimpl as readline
2464 import IPython.utils.rlineimpl as readline
2584
2465
2585 if not readline.have_readline and sys.platform == "win32":
2466 if not readline.have_readline and sys.platform == "win32":
2586 msg = """\
2467 msg = """\
2587 Proper color support under MS Windows requires the pyreadline library.
2468 Proper color support under MS Windows requires the pyreadline library.
2588 You can find it at:
2469 You can find it at:
2589 http://ipython.scipy.org/moin/PyReadline/Intro
2470 http://ipython.scipy.org/moin/PyReadline/Intro
2590 Gary's readline needs the ctypes module, from:
2471 Gary's readline needs the ctypes module, from:
2591 http://starship.python.net/crew/theller/ctypes
2472 http://starship.python.net/crew/theller/ctypes
2592 (Note that ctypes is already part of Python versions 2.5 and newer).
2473 (Note that ctypes is already part of Python versions 2.5 and newer).
2593
2474
2594 Defaulting color scheme to 'NoColor'"""
2475 Defaulting color scheme to 'NoColor'"""
2595 new_scheme = 'NoColor'
2476 new_scheme = 'NoColor'
2596 warn(msg)
2477 warn(msg)
2597
2478
2598 # readline option is 0
2479 # readline option is 0
2599 if not shell.has_readline:
2480 if not shell.has_readline:
2600 new_scheme = 'NoColor'
2481 new_scheme = 'NoColor'
2601
2482
2602 # Set prompt colors
2483 # Set prompt colors
2603 try:
2484 try:
2604 shell.outputcache.set_colors(new_scheme)
2485 shell.outputcache.set_colors(new_scheme)
2605 except:
2486 except:
2606 color_switch_err('prompt')
2487 color_switch_err('prompt')
2607 else:
2488 else:
2608 shell.colors = \
2489 shell.colors = \
2609 shell.outputcache.color_table.active_scheme_name
2490 shell.outputcache.color_table.active_scheme_name
2610 # Set exception colors
2491 # Set exception colors
2611 try:
2492 try:
2612 shell.InteractiveTB.set_colors(scheme = new_scheme)
2493 shell.InteractiveTB.set_colors(scheme = new_scheme)
2613 shell.SyntaxTB.set_colors(scheme = new_scheme)
2494 shell.SyntaxTB.set_colors(scheme = new_scheme)
2614 except:
2495 except:
2615 color_switch_err('exception')
2496 color_switch_err('exception')
2616
2497
2617 # threaded shells use a verbose traceback in sys.excepthook
2498 # threaded shells use a verbose traceback in sys.excepthook
2618 if shell.isthreaded:
2499 if shell.isthreaded:
2619 try:
2500 try:
2620 shell.sys_excepthook.set_colors(scheme=new_scheme)
2501 shell.sys_excepthook.set_colors(scheme=new_scheme)
2621 except:
2502 except:
2622 color_switch_err('system exception handler')
2503 color_switch_err('system exception handler')
2623
2504
2624 # Set info (for 'object?') colors
2505 # Set info (for 'object?') colors
2625 if shell.color_info:
2506 if shell.color_info:
2626 try:
2507 try:
2627 shell.inspector.set_active_scheme(new_scheme)
2508 shell.inspector.set_active_scheme(new_scheme)
2628 except:
2509 except:
2629 color_switch_err('object inspector')
2510 color_switch_err('object inspector')
2630 else:
2511 else:
2631 shell.inspector.set_active_scheme('NoColor')
2512 shell.inspector.set_active_scheme('NoColor')
2632
2513
2633 def magic_color_info(self,parameter_s = ''):
2514 def magic_color_info(self,parameter_s = ''):
2634 """Toggle color_info.
2515 """Toggle color_info.
2635
2516
2636 The color_info configuration parameter controls whether colors are
2517 The color_info configuration parameter controls whether colors are
2637 used for displaying object details (by things like %psource, %pfile or
2518 used for displaying object details (by things like %psource, %pfile or
2638 the '?' system). This function toggles this value with each call.
2519 the '?' system). This function toggles this value with each call.
2639
2520
2640 Note that unless you have a fairly recent pager (less works better
2521 Note that unless you have a fairly recent pager (less works better
2641 than more) in your system, using colored object information displays
2522 than more) in your system, using colored object information displays
2642 will not work properly. Test it and see."""
2523 will not work properly. Test it and see."""
2643
2524
2644 self.shell.color_info = not self.shell.color_info
2525 self.shell.color_info = not self.shell.color_info
2645 self.magic_colors(self.shell.colors)
2526 self.magic_colors(self.shell.colors)
2646 print 'Object introspection functions have now coloring:',
2527 print 'Object introspection functions have now coloring:',
2647 print ['OFF','ON'][int(self.shell.color_info)]
2528 print ['OFF','ON'][int(self.shell.color_info)]
2648
2529
2649 def magic_Pprint(self, parameter_s=''):
2530 def magic_Pprint(self, parameter_s=''):
2650 """Toggle pretty printing on/off."""
2531 """Toggle pretty printing on/off."""
2651
2532
2652 self.shell.pprint = 1 - self.shell.pprint
2533 self.shell.pprint = 1 - self.shell.pprint
2653 print 'Pretty printing has been turned', \
2534 print 'Pretty printing has been turned', \
2654 ['OFF','ON'][self.shell.pprint]
2535 ['OFF','ON'][self.shell.pprint]
2655
2536
2656 def magic_exit(self, parameter_s=''):
2537 def magic_exit(self, parameter_s=''):
2657 """Exit IPython, confirming if configured to do so.
2538 """Exit IPython, confirming if configured to do so.
2658
2539
2659 You can configure whether IPython asks for confirmation upon exit by
2540 You can configure whether IPython asks for confirmation upon exit by
2660 setting the confirm_exit flag in the ipythonrc file."""
2541 setting the confirm_exit flag in the ipythonrc file."""
2661
2542
2662 self.shell.exit()
2543 self.shell.exit()
2663
2544
2664 def magic_quit(self, parameter_s=''):
2545 def magic_quit(self, parameter_s=''):
2665 """Exit IPython, confirming if configured to do so (like %exit)"""
2546 """Exit IPython, confirming if configured to do so (like %exit)"""
2666
2547
2667 self.shell.exit()
2548 self.shell.exit()
2668
2549
2669 def magic_Exit(self, parameter_s=''):
2550 def magic_Exit(self, parameter_s=''):
2670 """Exit IPython without confirmation."""
2551 """Exit IPython without confirmation."""
2671
2552
2672 self.shell.ask_exit()
2553 self.shell.ask_exit()
2673
2554
2674 #......................................................................
2555 #......................................................................
2675 # Functions to implement unix shell-type things
2556 # Functions to implement unix shell-type things
2676
2557
2677 @testdec.skip_doctest
2558 @testdec.skip_doctest
2678 def magic_alias(self, parameter_s = ''):
2559 def magic_alias(self, parameter_s = ''):
2679 """Define an alias for a system command.
2560 """Define an alias for a system command.
2680
2561
2681 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2562 '%alias alias_name cmd' defines 'alias_name' as an alias for 'cmd'
2682
2563
2683 Then, typing 'alias_name params' will execute the system command 'cmd
2564 Then, typing 'alias_name params' will execute the system command 'cmd
2684 params' (from your underlying operating system).
2565 params' (from your underlying operating system).
2685
2566
2686 Aliases have lower precedence than magic functions and Python normal
2567 Aliases have lower precedence than magic functions and Python normal
2687 variables, so if 'foo' is both a Python variable and an alias, the
2568 variables, so if 'foo' is both a Python variable and an alias, the
2688 alias can not be executed until 'del foo' removes the Python variable.
2569 alias can not be executed until 'del foo' removes the Python variable.
2689
2570
2690 You can use the %l specifier in an alias definition to represent the
2571 You can use the %l specifier in an alias definition to represent the
2691 whole line when the alias is called. For example:
2572 whole line when the alias is called. For example:
2692
2573
2693 In [2]: alias all echo "Input in brackets: <%l>"
2574 In [2]: alias all echo "Input in brackets: <%l>"
2694 In [3]: all hello world
2575 In [3]: all hello world
2695 Input in brackets: <hello world>
2576 Input in brackets: <hello world>
2696
2577
2697 You can also define aliases with parameters using %s specifiers (one
2578 You can also define aliases with parameters using %s specifiers (one
2698 per parameter):
2579 per parameter):
2699
2580
2700 In [1]: alias parts echo first %s second %s
2581 In [1]: alias parts echo first %s second %s
2701 In [2]: %parts A B
2582 In [2]: %parts A B
2702 first A second B
2583 first A second B
2703 In [3]: %parts A
2584 In [3]: %parts A
2704 Incorrect number of arguments: 2 expected.
2585 Incorrect number of arguments: 2 expected.
2705 parts is an alias to: 'echo first %s second %s'
2586 parts is an alias to: 'echo first %s second %s'
2706
2587
2707 Note that %l and %s are mutually exclusive. You can only use one or
2588 Note that %l and %s are mutually exclusive. You can only use one or
2708 the other in your aliases.
2589 the other in your aliases.
2709
2590
2710 Aliases expand Python variables just like system calls using ! or !!
2591 Aliases expand Python variables just like system calls using ! or !!
2711 do: all expressions prefixed with '$' get expanded. For details of
2592 do: all expressions prefixed with '$' get expanded. For details of
2712 the semantic rules, see PEP-215:
2593 the semantic rules, see PEP-215:
2713 http://www.python.org/peps/pep-0215.html. This is the library used by
2594 http://www.python.org/peps/pep-0215.html. This is the library used by
2714 IPython for variable expansion. If you want to access a true shell
2595 IPython for variable expansion. If you want to access a true shell
2715 variable, an extra $ is necessary to prevent its expansion by IPython:
2596 variable, an extra $ is necessary to prevent its expansion by IPython:
2716
2597
2717 In [6]: alias show echo
2598 In [6]: alias show echo
2718 In [7]: PATH='A Python string'
2599 In [7]: PATH='A Python string'
2719 In [8]: show $PATH
2600 In [8]: show $PATH
2720 A Python string
2601 A Python string
2721 In [9]: show $$PATH
2602 In [9]: show $$PATH
2722 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2603 /usr/local/lf9560/bin:/usr/local/intel/compiler70/ia32/bin:...
2723
2604
2724 You can use the alias facility to acess all of $PATH. See the %rehash
2605 You can use the alias facility to acess all of $PATH. See the %rehash
2725 and %rehashx functions, which automatically create aliases for the
2606 and %rehashx functions, which automatically create aliases for the
2726 contents of your $PATH.
2607 contents of your $PATH.
2727
2608
2728 If called with no parameters, %alias prints the current alias table."""
2609 If called with no parameters, %alias prints the current alias table."""
2729
2610
2730 par = parameter_s.strip()
2611 par = parameter_s.strip()
2731 if not par:
2612 if not par:
2732 stored = self.db.get('stored_aliases', {} )
2613 stored = self.db.get('stored_aliases', {} )
2733 aliases = sorted(self.shell.alias_manager.aliases)
2614 aliases = sorted(self.shell.alias_manager.aliases)
2734 # for k, v in stored:
2615 # for k, v in stored:
2735 # atab.append(k, v[0])
2616 # atab.append(k, v[0])
2736
2617
2737 print "Total number of aliases:", len(aliases)
2618 print "Total number of aliases:", len(aliases)
2738 return aliases
2619 return aliases
2739
2620
2740 # Now try to define a new one
2621 # Now try to define a new one
2741 try:
2622 try:
2742 alias,cmd = par.split(None, 1)
2623 alias,cmd = par.split(None, 1)
2743 except:
2624 except:
2744 print oinspect.getdoc(self.magic_alias)
2625 print oinspect.getdoc(self.magic_alias)
2745 else:
2626 else:
2746 self.shell.alias_manager.soft_define_alias(alias, cmd)
2627 self.shell.alias_manager.soft_define_alias(alias, cmd)
2747 # end magic_alias
2628 # end magic_alias
2748
2629
2749 def magic_unalias(self, parameter_s = ''):
2630 def magic_unalias(self, parameter_s = ''):
2750 """Remove an alias"""
2631 """Remove an alias"""
2751
2632
2752 aname = parameter_s.strip()
2633 aname = parameter_s.strip()
2753 self.shell.alias_manager.undefine_alias(aname)
2634 self.shell.alias_manager.undefine_alias(aname)
2754 stored = self.db.get('stored_aliases', {} )
2635 stored = self.db.get('stored_aliases', {} )
2755 if aname in stored:
2636 if aname in stored:
2756 print "Removing %stored alias",aname
2637 print "Removing %stored alias",aname
2757 del stored[aname]
2638 del stored[aname]
2758 self.db['stored_aliases'] = stored
2639 self.db['stored_aliases'] = stored
2759
2640
2760
2641
2761 def magic_rehashx(self, parameter_s = ''):
2642 def magic_rehashx(self, parameter_s = ''):
2762 """Update the alias table with all executable files in $PATH.
2643 """Update the alias table with all executable files in $PATH.
2763
2644
2764 This version explicitly checks that every entry in $PATH is a file
2645 This version explicitly checks that every entry in $PATH is a file
2765 with execute access (os.X_OK), so it is much slower than %rehash.
2646 with execute access (os.X_OK), so it is much slower than %rehash.
2766
2647
2767 Under Windows, it checks executability as a match agains a
2648 Under Windows, it checks executability as a match agains a
2768 '|'-separated string of extensions, stored in the IPython config
2649 '|'-separated string of extensions, stored in the IPython config
2769 variable win_exec_ext. This defaults to 'exe|com|bat'.
2650 variable win_exec_ext. This defaults to 'exe|com|bat'.
2770
2651
2771 This function also resets the root module cache of module completer,
2652 This function also resets the root module cache of module completer,
2772 used on slow filesystems.
2653 used on slow filesystems.
2773 """
2654 """
2774 from IPython.core.alias import InvalidAliasError
2655 from IPython.core.alias import InvalidAliasError
2775
2656
2776 # for the benefit of module completer in ipy_completers.py
2657 # for the benefit of module completer in ipy_completers.py
2777 del self.db['rootmodules']
2658 del self.db['rootmodules']
2778
2659
2779 path = [os.path.abspath(os.path.expanduser(p)) for p in
2660 path = [os.path.abspath(os.path.expanduser(p)) for p in
2780 os.environ.get('PATH','').split(os.pathsep)]
2661 os.environ.get('PATH','').split(os.pathsep)]
2781 path = filter(os.path.isdir,path)
2662 path = filter(os.path.isdir,path)
2782
2663
2783 syscmdlist = []
2664 syscmdlist = []
2784 # Now define isexec in a cross platform manner.
2665 # Now define isexec in a cross platform manner.
2785 if os.name == 'posix':
2666 if os.name == 'posix':
2786 isexec = lambda fname:os.path.isfile(fname) and \
2667 isexec = lambda fname:os.path.isfile(fname) and \
2787 os.access(fname,os.X_OK)
2668 os.access(fname,os.X_OK)
2788 else:
2669 else:
2789 try:
2670 try:
2790 winext = os.environ['pathext'].replace(';','|').replace('.','')
2671 winext = os.environ['pathext'].replace(';','|').replace('.','')
2791 except KeyError:
2672 except KeyError:
2792 winext = 'exe|com|bat|py'
2673 winext = 'exe|com|bat|py'
2793 if 'py' not in winext:
2674 if 'py' not in winext:
2794 winext += '|py'
2675 winext += '|py'
2795 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2676 execre = re.compile(r'(.*)\.(%s)$' % winext,re.IGNORECASE)
2796 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2677 isexec = lambda fname:os.path.isfile(fname) and execre.match(fname)
2797 savedir = os.getcwd()
2678 savedir = os.getcwd()
2798
2679
2799 # Now walk the paths looking for executables to alias.
2680 # Now walk the paths looking for executables to alias.
2800 try:
2681 try:
2801 # write the whole loop for posix/Windows so we don't have an if in
2682 # write the whole loop for posix/Windows so we don't have an if in
2802 # the innermost part
2683 # the innermost part
2803 if os.name == 'posix':
2684 if os.name == 'posix':
2804 for pdir in path:
2685 for pdir in path:
2805 os.chdir(pdir)
2686 os.chdir(pdir)
2806 for ff in os.listdir(pdir):
2687 for ff in os.listdir(pdir):
2807 if isexec(ff):
2688 if isexec(ff):
2808 try:
2689 try:
2809 # Removes dots from the name since ipython
2690 # Removes dots from the name since ipython
2810 # will assume names with dots to be python.
2691 # will assume names with dots to be python.
2811 self.shell.alias_manager.define_alias(
2692 self.shell.alias_manager.define_alias(
2812 ff.replace('.',''), ff)
2693 ff.replace('.',''), ff)
2813 except InvalidAliasError:
2694 except InvalidAliasError:
2814 pass
2695 pass
2815 else:
2696 else:
2816 syscmdlist.append(ff)
2697 syscmdlist.append(ff)
2817 else:
2698 else:
2818 for pdir in path:
2699 for pdir in path:
2819 os.chdir(pdir)
2700 os.chdir(pdir)
2820 for ff in os.listdir(pdir):
2701 for ff in os.listdir(pdir):
2821 base, ext = os.path.splitext(ff)
2702 base, ext = os.path.splitext(ff)
2822 if isexec(ff) and base.lower() not in self.shell.no_alias:
2703 if isexec(ff) and base.lower() not in self.shell.no_alias:
2823 if ext.lower() == '.exe':
2704 if ext.lower() == '.exe':
2824 ff = base
2705 ff = base
2825 try:
2706 try:
2826 # Removes dots from the name since ipython
2707 # Removes dots from the name since ipython
2827 # will assume names with dots to be python.
2708 # will assume names with dots to be python.
2828 self.shell.alias_manager.define_alias(
2709 self.shell.alias_manager.define_alias(
2829 base.lower().replace('.',''), ff)
2710 base.lower().replace('.',''), ff)
2830 except InvalidAliasError:
2711 except InvalidAliasError:
2831 pass
2712 pass
2832 syscmdlist.append(ff)
2713 syscmdlist.append(ff)
2833 db = self.db
2714 db = self.db
2834 db['syscmdlist'] = syscmdlist
2715 db['syscmdlist'] = syscmdlist
2835 finally:
2716 finally:
2836 os.chdir(savedir)
2717 os.chdir(savedir)
2837
2718
2838 def magic_pwd(self, parameter_s = ''):
2719 def magic_pwd(self, parameter_s = ''):
2839 """Return the current working directory path."""
2720 """Return the current working directory path."""
2840 return os.getcwd()
2721 return os.getcwd()
2841
2722
2842 def magic_cd(self, parameter_s=''):
2723 def magic_cd(self, parameter_s=''):
2843 """Change the current working directory.
2724 """Change the current working directory.
2844
2725
2845 This command automatically maintains an internal list of directories
2726 This command automatically maintains an internal list of directories
2846 you visit during your IPython session, in the variable _dh. The
2727 you visit during your IPython session, in the variable _dh. The
2847 command %dhist shows this history nicely formatted. You can also
2728 command %dhist shows this history nicely formatted. You can also
2848 do 'cd -<tab>' to see directory history conveniently.
2729 do 'cd -<tab>' to see directory history conveniently.
2849
2730
2850 Usage:
2731 Usage:
2851
2732
2852 cd 'dir': changes to directory 'dir'.
2733 cd 'dir': changes to directory 'dir'.
2853
2734
2854 cd -: changes to the last visited directory.
2735 cd -: changes to the last visited directory.
2855
2736
2856 cd -<n>: changes to the n-th directory in the directory history.
2737 cd -<n>: changes to the n-th directory in the directory history.
2857
2738
2858 cd --foo: change to directory that matches 'foo' in history
2739 cd --foo: change to directory that matches 'foo' in history
2859
2740
2860 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2741 cd -b <bookmark_name>: jump to a bookmark set by %bookmark
2861 (note: cd <bookmark_name> is enough if there is no
2742 (note: cd <bookmark_name> is enough if there is no
2862 directory <bookmark_name>, but a bookmark with the name exists.)
2743 directory <bookmark_name>, but a bookmark with the name exists.)
2863 'cd -b <tab>' allows you to tab-complete bookmark names.
2744 'cd -b <tab>' allows you to tab-complete bookmark names.
2864
2745
2865 Options:
2746 Options:
2866
2747
2867 -q: quiet. Do not print the working directory after the cd command is
2748 -q: quiet. Do not print the working directory after the cd command is
2868 executed. By default IPython's cd command does print this directory,
2749 executed. By default IPython's cd command does print this directory,
2869 since the default prompts do not display path information.
2750 since the default prompts do not display path information.
2870
2751
2871 Note that !cd doesn't work for this purpose because the shell where
2752 Note that !cd doesn't work for this purpose because the shell where
2872 !command runs is immediately discarded after executing 'command'."""
2753 !command runs is immediately discarded after executing 'command'."""
2873
2754
2874 parameter_s = parameter_s.strip()
2755 parameter_s = parameter_s.strip()
2875 #bkms = self.shell.persist.get("bookmarks",{})
2756 #bkms = self.shell.persist.get("bookmarks",{})
2876
2757
2877 oldcwd = os.getcwd()
2758 oldcwd = os.getcwd()
2878 numcd = re.match(r'(-)(\d+)$',parameter_s)
2759 numcd = re.match(r'(-)(\d+)$',parameter_s)
2879 # jump in directory history by number
2760 # jump in directory history by number
2880 if numcd:
2761 if numcd:
2881 nn = int(numcd.group(2))
2762 nn = int(numcd.group(2))
2882 try:
2763 try:
2883 ps = self.shell.user_ns['_dh'][nn]
2764 ps = self.shell.user_ns['_dh'][nn]
2884 except IndexError:
2765 except IndexError:
2885 print 'The requested directory does not exist in history.'
2766 print 'The requested directory does not exist in history.'
2886 return
2767 return
2887 else:
2768 else:
2888 opts = {}
2769 opts = {}
2889 elif parameter_s.startswith('--'):
2770 elif parameter_s.startswith('--'):
2890 ps = None
2771 ps = None
2891 fallback = None
2772 fallback = None
2892 pat = parameter_s[2:]
2773 pat = parameter_s[2:]
2893 dh = self.shell.user_ns['_dh']
2774 dh = self.shell.user_ns['_dh']
2894 # first search only by basename (last component)
2775 # first search only by basename (last component)
2895 for ent in reversed(dh):
2776 for ent in reversed(dh):
2896 if pat in os.path.basename(ent) and os.path.isdir(ent):
2777 if pat in os.path.basename(ent) and os.path.isdir(ent):
2897 ps = ent
2778 ps = ent
2898 break
2779 break
2899
2780
2900 if fallback is None and pat in ent and os.path.isdir(ent):
2781 if fallback is None and pat in ent and os.path.isdir(ent):
2901 fallback = ent
2782 fallback = ent
2902
2783
2903 # if we have no last part match, pick the first full path match
2784 # if we have no last part match, pick the first full path match
2904 if ps is None:
2785 if ps is None:
2905 ps = fallback
2786 ps = fallback
2906
2787
2907 if ps is None:
2788 if ps is None:
2908 print "No matching entry in directory history"
2789 print "No matching entry in directory history"
2909 return
2790 return
2910 else:
2791 else:
2911 opts = {}
2792 opts = {}
2912
2793
2913
2794
2914 else:
2795 else:
2915 #turn all non-space-escaping backslashes to slashes,
2796 #turn all non-space-escaping backslashes to slashes,
2916 # for c:\windows\directory\names\
2797 # for c:\windows\directory\names\
2917 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2798 parameter_s = re.sub(r'\\(?! )','/', parameter_s)
2918 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2799 opts,ps = self.parse_options(parameter_s,'qb',mode='string')
2919 # jump to previous
2800 # jump to previous
2920 if ps == '-':
2801 if ps == '-':
2921 try:
2802 try:
2922 ps = self.shell.user_ns['_dh'][-2]
2803 ps = self.shell.user_ns['_dh'][-2]
2923 except IndexError:
2804 except IndexError:
2924 raise UsageError('%cd -: No previous directory to change to.')
2805 raise UsageError('%cd -: No previous directory to change to.')
2925 # jump to bookmark if needed
2806 # jump to bookmark if needed
2926 else:
2807 else:
2927 if not os.path.isdir(ps) or opts.has_key('b'):
2808 if not os.path.isdir(ps) or opts.has_key('b'):
2928 bkms = self.db.get('bookmarks', {})
2809 bkms = self.db.get('bookmarks', {})
2929
2810
2930 if bkms.has_key(ps):
2811 if bkms.has_key(ps):
2931 target = bkms[ps]
2812 target = bkms[ps]
2932 print '(bookmark:%s) -> %s' % (ps,target)
2813 print '(bookmark:%s) -> %s' % (ps,target)
2933 ps = target
2814 ps = target
2934 else:
2815 else:
2935 if opts.has_key('b'):
2816 if opts.has_key('b'):
2936 raise UsageError("Bookmark '%s' not found. "
2817 raise UsageError("Bookmark '%s' not found. "
2937 "Use '%%bookmark -l' to see your bookmarks." % ps)
2818 "Use '%%bookmark -l' to see your bookmarks." % ps)
2938
2819
2939 # at this point ps should point to the target dir
2820 # at this point ps should point to the target dir
2940 if ps:
2821 if ps:
2941 try:
2822 try:
2942 os.chdir(os.path.expanduser(ps))
2823 os.chdir(os.path.expanduser(ps))
2943 if self.shell.term_title:
2824 if self.shell.term_title:
2944 platutils.set_term_title('IPython: ' + abbrev_cwd())
2825 platutils.set_term_title('IPython: ' + abbrev_cwd())
2945 except OSError:
2826 except OSError:
2946 print sys.exc_info()[1]
2827 print sys.exc_info()[1]
2947 else:
2828 else:
2948 cwd = os.getcwd()
2829 cwd = os.getcwd()
2949 dhist = self.shell.user_ns['_dh']
2830 dhist = self.shell.user_ns['_dh']
2950 if oldcwd != cwd:
2831 if oldcwd != cwd:
2951 dhist.append(cwd)
2832 dhist.append(cwd)
2952 self.db['dhist'] = compress_dhist(dhist)[-100:]
2833 self.db['dhist'] = compress_dhist(dhist)[-100:]
2953
2834
2954 else:
2835 else:
2955 os.chdir(self.shell.home_dir)
2836 os.chdir(self.shell.home_dir)
2956 if self.shell.term_title:
2837 if self.shell.term_title:
2957 platutils.set_term_title('IPython: ' + '~')
2838 platutils.set_term_title('IPython: ' + '~')
2958 cwd = os.getcwd()
2839 cwd = os.getcwd()
2959 dhist = self.shell.user_ns['_dh']
2840 dhist = self.shell.user_ns['_dh']
2960
2841
2961 if oldcwd != cwd:
2842 if oldcwd != cwd:
2962 dhist.append(cwd)
2843 dhist.append(cwd)
2963 self.db['dhist'] = compress_dhist(dhist)[-100:]
2844 self.db['dhist'] = compress_dhist(dhist)[-100:]
2964 if not 'q' in opts and self.shell.user_ns['_dh']:
2845 if not 'q' in opts and self.shell.user_ns['_dh']:
2965 print self.shell.user_ns['_dh'][-1]
2846 print self.shell.user_ns['_dh'][-1]
2966
2847
2967
2848
2968 def magic_env(self, parameter_s=''):
2849 def magic_env(self, parameter_s=''):
2969 """List environment variables."""
2850 """List environment variables."""
2970
2851
2971 return os.environ.data
2852 return os.environ.data
2972
2853
2973 def magic_pushd(self, parameter_s=''):
2854 def magic_pushd(self, parameter_s=''):
2974 """Place the current dir on stack and change directory.
2855 """Place the current dir on stack and change directory.
2975
2856
2976 Usage:\\
2857 Usage:\\
2977 %pushd ['dirname']
2858 %pushd ['dirname']
2978 """
2859 """
2979
2860
2980 dir_s = self.shell.dir_stack
2861 dir_s = self.shell.dir_stack
2981 tgt = os.path.expanduser(parameter_s)
2862 tgt = os.path.expanduser(parameter_s)
2982 cwd = os.getcwd().replace(self.home_dir,'~')
2863 cwd = os.getcwd().replace(self.home_dir,'~')
2983 if tgt:
2864 if tgt:
2984 self.magic_cd(parameter_s)
2865 self.magic_cd(parameter_s)
2985 dir_s.insert(0,cwd)
2866 dir_s.insert(0,cwd)
2986 return self.magic_dirs()
2867 return self.magic_dirs()
2987
2868
2988 def magic_popd(self, parameter_s=''):
2869 def magic_popd(self, parameter_s=''):
2989 """Change to directory popped off the top of the stack.
2870 """Change to directory popped off the top of the stack.
2990 """
2871 """
2991 if not self.shell.dir_stack:
2872 if not self.shell.dir_stack:
2992 raise UsageError("%popd on empty stack")
2873 raise UsageError("%popd on empty stack")
2993 top = self.shell.dir_stack.pop(0)
2874 top = self.shell.dir_stack.pop(0)
2994 self.magic_cd(top)
2875 self.magic_cd(top)
2995 print "popd ->",top
2876 print "popd ->",top
2996
2877
2997 def magic_dirs(self, parameter_s=''):
2878 def magic_dirs(self, parameter_s=''):
2998 """Return the current directory stack."""
2879 """Return the current directory stack."""
2999
2880
3000 return self.shell.dir_stack
2881 return self.shell.dir_stack
3001
2882
3002 def magic_dhist(self, parameter_s=''):
2883 def magic_dhist(self, parameter_s=''):
3003 """Print your history of visited directories.
2884 """Print your history of visited directories.
3004
2885
3005 %dhist -> print full history\\
2886 %dhist -> print full history\\
3006 %dhist n -> print last n entries only\\
2887 %dhist n -> print last n entries only\\
3007 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
2888 %dhist n1 n2 -> print entries between n1 and n2 (n1 not included)\\
3008
2889
3009 This history is automatically maintained by the %cd command, and
2890 This history is automatically maintained by the %cd command, and
3010 always available as the global list variable _dh. You can use %cd -<n>
2891 always available as the global list variable _dh. You can use %cd -<n>
3011 to go to directory number <n>.
2892 to go to directory number <n>.
3012
2893
3013 Note that most of time, you should view directory history by entering
2894 Note that most of time, you should view directory history by entering
3014 cd -<TAB>.
2895 cd -<TAB>.
3015
2896
3016 """
2897 """
3017
2898
3018 dh = self.shell.user_ns['_dh']
2899 dh = self.shell.user_ns['_dh']
3019 if parameter_s:
2900 if parameter_s:
3020 try:
2901 try:
3021 args = map(int,parameter_s.split())
2902 args = map(int,parameter_s.split())
3022 except:
2903 except:
3023 self.arg_err(Magic.magic_dhist)
2904 self.arg_err(Magic.magic_dhist)
3024 return
2905 return
3025 if len(args) == 1:
2906 if len(args) == 1:
3026 ini,fin = max(len(dh)-(args[0]),0),len(dh)
2907 ini,fin = max(len(dh)-(args[0]),0),len(dh)
3027 elif len(args) == 2:
2908 elif len(args) == 2:
3028 ini,fin = args
2909 ini,fin = args
3029 else:
2910 else:
3030 self.arg_err(Magic.magic_dhist)
2911 self.arg_err(Magic.magic_dhist)
3031 return
2912 return
3032 else:
2913 else:
3033 ini,fin = 0,len(dh)
2914 ini,fin = 0,len(dh)
3034 nlprint(dh,
2915 nlprint(dh,
3035 header = 'Directory history (kept in _dh)',
2916 header = 'Directory history (kept in _dh)',
3036 start=ini,stop=fin)
2917 start=ini,stop=fin)
3037
2918
3038 @testdec.skip_doctest
2919 @testdec.skip_doctest
3039 def magic_sc(self, parameter_s=''):
2920 def magic_sc(self, parameter_s=''):
3040 """Shell capture - execute a shell command and capture its output.
2921 """Shell capture - execute a shell command and capture its output.
3041
2922
3042 DEPRECATED. Suboptimal, retained for backwards compatibility.
2923 DEPRECATED. Suboptimal, retained for backwards compatibility.
3043
2924
3044 You should use the form 'var = !command' instead. Example:
2925 You should use the form 'var = !command' instead. Example:
3045
2926
3046 "%sc -l myfiles = ls ~" should now be written as
2927 "%sc -l myfiles = ls ~" should now be written as
3047
2928
3048 "myfiles = !ls ~"
2929 "myfiles = !ls ~"
3049
2930
3050 myfiles.s, myfiles.l and myfiles.n still apply as documented
2931 myfiles.s, myfiles.l and myfiles.n still apply as documented
3051 below.
2932 below.
3052
2933
3053 --
2934 --
3054 %sc [options] varname=command
2935 %sc [options] varname=command
3055
2936
3056 IPython will run the given command using commands.getoutput(), and
2937 IPython will run the given command using commands.getoutput(), and
3057 will then update the user's interactive namespace with a variable
2938 will then update the user's interactive namespace with a variable
3058 called varname, containing the value of the call. Your command can
2939 called varname, containing the value of the call. Your command can
3059 contain shell wildcards, pipes, etc.
2940 contain shell wildcards, pipes, etc.
3060
2941
3061 The '=' sign in the syntax is mandatory, and the variable name you
2942 The '=' sign in the syntax is mandatory, and the variable name you
3062 supply must follow Python's standard conventions for valid names.
2943 supply must follow Python's standard conventions for valid names.
3063
2944
3064 (A special format without variable name exists for internal use)
2945 (A special format without variable name exists for internal use)
3065
2946
3066 Options:
2947 Options:
3067
2948
3068 -l: list output. Split the output on newlines into a list before
2949 -l: list output. Split the output on newlines into a list before
3069 assigning it to the given variable. By default the output is stored
2950 assigning it to the given variable. By default the output is stored
3070 as a single string.
2951 as a single string.
3071
2952
3072 -v: verbose. Print the contents of the variable.
2953 -v: verbose. Print the contents of the variable.
3073
2954
3074 In most cases you should not need to split as a list, because the
2955 In most cases you should not need to split as a list, because the
3075 returned value is a special type of string which can automatically
2956 returned value is a special type of string which can automatically
3076 provide its contents either as a list (split on newlines) or as a
2957 provide its contents either as a list (split on newlines) or as a
3077 space-separated string. These are convenient, respectively, either
2958 space-separated string. These are convenient, respectively, either
3078 for sequential processing or to be passed to a shell command.
2959 for sequential processing or to be passed to a shell command.
3079
2960
3080 For example:
2961 For example:
3081
2962
3082 # all-random
2963 # all-random
3083
2964
3084 # Capture into variable a
2965 # Capture into variable a
3085 In [1]: sc a=ls *py
2966 In [1]: sc a=ls *py
3086
2967
3087 # a is a string with embedded newlines
2968 # a is a string with embedded newlines
3088 In [2]: a
2969 In [2]: a
3089 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
2970 Out[2]: 'setup.py\\nwin32_manual_post_install.py'
3090
2971
3091 # which can be seen as a list:
2972 # which can be seen as a list:
3092 In [3]: a.l
2973 In [3]: a.l
3093 Out[3]: ['setup.py', 'win32_manual_post_install.py']
2974 Out[3]: ['setup.py', 'win32_manual_post_install.py']
3094
2975
3095 # or as a whitespace-separated string:
2976 # or as a whitespace-separated string:
3096 In [4]: a.s
2977 In [4]: a.s
3097 Out[4]: 'setup.py win32_manual_post_install.py'
2978 Out[4]: 'setup.py win32_manual_post_install.py'
3098
2979
3099 # a.s is useful to pass as a single command line:
2980 # a.s is useful to pass as a single command line:
3100 In [5]: !wc -l $a.s
2981 In [5]: !wc -l $a.s
3101 146 setup.py
2982 146 setup.py
3102 130 win32_manual_post_install.py
2983 130 win32_manual_post_install.py
3103 276 total
2984 276 total
3104
2985
3105 # while the list form is useful to loop over:
2986 # while the list form is useful to loop over:
3106 In [6]: for f in a.l:
2987 In [6]: for f in a.l:
3107 ...: !wc -l $f
2988 ...: !wc -l $f
3108 ...:
2989 ...:
3109 146 setup.py
2990 146 setup.py
3110 130 win32_manual_post_install.py
2991 130 win32_manual_post_install.py
3111
2992
3112 Similiarly, the lists returned by the -l option are also special, in
2993 Similiarly, the lists returned by the -l option are also special, in
3113 the sense that you can equally invoke the .s attribute on them to
2994 the sense that you can equally invoke the .s attribute on them to
3114 automatically get a whitespace-separated string from their contents:
2995 automatically get a whitespace-separated string from their contents:
3115
2996
3116 In [7]: sc -l b=ls *py
2997 In [7]: sc -l b=ls *py
3117
2998
3118 In [8]: b
2999 In [8]: b
3119 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3000 Out[8]: ['setup.py', 'win32_manual_post_install.py']
3120
3001
3121 In [9]: b.s
3002 In [9]: b.s
3122 Out[9]: 'setup.py win32_manual_post_install.py'
3003 Out[9]: 'setup.py win32_manual_post_install.py'
3123
3004
3124 In summary, both the lists and strings used for ouptut capture have
3005 In summary, both the lists and strings used for ouptut capture have
3125 the following special attributes:
3006 the following special attributes:
3126
3007
3127 .l (or .list) : value as list.
3008 .l (or .list) : value as list.
3128 .n (or .nlstr): value as newline-separated string.
3009 .n (or .nlstr): value as newline-separated string.
3129 .s (or .spstr): value as space-separated string.
3010 .s (or .spstr): value as space-separated string.
3130 """
3011 """
3131
3012
3132 opts,args = self.parse_options(parameter_s,'lv')
3013 opts,args = self.parse_options(parameter_s,'lv')
3133 # Try to get a variable name and command to run
3014 # Try to get a variable name and command to run
3134 try:
3015 try:
3135 # the variable name must be obtained from the parse_options
3016 # the variable name must be obtained from the parse_options
3136 # output, which uses shlex.split to strip options out.
3017 # output, which uses shlex.split to strip options out.
3137 var,_ = args.split('=',1)
3018 var,_ = args.split('=',1)
3138 var = var.strip()
3019 var = var.strip()
3139 # But the the command has to be extracted from the original input
3020 # But the the command has to be extracted from the original input
3140 # parameter_s, not on what parse_options returns, to avoid the
3021 # parameter_s, not on what parse_options returns, to avoid the
3141 # quote stripping which shlex.split performs on it.
3022 # quote stripping which shlex.split performs on it.
3142 _,cmd = parameter_s.split('=',1)
3023 _,cmd = parameter_s.split('=',1)
3143 except ValueError:
3024 except ValueError:
3144 var,cmd = '',''
3025 var,cmd = '',''
3145 # If all looks ok, proceed
3026 # If all looks ok, proceed
3146 out,err = self.shell.getoutputerror(cmd)
3027 out,err = self.shell.getoutputerror(cmd)
3147 if err:
3028 if err:
3148 print >> Term.cerr,err
3029 print >> Term.cerr,err
3149 if opts.has_key('l'):
3030 if opts.has_key('l'):
3150 out = SList(out.split('\n'))
3031 out = SList(out.split('\n'))
3151 else:
3032 else:
3152 out = LSString(out)
3033 out = LSString(out)
3153 if opts.has_key('v'):
3034 if opts.has_key('v'):
3154 print '%s ==\n%s' % (var,pformat(out))
3035 print '%s ==\n%s' % (var,pformat(out))
3155 if var:
3036 if var:
3156 self.shell.user_ns.update({var:out})
3037 self.shell.user_ns.update({var:out})
3157 else:
3038 else:
3158 return out
3039 return out
3159
3040
3160 def magic_sx(self, parameter_s=''):
3041 def magic_sx(self, parameter_s=''):
3161 """Shell execute - run a shell command and capture its output.
3042 """Shell execute - run a shell command and capture its output.
3162
3043
3163 %sx command
3044 %sx command
3164
3045
3165 IPython will run the given command using commands.getoutput(), and
3046 IPython will run the given command using commands.getoutput(), and
3166 return the result formatted as a list (split on '\\n'). Since the
3047 return the result formatted as a list (split on '\\n'). Since the
3167 output is _returned_, it will be stored in ipython's regular output
3048 output is _returned_, it will be stored in ipython's regular output
3168 cache Out[N] and in the '_N' automatic variables.
3049 cache Out[N] and in the '_N' automatic variables.
3169
3050
3170 Notes:
3051 Notes:
3171
3052
3172 1) If an input line begins with '!!', then %sx is automatically
3053 1) If an input line begins with '!!', then %sx is automatically
3173 invoked. That is, while:
3054 invoked. That is, while:
3174 !ls
3055 !ls
3175 causes ipython to simply issue system('ls'), typing
3056 causes ipython to simply issue system('ls'), typing
3176 !!ls
3057 !!ls
3177 is a shorthand equivalent to:
3058 is a shorthand equivalent to:
3178 %sx ls
3059 %sx ls
3179
3060
3180 2) %sx differs from %sc in that %sx automatically splits into a list,
3061 2) %sx differs from %sc in that %sx automatically splits into a list,
3181 like '%sc -l'. The reason for this is to make it as easy as possible
3062 like '%sc -l'. The reason for this is to make it as easy as possible
3182 to process line-oriented shell output via further python commands.
3063 to process line-oriented shell output via further python commands.
3183 %sc is meant to provide much finer control, but requires more
3064 %sc is meant to provide much finer control, but requires more
3184 typing.
3065 typing.
3185
3066
3186 3) Just like %sc -l, this is a list with special attributes:
3067 3) Just like %sc -l, this is a list with special attributes:
3187
3068
3188 .l (or .list) : value as list.
3069 .l (or .list) : value as list.
3189 .n (or .nlstr): value as newline-separated string.
3070 .n (or .nlstr): value as newline-separated string.
3190 .s (or .spstr): value as whitespace-separated string.
3071 .s (or .spstr): value as whitespace-separated string.
3191
3072
3192 This is very useful when trying to use such lists as arguments to
3073 This is very useful when trying to use such lists as arguments to
3193 system commands."""
3074 system commands."""
3194
3075
3195 if parameter_s:
3076 if parameter_s:
3196 out,err = self.shell.getoutputerror(parameter_s)
3077 out,err = self.shell.getoutputerror(parameter_s)
3197 if err:
3078 if err:
3198 print >> Term.cerr,err
3079 print >> Term.cerr,err
3199 return SList(out.split('\n'))
3080 return SList(out.split('\n'))
3200
3081
3201 def magic_bg(self, parameter_s=''):
3082 def magic_bg(self, parameter_s=''):
3202 """Run a job in the background, in a separate thread.
3083 """Run a job in the background, in a separate thread.
3203
3084
3204 For example,
3085 For example,
3205
3086
3206 %bg myfunc(x,y,z=1)
3087 %bg myfunc(x,y,z=1)
3207
3088
3208 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3089 will execute 'myfunc(x,y,z=1)' in a background thread. As soon as the
3209 execution starts, a message will be printed indicating the job
3090 execution starts, a message will be printed indicating the job
3210 number. If your job number is 5, you can use
3091 number. If your job number is 5, you can use
3211
3092
3212 myvar = jobs.result(5) or myvar = jobs[5].result
3093 myvar = jobs.result(5) or myvar = jobs[5].result
3213
3094
3214 to assign this result to variable 'myvar'.
3095 to assign this result to variable 'myvar'.
3215
3096
3216 IPython has a job manager, accessible via the 'jobs' object. You can
3097 IPython has a job manager, accessible via the 'jobs' object. You can
3217 type jobs? to get more information about it, and use jobs.<TAB> to see
3098 type jobs? to get more information about it, and use jobs.<TAB> to see
3218 its attributes. All attributes not starting with an underscore are
3099 its attributes. All attributes not starting with an underscore are
3219 meant for public use.
3100 meant for public use.
3220
3101
3221 In particular, look at the jobs.new() method, which is used to create
3102 In particular, look at the jobs.new() method, which is used to create
3222 new jobs. This magic %bg function is just a convenience wrapper
3103 new jobs. This magic %bg function is just a convenience wrapper
3223 around jobs.new(), for expression-based jobs. If you want to create a
3104 around jobs.new(), for expression-based jobs. If you want to create a
3224 new job with an explicit function object and arguments, you must call
3105 new job with an explicit function object and arguments, you must call
3225 jobs.new() directly.
3106 jobs.new() directly.
3226
3107
3227 The jobs.new docstring also describes in detail several important
3108 The jobs.new docstring also describes in detail several important
3228 caveats associated with a thread-based model for background job
3109 caveats associated with a thread-based model for background job
3229 execution. Type jobs.new? for details.
3110 execution. Type jobs.new? for details.
3230
3111
3231 You can check the status of all jobs with jobs.status().
3112 You can check the status of all jobs with jobs.status().
3232
3113
3233 The jobs variable is set by IPython into the Python builtin namespace.
3114 The jobs variable is set by IPython into the Python builtin namespace.
3234 If you ever declare a variable named 'jobs', you will shadow this
3115 If you ever declare a variable named 'jobs', you will shadow this
3235 name. You can either delete your global jobs variable to regain
3116 name. You can either delete your global jobs variable to regain
3236 access to the job manager, or make a new name and assign it manually
3117 access to the job manager, or make a new name and assign it manually
3237 to the manager (stored in IPython's namespace). For example, to
3118 to the manager (stored in IPython's namespace). For example, to
3238 assign the job manager to the Jobs name, use:
3119 assign the job manager to the Jobs name, use:
3239
3120
3240 Jobs = __builtins__.jobs"""
3121 Jobs = __builtins__.jobs"""
3241
3122
3242 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3123 self.shell.jobs.new(parameter_s,self.shell.user_ns)
3243
3124
3244 def magic_r(self, parameter_s=''):
3125 def magic_r(self, parameter_s=''):
3245 """Repeat previous input.
3126 """Repeat previous input.
3246
3127
3247 Note: Consider using the more powerfull %rep instead!
3128 Note: Consider using the more powerfull %rep instead!
3248
3129
3249 If given an argument, repeats the previous command which starts with
3130 If given an argument, repeats the previous command which starts with
3250 the same string, otherwise it just repeats the previous input.
3131 the same string, otherwise it just repeats the previous input.
3251
3132
3252 Shell escaped commands (with ! as first character) are not recognized
3133 Shell escaped commands (with ! as first character) are not recognized
3253 by this system, only pure python code and magic commands.
3134 by this system, only pure python code and magic commands.
3254 """
3135 """
3255
3136
3256 start = parameter_s.strip()
3137 start = parameter_s.strip()
3257 esc_magic = ESC_MAGIC
3138 esc_magic = ESC_MAGIC
3258 # Identify magic commands even if automagic is on (which means
3139 # Identify magic commands even if automagic is on (which means
3259 # the in-memory version is different from that typed by the user).
3140 # the in-memory version is different from that typed by the user).
3260 if self.shell.automagic:
3141 if self.shell.automagic:
3261 start_magic = esc_magic+start
3142 start_magic = esc_magic+start
3262 else:
3143 else:
3263 start_magic = start
3144 start_magic = start
3264 # Look through the input history in reverse
3145 # Look through the input history in reverse
3265 for n in range(len(self.shell.input_hist)-2,0,-1):
3146 for n in range(len(self.shell.input_hist)-2,0,-1):
3266 input = self.shell.input_hist[n]
3147 input = self.shell.input_hist[n]
3267 # skip plain 'r' lines so we don't recurse to infinity
3148 # skip plain 'r' lines so we don't recurse to infinity
3268 if input != '_ip.magic("r")\n' and \
3149 if input != '_ip.magic("r")\n' and \
3269 (input.startswith(start) or input.startswith(start_magic)):
3150 (input.startswith(start) or input.startswith(start_magic)):
3270 #print 'match',`input` # dbg
3151 #print 'match',`input` # dbg
3271 print 'Executing:',input,
3152 print 'Executing:',input,
3272 self.shell.runlines(input)
3153 self.shell.runlines(input)
3273 return
3154 return
3274 print 'No previous input matching `%s` found.' % start
3155 print 'No previous input matching `%s` found.' % start
3275
3156
3276
3157
3277 def magic_bookmark(self, parameter_s=''):
3158 def magic_bookmark(self, parameter_s=''):
3278 """Manage IPython's bookmark system.
3159 """Manage IPython's bookmark system.
3279
3160
3280 %bookmark <name> - set bookmark to current dir
3161 %bookmark <name> - set bookmark to current dir
3281 %bookmark <name> <dir> - set bookmark to <dir>
3162 %bookmark <name> <dir> - set bookmark to <dir>
3282 %bookmark -l - list all bookmarks
3163 %bookmark -l - list all bookmarks
3283 %bookmark -d <name> - remove bookmark
3164 %bookmark -d <name> - remove bookmark
3284 %bookmark -r - remove all bookmarks
3165 %bookmark -r - remove all bookmarks
3285
3166
3286 You can later on access a bookmarked folder with:
3167 You can later on access a bookmarked folder with:
3287 %cd -b <name>
3168 %cd -b <name>
3288 or simply '%cd <name>' if there is no directory called <name> AND
3169 or simply '%cd <name>' if there is no directory called <name> AND
3289 there is such a bookmark defined.
3170 there is such a bookmark defined.
3290
3171
3291 Your bookmarks persist through IPython sessions, but they are
3172 Your bookmarks persist through IPython sessions, but they are
3292 associated with each profile."""
3173 associated with each profile."""
3293
3174
3294 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3175 opts,args = self.parse_options(parameter_s,'drl',mode='list')
3295 if len(args) > 2:
3176 if len(args) > 2:
3296 raise UsageError("%bookmark: too many arguments")
3177 raise UsageError("%bookmark: too many arguments")
3297
3178
3298 bkms = self.db.get('bookmarks',{})
3179 bkms = self.db.get('bookmarks',{})
3299
3180
3300 if opts.has_key('d'):
3181 if opts.has_key('d'):
3301 try:
3182 try:
3302 todel = args[0]
3183 todel = args[0]
3303 except IndexError:
3184 except IndexError:
3304 raise UsageError(
3185 raise UsageError(
3305 "%bookmark -d: must provide a bookmark to delete")
3186 "%bookmark -d: must provide a bookmark to delete")
3306 else:
3187 else:
3307 try:
3188 try:
3308 del bkms[todel]
3189 del bkms[todel]
3309 except KeyError:
3190 except KeyError:
3310 raise UsageError(
3191 raise UsageError(
3311 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3192 "%%bookmark -d: Can't delete bookmark '%s'" % todel)
3312
3193
3313 elif opts.has_key('r'):
3194 elif opts.has_key('r'):
3314 bkms = {}
3195 bkms = {}
3315 elif opts.has_key('l'):
3196 elif opts.has_key('l'):
3316 bks = bkms.keys()
3197 bks = bkms.keys()
3317 bks.sort()
3198 bks.sort()
3318 if bks:
3199 if bks:
3319 size = max(map(len,bks))
3200 size = max(map(len,bks))
3320 else:
3201 else:
3321 size = 0
3202 size = 0
3322 fmt = '%-'+str(size)+'s -> %s'
3203 fmt = '%-'+str(size)+'s -> %s'
3323 print 'Current bookmarks:'
3204 print 'Current bookmarks:'
3324 for bk in bks:
3205 for bk in bks:
3325 print fmt % (bk,bkms[bk])
3206 print fmt % (bk,bkms[bk])
3326 else:
3207 else:
3327 if not args:
3208 if not args:
3328 raise UsageError("%bookmark: You must specify the bookmark name")
3209 raise UsageError("%bookmark: You must specify the bookmark name")
3329 elif len(args)==1:
3210 elif len(args)==1:
3330 bkms[args[0]] = os.getcwd()
3211 bkms[args[0]] = os.getcwd()
3331 elif len(args)==2:
3212 elif len(args)==2:
3332 bkms[args[0]] = args[1]
3213 bkms[args[0]] = args[1]
3333 self.db['bookmarks'] = bkms
3214 self.db['bookmarks'] = bkms
3334
3215
3335 def magic_pycat(self, parameter_s=''):
3216 def magic_pycat(self, parameter_s=''):
3336 """Show a syntax-highlighted file through a pager.
3217 """Show a syntax-highlighted file through a pager.
3337
3218
3338 This magic is similar to the cat utility, but it will assume the file
3219 This magic is similar to the cat utility, but it will assume the file
3339 to be Python source and will show it with syntax highlighting. """
3220 to be Python source and will show it with syntax highlighting. """
3340
3221
3341 try:
3222 try:
3342 filename = get_py_filename(parameter_s)
3223 filename = get_py_filename(parameter_s)
3343 cont = file_read(filename)
3224 cont = file_read(filename)
3344 except IOError:
3225 except IOError:
3345 try:
3226 try:
3346 cont = eval(parameter_s,self.user_ns)
3227 cont = eval(parameter_s,self.user_ns)
3347 except NameError:
3228 except NameError:
3348 cont = None
3229 cont = None
3349 if cont is None:
3230 if cont is None:
3350 print "Error: no such file or variable"
3231 print "Error: no such file or variable"
3351 return
3232 return
3352
3233
3353 page(self.shell.pycolorize(cont),
3234 page(self.shell.pycolorize(cont),
3354 screen_lines=self.shell.usable_screen_length)
3235 screen_lines=self.shell.usable_screen_length)
3355
3236
3356 def _rerun_pasted(self):
3237 def _rerun_pasted(self):
3357 """ Rerun a previously pasted command.
3238 """ Rerun a previously pasted command.
3358 """
3239 """
3359 b = self.user_ns.get('pasted_block', None)
3240 b = self.user_ns.get('pasted_block', None)
3360 if b is None:
3241 if b is None:
3361 raise UsageError('No previous pasted block available')
3242 raise UsageError('No previous pasted block available')
3362 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3243 print "Re-executing '%s...' (%d chars)"% (b.split('\n',1)[0], len(b))
3363 exec b in self.user_ns
3244 exec b in self.user_ns
3364
3245
3365 def _get_pasted_lines(self, sentinel):
3246 def _get_pasted_lines(self, sentinel):
3366 """ Yield pasted lines until the user enters the given sentinel value.
3247 """ Yield pasted lines until the user enters the given sentinel value.
3367 """
3248 """
3368 from IPython.core import iplib
3249 from IPython.core import iplib
3369 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3250 print "Pasting code; enter '%s' alone on the line to stop." % sentinel
3370 while True:
3251 while True:
3371 l = iplib.raw_input_original(':')
3252 l = iplib.raw_input_original(':')
3372 if l == sentinel:
3253 if l == sentinel:
3373 return
3254 return
3374 else:
3255 else:
3375 yield l
3256 yield l
3376
3257
3377 def _strip_pasted_lines_for_code(self, raw_lines):
3258 def _strip_pasted_lines_for_code(self, raw_lines):
3378 """ Strip non-code parts of a sequence of lines to return a block of
3259 """ Strip non-code parts of a sequence of lines to return a block of
3379 code.
3260 code.
3380 """
3261 """
3381 # Regular expressions that declare text we strip from the input:
3262 # Regular expressions that declare text we strip from the input:
3382 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3263 strip_re = [r'^\s*In \[\d+\]:', # IPython input prompt
3383 r'^\s*(\s?>)+', # Python input prompt
3264 r'^\s*(\s?>)+', # Python input prompt
3384 r'^\s*\.{3,}', # Continuation prompts
3265 r'^\s*\.{3,}', # Continuation prompts
3385 r'^\++',
3266 r'^\++',
3386 ]
3267 ]
3387
3268
3388 strip_from_start = map(re.compile,strip_re)
3269 strip_from_start = map(re.compile,strip_re)
3389
3270
3390 lines = []
3271 lines = []
3391 for l in raw_lines:
3272 for l in raw_lines:
3392 for pat in strip_from_start:
3273 for pat in strip_from_start:
3393 l = pat.sub('',l)
3274 l = pat.sub('',l)
3394 lines.append(l)
3275 lines.append(l)
3395
3276
3396 block = "\n".join(lines) + '\n'
3277 block = "\n".join(lines) + '\n'
3397 #print "block:\n",block
3278 #print "block:\n",block
3398 return block
3279 return block
3399
3280
3400 def _execute_block(self, block, par):
3281 def _execute_block(self, block, par):
3401 """ Execute a block, or store it in a variable, per the user's request.
3282 """ Execute a block, or store it in a variable, per the user's request.
3402 """
3283 """
3403 if not par:
3284 if not par:
3404 b = textwrap.dedent(block)
3285 b = textwrap.dedent(block)
3405 self.user_ns['pasted_block'] = b
3286 self.user_ns['pasted_block'] = b
3406 exec b in self.user_ns
3287 exec b in self.user_ns
3407 else:
3288 else:
3408 self.user_ns[par] = SList(block.splitlines())
3289 self.user_ns[par] = SList(block.splitlines())
3409 print "Block assigned to '%s'" % par
3290 print "Block assigned to '%s'" % par
3410
3291
3411 def magic_cpaste(self, parameter_s=''):
3292 def magic_cpaste(self, parameter_s=''):
3412 """Allows you to paste & execute a pre-formatted code block from clipboard.
3293 """Allows you to paste & execute a pre-formatted code block from clipboard.
3413
3294
3414 You must terminate the block with '--' (two minus-signs) alone on the
3295 You must terminate the block with '--' (two minus-signs) alone on the
3415 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3296 line. You can also provide your own sentinel with '%paste -s %%' ('%%'
3416 is the new sentinel for this operation)
3297 is the new sentinel for this operation)
3417
3298
3418 The block is dedented prior to execution to enable execution of method
3299 The block is dedented prior to execution to enable execution of method
3419 definitions. '>' and '+' characters at the beginning of a line are
3300 definitions. '>' and '+' characters at the beginning of a line are
3420 ignored, to allow pasting directly from e-mails, diff files and
3301 ignored, to allow pasting directly from e-mails, diff files and
3421 doctests (the '...' continuation prompt is also stripped). The
3302 doctests (the '...' continuation prompt is also stripped). The
3422 executed block is also assigned to variable named 'pasted_block' for
3303 executed block is also assigned to variable named 'pasted_block' for
3423 later editing with '%edit pasted_block'.
3304 later editing with '%edit pasted_block'.
3424
3305
3425 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3306 You can also pass a variable name as an argument, e.g. '%cpaste foo'.
3426 This assigns the pasted block to variable 'foo' as string, without
3307 This assigns the pasted block to variable 'foo' as string, without
3427 dedenting or executing it (preceding >>> and + is still stripped)
3308 dedenting or executing it (preceding >>> and + is still stripped)
3428
3309
3429 '%cpaste -r' re-executes the block previously entered by cpaste.
3310 '%cpaste -r' re-executes the block previously entered by cpaste.
3430
3311
3431 Do not be alarmed by garbled output on Windows (it's a readline bug).
3312 Do not be alarmed by garbled output on Windows (it's a readline bug).
3432 Just press enter and type -- (and press enter again) and the block
3313 Just press enter and type -- (and press enter again) and the block
3433 will be what was just pasted.
3314 will be what was just pasted.
3434
3315
3435 IPython statements (magics, shell escapes) are not supported (yet).
3316 IPython statements (magics, shell escapes) are not supported (yet).
3436
3317
3437 See also
3318 See also
3438 --------
3319 --------
3439 paste: automatically pull code from clipboard.
3320 paste: automatically pull code from clipboard.
3440 """
3321 """
3441
3322
3442 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3323 opts,args = self.parse_options(parameter_s,'rs:',mode='string')
3443 par = args.strip()
3324 par = args.strip()
3444 if opts.has_key('r'):
3325 if opts.has_key('r'):
3445 self._rerun_pasted()
3326 self._rerun_pasted()
3446 return
3327 return
3447
3328
3448 sentinel = opts.get('s','--')
3329 sentinel = opts.get('s','--')
3449
3330
3450 block = self._strip_pasted_lines_for_code(
3331 block = self._strip_pasted_lines_for_code(
3451 self._get_pasted_lines(sentinel))
3332 self._get_pasted_lines(sentinel))
3452
3333
3453 self._execute_block(block, par)
3334 self._execute_block(block, par)
3454
3335
3455 def magic_paste(self, parameter_s=''):
3336 def magic_paste(self, parameter_s=''):
3456 """Allows you to paste & execute a pre-formatted code block from clipboard.
3337 """Allows you to paste & execute a pre-formatted code block from clipboard.
3457
3338
3458 The text is pulled directly from the clipboard without user
3339 The text is pulled directly from the clipboard without user
3459 intervention and printed back on the screen before execution (unless
3340 intervention and printed back on the screen before execution (unless
3460 the -q flag is given to force quiet mode).
3341 the -q flag is given to force quiet mode).
3461
3342
3462 The block is dedented prior to execution to enable execution of method
3343 The block is dedented prior to execution to enable execution of method
3463 definitions. '>' and '+' characters at the beginning of a line are
3344 definitions. '>' and '+' characters at the beginning of a line are
3464 ignored, to allow pasting directly from e-mails, diff files and
3345 ignored, to allow pasting directly from e-mails, diff files and
3465 doctests (the '...' continuation prompt is also stripped). The
3346 doctests (the '...' continuation prompt is also stripped). The
3466 executed block is also assigned to variable named 'pasted_block' for
3347 executed block is also assigned to variable named 'pasted_block' for
3467 later editing with '%edit pasted_block'.
3348 later editing with '%edit pasted_block'.
3468
3349
3469 You can also pass a variable name as an argument, e.g. '%paste foo'.
3350 You can also pass a variable name as an argument, e.g. '%paste foo'.
3470 This assigns the pasted block to variable 'foo' as string, without
3351 This assigns the pasted block to variable 'foo' as string, without
3471 dedenting or executing it (preceding >>> and + is still stripped)
3352 dedenting or executing it (preceding >>> and + is still stripped)
3472
3353
3473 Options
3354 Options
3474 -------
3355 -------
3475
3356
3476 -r: re-executes the block previously entered by cpaste.
3357 -r: re-executes the block previously entered by cpaste.
3477
3358
3478 -q: quiet mode: do not echo the pasted text back to the terminal.
3359 -q: quiet mode: do not echo the pasted text back to the terminal.
3479
3360
3480 IPython statements (magics, shell escapes) are not supported (yet).
3361 IPython statements (magics, shell escapes) are not supported (yet).
3481
3362
3482 See also
3363 See also
3483 --------
3364 --------
3484 cpaste: manually paste code into terminal until you mark its end.
3365 cpaste: manually paste code into terminal until you mark its end.
3485 """
3366 """
3486 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3367 opts,args = self.parse_options(parameter_s,'rq',mode='string')
3487 par = args.strip()
3368 par = args.strip()
3488 if opts.has_key('r'):
3369 if opts.has_key('r'):
3489 self._rerun_pasted()
3370 self._rerun_pasted()
3490 return
3371 return
3491
3372
3492 text = self.shell.hooks.clipboard_get()
3373 text = self.shell.hooks.clipboard_get()
3493 block = self._strip_pasted_lines_for_code(text.splitlines())
3374 block = self._strip_pasted_lines_for_code(text.splitlines())
3494
3375
3495 # By default, echo back to terminal unless quiet mode is requested
3376 # By default, echo back to terminal unless quiet mode is requested
3496 if not opts.has_key('q'):
3377 if not opts.has_key('q'):
3497 write = self.shell.write
3378 write = self.shell.write
3498 write(self.shell.pycolorize(block))
3379 write(self.shell.pycolorize(block))
3499 if not block.endswith('\n'):
3380 if not block.endswith('\n'):
3500 write('\n')
3381 write('\n')
3501 write("## -- End pasted text --\n")
3382 write("## -- End pasted text --\n")
3502
3383
3503 self._execute_block(block, par)
3384 self._execute_block(block, par)
3504
3385
3505 def magic_quickref(self,arg):
3386 def magic_quickref(self,arg):
3506 """ Show a quick reference sheet """
3387 """ Show a quick reference sheet """
3507 import IPython.core.usage
3388 import IPython.core.usage
3508 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3389 qr = IPython.core.usage.quick_reference + self.magic_magic('-brief')
3509
3390
3510 page(qr)
3391 page(qr)
3511
3392
3512 def magic_doctest_mode(self,parameter_s=''):
3393 def magic_doctest_mode(self,parameter_s=''):
3513 """Toggle doctest mode on and off.
3394 """Toggle doctest mode on and off.
3514
3395
3515 This mode allows you to toggle the prompt behavior between normal
3396 This mode allows you to toggle the prompt behavior between normal
3516 IPython prompts and ones that are as similar to the default IPython
3397 IPython prompts and ones that are as similar to the default IPython
3517 interpreter as possible.
3398 interpreter as possible.
3518
3399
3519 It also supports the pasting of code snippets that have leading '>>>'
3400 It also supports the pasting of code snippets that have leading '>>>'
3520 and '...' prompts in them. This means that you can paste doctests from
3401 and '...' prompts in them. This means that you can paste doctests from
3521 files or docstrings (even if they have leading whitespace), and the
3402 files or docstrings (even if they have leading whitespace), and the
3522 code will execute correctly. You can then use '%history -tn' to see
3403 code will execute correctly. You can then use '%history -tn' to see
3523 the translated history without line numbers; this will give you the
3404 the translated history without line numbers; this will give you the
3524 input after removal of all the leading prompts and whitespace, which
3405 input after removal of all the leading prompts and whitespace, which
3525 can be pasted back into an editor.
3406 can be pasted back into an editor.
3526
3407
3527 With these features, you can switch into this mode easily whenever you
3408 With these features, you can switch into this mode easily whenever you
3528 need to do testing and changes to doctests, without having to leave
3409 need to do testing and changes to doctests, without having to leave
3529 your existing IPython session.
3410 your existing IPython session.
3530 """
3411 """
3531
3412
3532 # XXX - Fix this to have cleaner activate/deactivate calls.
3413 # XXX - Fix this to have cleaner activate/deactivate calls.
3533 from IPython.extensions import InterpreterPasteInput as ipaste
3414 from IPython.extensions import InterpreterPasteInput as ipaste
3534 from IPython.utils.ipstruct import Struct
3415 from IPython.utils.ipstruct import Struct
3535
3416
3536 # Shorthands
3417 # Shorthands
3537 shell = self.shell
3418 shell = self.shell
3538 oc = shell.outputcache
3419 oc = shell.outputcache
3539 meta = shell.meta
3420 meta = shell.meta
3540 # dstore is a data store kept in the instance metadata bag to track any
3421 # dstore is a data store kept in the instance metadata bag to track any
3541 # changes we make, so we can undo them later.
3422 # changes we make, so we can undo them later.
3542 dstore = meta.setdefault('doctest_mode',Struct())
3423 dstore = meta.setdefault('doctest_mode',Struct())
3543 save_dstore = dstore.setdefault
3424 save_dstore = dstore.setdefault
3544
3425
3545 # save a few values we'll need to recover later
3426 # save a few values we'll need to recover later
3546 mode = save_dstore('mode',False)
3427 mode = save_dstore('mode',False)
3547 save_dstore('rc_pprint',shell.pprint)
3428 save_dstore('rc_pprint',shell.pprint)
3548 save_dstore('xmode',shell.InteractiveTB.mode)
3429 save_dstore('xmode',shell.InteractiveTB.mode)
3549 save_dstore('rc_separate_out',shell.separate_out)
3430 save_dstore('rc_separate_out',shell.separate_out)
3550 save_dstore('rc_separate_out2',shell.separate_out2)
3431 save_dstore('rc_separate_out2',shell.separate_out2)
3551 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3432 save_dstore('rc_prompts_pad_left',shell.prompts_pad_left)
3552 save_dstore('rc_separate_in',shell.separate_in)
3433 save_dstore('rc_separate_in',shell.separate_in)
3553
3434
3554 if mode == False:
3435 if mode == False:
3555 # turn on
3436 # turn on
3556 ipaste.activate_prefilter()
3437 ipaste.activate_prefilter()
3557
3438
3558 oc.prompt1.p_template = '>>> '
3439 oc.prompt1.p_template = '>>> '
3559 oc.prompt2.p_template = '... '
3440 oc.prompt2.p_template = '... '
3560 oc.prompt_out.p_template = ''
3441 oc.prompt_out.p_template = ''
3561
3442
3562 # Prompt separators like plain python
3443 # Prompt separators like plain python
3563 oc.input_sep = oc.prompt1.sep = ''
3444 oc.input_sep = oc.prompt1.sep = ''
3564 oc.output_sep = ''
3445 oc.output_sep = ''
3565 oc.output_sep2 = ''
3446 oc.output_sep2 = ''
3566
3447
3567 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3448 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3568 oc.prompt_out.pad_left = False
3449 oc.prompt_out.pad_left = False
3569
3450
3570 shell.pprint = False
3451 shell.pprint = False
3571
3452
3572 shell.magic_xmode('Plain')
3453 shell.magic_xmode('Plain')
3573
3454
3574 else:
3455 else:
3575 # turn off
3456 # turn off
3576 ipaste.deactivate_prefilter()
3457 ipaste.deactivate_prefilter()
3577
3458
3578 oc.prompt1.p_template = shell.prompt_in1
3459 oc.prompt1.p_template = shell.prompt_in1
3579 oc.prompt2.p_template = shell.prompt_in2
3460 oc.prompt2.p_template = shell.prompt_in2
3580 oc.prompt_out.p_template = shell.prompt_out
3461 oc.prompt_out.p_template = shell.prompt_out
3581
3462
3582 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3463 oc.input_sep = oc.prompt1.sep = dstore.rc_separate_in
3583
3464
3584 oc.output_sep = dstore.rc_separate_out
3465 oc.output_sep = dstore.rc_separate_out
3585 oc.output_sep2 = dstore.rc_separate_out2
3466 oc.output_sep2 = dstore.rc_separate_out2
3586
3467
3587 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3468 oc.prompt1.pad_left = oc.prompt2.pad_left = \
3588 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3469 oc.prompt_out.pad_left = dstore.rc_prompts_pad_left
3589
3470
3590 rc.pprint = dstore.rc_pprint
3471 rc.pprint = dstore.rc_pprint
3591
3472
3592 shell.magic_xmode(dstore.xmode)
3473 shell.magic_xmode(dstore.xmode)
3593
3474
3594 # Store new mode and inform
3475 # Store new mode and inform
3595 dstore.mode = bool(1-int(mode))
3476 dstore.mode = bool(1-int(mode))
3596 print 'Doctest mode is:',
3477 print 'Doctest mode is:',
3597 print ['OFF','ON'][dstore.mode]
3478 print ['OFF','ON'][dstore.mode]
3598
3479
3599 def magic_gui(self, parameter_s=''):
3480 def magic_gui(self, parameter_s=''):
3600 """Enable or disable IPython GUI event loop integration.
3481 """Enable or disable IPython GUI event loop integration.
3601
3482
3602 %gui [-a] [GUINAME]
3483 %gui [-a] [GUINAME]
3603
3484
3604 This magic replaces IPython's threaded shells that were activated
3485 This magic replaces IPython's threaded shells that were activated
3605 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3486 using the (pylab/wthread/etc.) command line flags. GUI toolkits
3606 can now be enabled, disabled and swtiched at runtime and keyboard
3487 can now be enabled, disabled and swtiched at runtime and keyboard
3607 interrupts should work without any problems. The following toolkits
3488 interrupts should work without any problems. The following toolkits
3608 are supported: wxPython, PyQt4, PyGTK, and Tk::
3489 are supported: wxPython, PyQt4, PyGTK, and Tk::
3609
3490
3610 %gui wx # enable wxPython event loop integration
3491 %gui wx # enable wxPython event loop integration
3611 %gui qt4|qt # enable PyQt4 event loop integration
3492 %gui qt4|qt # enable PyQt4 event loop integration
3612 %gui gtk # enable PyGTK event loop integration
3493 %gui gtk # enable PyGTK event loop integration
3613 %gui tk # enable Tk event loop integration
3494 %gui tk # enable Tk event loop integration
3614 %gui # disable all event loop integration
3495 %gui # disable all event loop integration
3615
3496
3616 WARNING: after any of these has been called you can simply create
3497 WARNING: after any of these has been called you can simply create
3617 an application object, but DO NOT start the event loop yourself, as
3498 an application object, but DO NOT start the event loop yourself, as
3618 we have already handled that.
3499 we have already handled that.
3619
3500
3620 If you want us to create an appropriate application object add the
3501 If you want us to create an appropriate application object add the
3621 "-a" flag to your command::
3502 "-a" flag to your command::
3622
3503
3623 %gui -a wx
3504 %gui -a wx
3624
3505
3625 This is highly recommended for most users.
3506 This is highly recommended for most users.
3626 """
3507 """
3627 from IPython.lib import inputhook
3628
3629 opts, arg = self.parse_options(parameter_s,'a')
3508 opts, arg = self.parse_options(parameter_s,'a')
3630 if not arg:
3509 if arg=='': arg = None
3631 inputhook.clear_inputhook()
3510 return enable_gui(arg, 'a' in opts)
3632 return
3633
3634 guis = {'tk': inputhook.enable_tk,
3635 'gtk':inputhook.enable_gtk,
3636 'wx': inputhook.enable_wx,
3637 'qt': inputhook.enable_qt4, # qt3 not supported
3638 'qt4': inputhook.enable_qt4 }
3639 try:
3640 gui = guis[arg]
3641 except KeyError:
3642 e="Invalid GUI request %r, valid ones are:%s" % (arg, guis.keys())
3643 raise UsageError(e)
3644
3645 #print 'Switching IPython gui support to:', arg, 'a' in opts # dbg
3646 return gui('a' in opts)
3647
3511
3648 def magic_load_ext(self, module_str):
3512 def magic_load_ext(self, module_str):
3649 """Load an IPython extension by its module name."""
3513 """Load an IPython extension by its module name."""
3650 self.load_extension(module_str)
3514 self.load_extension(module_str)
3651
3515
3652 def magic_unload_ext(self, module_str):
3516 def magic_unload_ext(self, module_str):
3653 """Unload an IPython extension by its module name."""
3517 """Unload an IPython extension by its module name."""
3654 self.unload_extension(module_str)
3518 self.unload_extension(module_str)
3655
3519
3656 def magic_reload_ext(self, module_str):
3520 def magic_reload_ext(self, module_str):
3657 """Reload an IPython extension by its module name."""
3521 """Reload an IPython extension by its module name."""
3658 self.reload_extension(module_str)
3522 self.reload_extension(module_str)
3659
3523
3660 def magic_install_profiles(self, s):
3524 def magic_install_profiles(self, s):
3661 """Install the default IPython profiles into the .ipython dir.
3525 """Install the default IPython profiles into the .ipython dir.
3662
3526
3663 If the default profiles have already been installed, they will not
3527 If the default profiles have already been installed, they will not
3664 be overwritten. You can force overwriting them by using the ``-o``
3528 be overwritten. You can force overwriting them by using the ``-o``
3665 option::
3529 option::
3666
3530
3667 In [1]: %install_profiles -o
3531 In [1]: %install_profiles -o
3668 """
3532 """
3669 if '-o' in s:
3533 if '-o' in s:
3670 overwrite = True
3534 overwrite = True
3671 else:
3535 else:
3672 overwrite = False
3536 overwrite = False
3673 from IPython.config import profile
3537 from IPython.config import profile
3674 profile_dir = os.path.split(profile.__file__)[0]
3538 profile_dir = os.path.split(profile.__file__)[0]
3675 ipython_dir = self.ipython_dir
3539 ipython_dir = self.ipython_dir
3676 files = os.listdir(profile_dir)
3540 files = os.listdir(profile_dir)
3677
3541
3678 to_install = []
3542 to_install = []
3679 for f in files:
3543 for f in files:
3680 if f.startswith('ipython_config'):
3544 if f.startswith('ipython_config'):
3681 src = os.path.join(profile_dir, f)
3545 src = os.path.join(profile_dir, f)
3682 dst = os.path.join(ipython_dir, f)
3546 dst = os.path.join(ipython_dir, f)
3683 if (not os.path.isfile(dst)) or overwrite:
3547 if (not os.path.isfile(dst)) or overwrite:
3684 to_install.append((f, src, dst))
3548 to_install.append((f, src, dst))
3685 if len(to_install)>0:
3549 if len(to_install)>0:
3686 print "Installing profiles to: ", ipython_dir
3550 print "Installing profiles to: ", ipython_dir
3687 for (f, src, dst) in to_install:
3551 for (f, src, dst) in to_install:
3688 shutil.copy(src, dst)
3552 shutil.copy(src, dst)
3689 print " %s" % f
3553 print " %s" % f
3690
3554
3691 def magic_install_default_config(self, s):
3555 def magic_install_default_config(self, s):
3692 """Install IPython's default config file into the .ipython dir.
3556 """Install IPython's default config file into the .ipython dir.
3693
3557
3694 If the default config file (:file:`ipython_config.py`) is already
3558 If the default config file (:file:`ipython_config.py`) is already
3695 installed, it will not be overwritten. You can force overwriting
3559 installed, it will not be overwritten. You can force overwriting
3696 by using the ``-o`` option::
3560 by using the ``-o`` option::
3697
3561
3698 In [1]: %install_default_config
3562 In [1]: %install_default_config
3699 """
3563 """
3700 if '-o' in s:
3564 if '-o' in s:
3701 overwrite = True
3565 overwrite = True
3702 else:
3566 else:
3703 overwrite = False
3567 overwrite = False
3704 from IPython.config import default
3568 from IPython.config import default
3705 config_dir = os.path.split(default.__file__)[0]
3569 config_dir = os.path.split(default.__file__)[0]
3706 ipython_dir = self.ipython_dir
3570 ipython_dir = self.ipython_dir
3707 default_config_file_name = 'ipython_config.py'
3571 default_config_file_name = 'ipython_config.py'
3708 src = os.path.join(config_dir, default_config_file_name)
3572 src = os.path.join(config_dir, default_config_file_name)
3709 dst = os.path.join(ipython_dir, default_config_file_name)
3573 dst = os.path.join(ipython_dir, default_config_file_name)
3710 if (not os.path.isfile(dst)) or overwrite:
3574 if (not os.path.isfile(dst)) or overwrite:
3711 shutil.copy(src, dst)
3575 shutil.copy(src, dst)
3712 print "Installing default config file: %s" % dst
3576 print "Installing default config file: %s" % dst
3713
3577
3714 # Pylab support: simple wrappers that activate pylab, load gui input
3578 # Pylab support: simple wrappers that activate pylab, load gui input
3715 # handling and modify slightly %run
3579 # handling and modify slightly %run
3716
3580
3717 @testdec.skip_doctest
3581 @testdec.skip_doctest
3718 def _pylab_magic_run(self, parameter_s=''):
3582 def _pylab_magic_run(self, parameter_s=''):
3719 Magic.magic_run(self, parameter_s,
3583 Magic.magic_run(self, parameter_s,
3720 runner=mpl_runner(self.shell.safe_execfile))
3584 runner=mpl_runner(self.shell.safe_execfile))
3721
3585
3722 _pylab_magic_run.__doc__ = magic_run.__doc__
3586 _pylab_magic_run.__doc__ = magic_run.__doc__
3723
3587
3724 @testdec.skip_doctest
3588 @testdec.skip_doctest
3725 def magic_pylab(self, s):
3589 def magic_pylab(self, s):
3726 """Load numpy and matplotlib to work interactively.
3590 """Load numpy and matplotlib to work interactively.
3727
3591
3728 %pylab [GUINAME]
3592 %pylab [GUINAME]
3729
3593
3730 This function lets you activate pylab (matplotlib, numpy and
3594 This function lets you activate pylab (matplotlib, numpy and
3731 interactive support) at any point during an IPython session.
3595 interactive support) at any point during an IPython session.
3732
3596
3733 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3597 It will import at the top level numpy as np, pyplot as plt, matplotlib,
3734 pylab and mlab, as well as all names from numpy and pylab.
3598 pylab and mlab, as well as all names from numpy and pylab.
3735
3599
3736 Parameters
3600 Parameters
3737 ----------
3601 ----------
3738 guiname : optional
3602 guiname : optional
3739 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3603 One of the valid arguments to the %gui magic ('qt', 'wx', 'gtk' or
3740 'tk'). If given, the corresponding Matplotlib backend is used,
3604 'tk'). If given, the corresponding Matplotlib backend is used,
3741 otherwise matplotlib's default (which you can override in your
3605 otherwise matplotlib's default (which you can override in your
3742 matplotlib config file) is used.
3606 matplotlib config file) is used.
3743
3607
3744 Examples
3608 Examples
3745 --------
3609 --------
3746 In this case, where the MPL default is TkAgg:
3610 In this case, where the MPL default is TkAgg:
3747 In [2]: %pylab
3611 In [2]: %pylab
3748
3612
3749 Welcome to pylab, a matplotlib-based Python environment.
3613 Welcome to pylab, a matplotlib-based Python environment.
3750 Backend in use: TkAgg
3614 Backend in use: TkAgg
3751 For more information, type 'help(pylab)'.
3615 For more information, type 'help(pylab)'.
3752
3616
3753 But you can explicitly request a different backend:
3617 But you can explicitly request a different backend:
3754 In [3]: %pylab qt
3618 In [3]: %pylab qt
3755
3619
3756 Welcome to pylab, a matplotlib-based Python environment.
3620 Welcome to pylab, a matplotlib-based Python environment.
3757 Backend in use: Qt4Agg
3621 Backend in use: Qt4Agg
3758 For more information, type 'help(pylab)'.
3622 For more information, type 'help(pylab)'.
3759 """
3623 """
3760
3624 self.shell.enable_pylab(s)
3761 gui = pylab_activate(self.shell.user_ns, s)
3762 self.shell.magic_gui('-a %s' % gui)
3763 self.shell.magic_run = self._pylab_magic_run
3764
3625
3765 # end Magic
3626 # end Magic
@@ -1,525 +1,571 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 # encoding: utf-8
2 # coding: utf-8
3 """
3 """
4 Inputhook management for GUI event loop integration.
4 Inputhook management for GUI event loop integration.
5 """
5 """
6
6
7 #-----------------------------------------------------------------------------
7 #-----------------------------------------------------------------------------
8 # Copyright (C) 2008-2009 The IPython Development Team
8 # Copyright (C) 2008-2009 The IPython Development Team
9 #
9 #
10 # Distributed under the terms of the BSD License. The full license is in
10 # Distributed under the terms of the BSD License. The full license is in
11 # the file COPYING, distributed as part of this software.
11 # the file COPYING, distributed as part of this software.
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17
17
18 import ctypes
18 import ctypes
19 import sys
19 import sys
20
20
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22 # Constants
22 # Constants
23 #-----------------------------------------------------------------------------
23 #-----------------------------------------------------------------------------
24
24
25 # Constants for identifying the GUI toolkits.
25 # Constants for identifying the GUI toolkits.
26 GUI_WX = 'wx'
26 GUI_WX = 'wx'
27 GUI_QT = 'qt'
27 GUI_QT4 = 'qt4'
28 GUI_QT4 = 'qt4'
28 GUI_GTK = 'gtk'
29 GUI_GTK = 'gtk'
29 GUI_TK = 'tk'
30 GUI_TK = 'tk'
30
31
31 #-----------------------------------------------------------------------------
32 #-----------------------------------------------------------------------------
32 # Utility classes
33 # Utility classes
33 #-----------------------------------------------------------------------------
34 #-----------------------------------------------------------------------------
34
35
35
36
36 class _DummyMainloop(object):
37 class _DummyMainloop(object):
37 """A special manager to hijack GUI mainloops that is mostly a no-op.
38 """A special manager to hijack GUI mainloops that is mostly a no-op.
38
39
39 We are not using this class currently as it breaks GUI code that calls
40 We are not using this class currently as it breaks GUI code that calls
40 a mainloop function after the app has started to process pending events.
41 a mainloop function after the app has started to process pending events.
41 """
42 """
42 def __init__(self, ml, ihm, gui_type):
43 def __init__(self, ml, ihm, gui_type):
43 self.ml = ml
44 self.ml = ml
44 self.ihm = ihm
45 self.ihm = ihm
45 self.gui_type = gui_type
46 self.gui_type = gui_type
46
47
47 def __call__(self, *args, **kw):
48 def __call__(self, *args, **kw):
48 if self.ihm.current_gui() == self.gui_type:
49 if self.ihm.current_gui() == self.gui_type:
49 pass
50 pass
50 else:
51 else:
51 self.ml(*args, **kw)
52 self.ml(*args, **kw)
52
53
53
54
54 #-----------------------------------------------------------------------------
55 #-----------------------------------------------------------------------------
55 # Appstart and spin functions
56 # Appstart and spin functions
56 #-----------------------------------------------------------------------------
57 #-----------------------------------------------------------------------------
57
58
58
59
59 def appstart_qt4(app):
60 def appstart_qt4(app):
60 """Start the qt4 event loop in a way that plays with IPython.
61 """Start the qt4 event loop in a way that plays with IPython.
61
62
62 When a qt4 app is run interactively in IPython, the event loop should
63 When a qt4 app is run interactively in IPython, the event loop should
63 not be started. This function checks to see if IPython's qt4 integration
64 not be started. This function checks to see if IPython's qt4 integration
64 is activated and if so, it passes. If not, it will call the :meth:`exec_`
65 is activated and if so, it passes. If not, it will call the :meth:`exec_`
65 method of the main qt4 app.
66 method of the main qt4 app.
66
67
67 This function should be used by users who want their qt4 scripts to work
68 This function should be used by users who want their qt4 scripts to work
68 both at the command line and in IPython. These users should put the
69 both at the command line and in IPython. These users should put the
69 following logic at the bottom on their script, after they create a
70 following logic at the bottom on their script, after they create a
70 :class:`QApplication` instance (called ``app`` here)::
71 :class:`QApplication` instance (called ``app`` here)::
71
72
72 try:
73 try:
73 from IPython.lib.inputhook import appstart_qt4
74 from IPython.lib.inputhook import appstart_qt4
74 appstart_qt4(app)
75 appstart_qt4(app)
75 except ImportError:
76 except ImportError:
76 app.exec_()
77 app.exec_()
77 """
78 """
78 from PyQt4 import QtCore, QtGui
79 from PyQt4 import QtCore, QtGui
79
80
80 assert isinstance(app, QtCore.QCoreApplication)
81 assert isinstance(app, QtCore.QCoreApplication)
81 if app is not None:
82 if app is not None:
82 if current_gui() == GUI_QT4:
83 if current_gui() == GUI_QT4:
83 pass
84 pass
84 else:
85 else:
85 app.exec_()
86 app.exec_()
86
87
87
88
88 def appstart_wx(app):
89 def appstart_wx(app):
89 """Start the wx event loop in a way that plays with IPython.
90 """Start the wx event loop in a way that plays with IPython.
90
91
91 When a wx app is run interactively in IPython, the event loop should
92 When a wx app is run interactively in IPython, the event loop should
92 not be started. This function checks to see if IPython's wx integration
93 not be started. This function checks to see if IPython's wx integration
93 is activated and if so, it passes. If not, it will call the
94 is activated and if so, it passes. If not, it will call the
94 :meth:`MainLoop` method of the main qt4 app.
95 :meth:`MainLoop` method of the main qt4 app.
95
96
96 This function should be used by users who want their wx scripts to work
97 This function should be used by users who want their wx scripts to work
97 both at the command line and in IPython. These users should put the
98 both at the command line and in IPython. These users should put the
98 following logic at the bottom on their script, after they create a
99 following logic at the bottom on their script, after they create a
99 :class:`App` instance (called ``app`` here)::
100 :class:`App` instance (called ``app`` here)::
100
101
101 try:
102 try:
102 from IPython.lib.inputhook import appstart_wx
103 from IPython.lib.inputhook import appstart_wx
103 appstart_wx(app)
104 appstart_wx(app)
104 except ImportError:
105 except ImportError:
105 app.MainLoop()
106 app.MainLoop()
106 """
107 """
107 import wx
108 import wx
108
109
109 assert isinstance(app, wx.App)
110 assert isinstance(app, wx.App)
110 if app is not None:
111 if app is not None:
111 if current_gui() == GUI_WX:
112 if current_gui() == GUI_WX:
112 pass
113 pass
113 else:
114 else:
114 app.MainLoop()
115 app.MainLoop()
115
116
116
117
117 def appstart_tk(app):
118 def appstart_tk(app):
118 """Start the tk event loop in a way that plays with IPython.
119 """Start the tk event loop in a way that plays with IPython.
119
120
120 When a tk app is run interactively in IPython, the event loop should
121 When a tk app is run interactively in IPython, the event loop should
121 not be started. This function checks to see if IPython's tk integration
122 not be started. This function checks to see if IPython's tk integration
122 is activated and if so, it passes. If not, it will call the
123 is activated and if so, it passes. If not, it will call the
123 :meth:`mainloop` method of the tk object passed to this method.
124 :meth:`mainloop` method of the tk object passed to this method.
124
125
125 This function should be used by users who want their tk scripts to work
126 This function should be used by users who want their tk scripts to work
126 both at the command line and in IPython. These users should put the
127 both at the command line and in IPython. These users should put the
127 following logic at the bottom on their script, after they create a
128 following logic at the bottom on their script, after they create a
128 :class:`Tk` instance (called ``app`` here)::
129 :class:`Tk` instance (called ``app`` here)::
129
130
130 try:
131 try:
131 from IPython.lib.inputhook import appstart_tk
132 from IPython.lib.inputhook import appstart_tk
132 appstart_tk(app)
133 appstart_tk(app)
133 except ImportError:
134 except ImportError:
134 app.mainloop()
135 app.mainloop()
135 """
136 """
136 if app is not None:
137 if app is not None:
137 if current_gui() == GUI_TK:
138 if current_gui() == GUI_TK:
138 pass
139 pass
139 else:
140 else:
140 app.mainloop()
141 app.mainloop()
141
142
142 def appstart_gtk():
143 def appstart_gtk():
143 """Start the gtk event loop in a way that plays with IPython.
144 """Start the gtk event loop in a way that plays with IPython.
144
145
145 When a gtk app is run interactively in IPython, the event loop should
146 When a gtk app is run interactively in IPython, the event loop should
146 not be started. This function checks to see if IPython's gtk integration
147 not be started. This function checks to see if IPython's gtk integration
147 is activated and if so, it passes. If not, it will call
148 is activated and if so, it passes. If not, it will call
148 :func:`gtk.main`. Unlike the other appstart implementations, this does
149 :func:`gtk.main`. Unlike the other appstart implementations, this does
149 not take an ``app`` argument.
150 not take an ``app`` argument.
150
151
151 This function should be used by users who want their gtk scripts to work
152 This function should be used by users who want their gtk scripts to work
152 both at the command line and in IPython. These users should put the
153 both at the command line and in IPython. These users should put the
153 following logic at the bottom on their script::
154 following logic at the bottom on their script::
154
155
155 try:
156 try:
156 from IPython.lib.inputhook import appstart_gtk
157 from IPython.lib.inputhook import appstart_gtk
157 appstart_gtk()
158 appstart_gtk()
158 except ImportError:
159 except ImportError:
159 gtk.main()
160 gtk.main()
160 """
161 """
161 import gtk
162 import gtk
162 if current_gui() == GUI_GTK:
163 if current_gui() == GUI_GTK:
163 pass
164 pass
164 else:
165 else:
165 gtk.main()
166 gtk.main()
166
167
167 #-----------------------------------------------------------------------------
168 #-----------------------------------------------------------------------------
168 # Main InputHookManager class
169 # Main InputHookManager class
169 #-----------------------------------------------------------------------------
170 #-----------------------------------------------------------------------------
170
171
171
172
172 class InputHookManager(object):
173 class InputHookManager(object):
173 """Manage PyOS_InputHook for different GUI toolkits.
174 """Manage PyOS_InputHook for different GUI toolkits.
174
175
175 This class installs various hooks under ``PyOSInputHook`` to handle
176 This class installs various hooks under ``PyOSInputHook`` to handle
176 GUI event loop integration.
177 GUI event loop integration.
177 """
178 """
178
179
179 def __init__(self):
180 def __init__(self):
180 self.PYFUNC = ctypes.PYFUNCTYPE(ctypes.c_int)
181 self.PYFUNC = ctypes.PYFUNCTYPE(ctypes.c_int)
181 self._apps = {}
182 self._apps = {}
182 self._spinner_dict = {
183 self._spinner_dict = {
183 GUI_QT4 : self._spin_qt4,
184 GUI_QT4 : self._spin_qt4,
184 GUI_WX : self._spin_wx,
185 GUI_WX : self._spin_wx,
185 GUI_GTK : self._spin_gtk,
186 GUI_GTK : self._spin_gtk,
186 GUI_TK : self._spin_tk}
187 GUI_TK : self._spin_tk}
187 self._reset()
188 self._reset()
188
189
189 def _reset(self):
190 def _reset(self):
190 self._callback_pyfunctype = None
191 self._callback_pyfunctype = None
191 self._callback = None
192 self._callback = None
192 self._installed = False
193 self._installed = False
193 self._current_gui = None
194 self._current_gui = None
194
195
195 def _hijack_wx(self):
196 def _hijack_wx(self):
196 """Hijack the wx mainloop so a user calling it won't cause badness.
197 """Hijack the wx mainloop so a user calling it won't cause badness.
197
198
198 We are not currently using this as it breaks GUI code that calls a
199 We are not currently using this as it breaks GUI code that calls a
199 mainloop at anytime but startup.
200 mainloop at anytime but startup.
200 """
201 """
201 import wx
202 import wx
202 if hasattr(wx, '_core_'): core = getattr(wx, '_core_')
203 if hasattr(wx, '_core_'): core = getattr(wx, '_core_')
203 elif hasattr(wx, '_core'): core = getattr(wx, '_core')
204 elif hasattr(wx, '_core'): core = getattr(wx, '_core')
204 else: raise AttributeError('Could not find wx core module')
205 else: raise AttributeError('Could not find wx core module')
205 orig_mainloop = core.PyApp_MainLoop
206 orig_mainloop = core.PyApp_MainLoop
206 core.PyApp_MainLoop = _DummyMainloop
207 core.PyApp_MainLoop = _DummyMainloop
207 return orig_mainloop
208 return orig_mainloop
208
209
209 def _hijack_qt4(self):
210 def _hijack_qt4(self):
210 """Hijack the qt4 mainloop so a user calling it won't cause badness.
211 """Hijack the qt4 mainloop so a user calling it won't cause badness.
211
212
212 We are not currently using this as it breaks GUI code that calls a
213 We are not currently using this as it breaks GUI code that calls a
213 mainloop at anytime but startup.
214 mainloop at anytime but startup.
214 """
215 """
215 from PyQt4 import QtGui, QtCore
216 from PyQt4 import QtGui, QtCore
216 orig_mainloop = QtGui.qApp.exec_
217 orig_mainloop = QtGui.qApp.exec_
217 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_QT4)
218 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_QT4)
218 QtGui.qApp.exec_ = dumb_ml
219 QtGui.qApp.exec_ = dumb_ml
219 QtGui.QApplication.exec_ = dumb_ml
220 QtGui.QApplication.exec_ = dumb_ml
220 QtCore.QCoreApplication.exec_ = dumb_ml
221 QtCore.QCoreApplication.exec_ = dumb_ml
221 return orig_mainloop
222 return orig_mainloop
222
223
223 def _hijack_gtk(self):
224 def _hijack_gtk(self):
224 """Hijack the gtk mainloop so a user calling it won't cause badness.
225 """Hijack the gtk mainloop so a user calling it won't cause badness.
225
226
226 We are not currently using this as it breaks GUI code that calls a
227 We are not currently using this as it breaks GUI code that calls a
227 mainloop at anytime but startup.
228 mainloop at anytime but startup.
228 """
229 """
229 import gtk
230 import gtk
230 orig_mainloop = gtk.main
231 orig_mainloop = gtk.main
231 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_GTK)
232 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_GTK)
232 gtk.mainloop = dumb_ml
233 gtk.mainloop = dumb_ml
233 gtk.main = dumb_ml
234 gtk.main = dumb_ml
234 return orig_mainloop
235 return orig_mainloop
235
236
236 def _hijack_tk(self):
237 def _hijack_tk(self):
237 """Hijack the tk mainloop so a user calling it won't cause badness.
238 """Hijack the tk mainloop so a user calling it won't cause badness.
238
239
239 We are not currently using this as it breaks GUI code that calls a
240 We are not currently using this as it breaks GUI code that calls a
240 mainloop at anytime but startup.
241 mainloop at anytime but startup.
241 """
242 """
242 import Tkinter
243 import Tkinter
243 orig_mainloop = gtk.main
244 orig_mainloop = gtk.main
244 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_TK)
245 dumb_ml = _DummyMainloop(orig_mainloop, self, GUI_TK)
245 Tkinter.Misc.mainloop = dumb_ml
246 Tkinter.Misc.mainloop = dumb_ml
246 Tkinter.mainloop = dumb_ml
247 Tkinter.mainloop = dumb_ml
247
248
248 def _spin_qt4(self):
249 def _spin_qt4(self):
249 """Process all pending events in the qt4 event loop.
250 """Process all pending events in the qt4 event loop.
250
251
251 This is for internal IPython use only and user code should not call this.
252 This is for internal IPython use only and user code should not call this.
252 Instead, they should issue the raw GUI calls themselves.
253 Instead, they should issue the raw GUI calls themselves.
253 """
254 """
254 from PyQt4 import QtCore, QtGui
255 from PyQt4 import QtCore, QtGui
255
256
256 app = QtCore.QCoreApplication.instance()
257 app = QtCore.QCoreApplication.instance()
257 if app is not None:
258 if app is not None:
258 QtCore.QCoreApplication.processEvents(QtCore.QEventLoop.AllEvents)
259 QtCore.QCoreApplication.processEvents(QtCore.QEventLoop.AllEvents)
259
260
260 def _spin_wx(self):
261 def _spin_wx(self):
261 """Process all pending events in the wx event loop.
262 """Process all pending events in the wx event loop.
262
263
263 This is for internal IPython use only and user code should not call this.
264 This is for internal IPython use only and user code should not call this.
264 Instead, they should issue the raw GUI calls themselves.
265 Instead, they should issue the raw GUI calls themselves.
265 """
266 """
266 import wx
267 import wx
267 app = wx.GetApp()
268 app = wx.GetApp()
268 if app is not None and wx.Thread_IsMain():
269 if app is not None and wx.Thread_IsMain():
269 evtloop = wx.EventLoop()
270 evtloop = wx.EventLoop()
270 ea = wx.EventLoopActivator(evtloop)
271 ea = wx.EventLoopActivator(evtloop)
271 while evtloop.Pending():
272 while evtloop.Pending():
272 evtloop.Dispatch()
273 evtloop.Dispatch()
273 app.ProcessIdle()
274 app.ProcessIdle()
274 del ea
275 del ea
275
276
276 def _spin_gtk(self):
277 def _spin_gtk(self):
277 """Process all pending events in the gtk event loop.
278 """Process all pending events in the gtk event loop.
278
279
279 This is for internal IPython use only and user code should not call this.
280 This is for internal IPython use only and user code should not call this.
280 Instead, they should issue the raw GUI calls themselves.
281 Instead, they should issue the raw GUI calls themselves.
281 """
282 """
282 import gtk
283 import gtk
283 gtk.gdk.threads_enter()
284 gtk.gdk.threads_enter()
284 while gtk.events_pending():
285 while gtk.events_pending():
285 gtk.main_iteration(False)
286 gtk.main_iteration(False)
286 gtk.gdk.flush()
287 gtk.gdk.flush()
287 gtk.gdk.threads_leave()
288 gtk.gdk.threads_leave()
288
289
289 def _spin_tk(self):
290 def _spin_tk(self):
290 """Process all pending events in the tk event loop.
291 """Process all pending events in the tk event loop.
291
292
292 This is for internal IPython use only and user code should not call this.
293 This is for internal IPython use only and user code should not call this.
293 Instead, they should issue the raw GUI calls themselves.
294 Instead, they should issue the raw GUI calls themselves.
294 """
295 """
295 app = self._apps.get(GUI_TK)
296 app = self._apps.get(GUI_TK)
296 if app is not None:
297 if app is not None:
297 app.update()
298 app.update()
298
299
299 def spin(self):
300 def spin(self):
300 """Process pending events in the current gui.
301 """Process pending events in the current gui.
301
302
302 This method is just provided for IPython to use internally if needed
303 This method is just provided for IPython to use internally if needed
303 for things like testing. Third party projects should not call this
304 for things like testing. Third party projects should not call this
304 method, but instead should call the underlying GUI toolkit methods
305 method, but instead should call the underlying GUI toolkit methods
305 that we are calling.
306 that we are calling.
306 """
307 """
307 spinner = self._spinner_dict.get(self._current_gui, lambda: None)
308 spinner = self._spinner_dict.get(self._current_gui, lambda: None)
308 spinner()
309 spinner()
309
310
310 def get_pyos_inputhook(self):
311 def get_pyos_inputhook(self):
311 """Return the current PyOS_InputHook as a ctypes.c_void_p."""
312 """Return the current PyOS_InputHook as a ctypes.c_void_p."""
312 return ctypes.c_void_p.in_dll(ctypes.pythonapi,"PyOS_InputHook")
313 return ctypes.c_void_p.in_dll(ctypes.pythonapi,"PyOS_InputHook")
313
314
314 def get_pyos_inputhook_as_func(self):
315 def get_pyos_inputhook_as_func(self):
315 """Return the current PyOS_InputHook as a ctypes.PYFUNCYPE."""
316 """Return the current PyOS_InputHook as a ctypes.PYFUNCYPE."""
316 return self.PYFUNC.in_dll(ctypes.pythonapi,"PyOS_InputHook")
317 return self.PYFUNC.in_dll(ctypes.pythonapi,"PyOS_InputHook")
317
318
318 def set_inputhook(self, callback):
319 def set_inputhook(self, callback):
319 """Set PyOS_InputHook to callback and return the previous one."""
320 """Set PyOS_InputHook to callback and return the previous one."""
320 self._callback = callback
321 self._callback = callback
321 self._callback_pyfunctype = self.PYFUNC(callback)
322 self._callback_pyfunctype = self.PYFUNC(callback)
322 pyos_inputhook_ptr = self.get_pyos_inputhook()
323 pyos_inputhook_ptr = self.get_pyos_inputhook()
323 original = self.get_pyos_inputhook_as_func()
324 original = self.get_pyos_inputhook_as_func()
324 pyos_inputhook_ptr.value = \
325 pyos_inputhook_ptr.value = \
325 ctypes.cast(self._callback_pyfunctype, ctypes.c_void_p).value
326 ctypes.cast(self._callback_pyfunctype, ctypes.c_void_p).value
326 self._installed = True
327 self._installed = True
327 return original
328 return original
328
329
329 def clear_inputhook(self):
330 def clear_inputhook(self, app=None):
330 """Set PyOS_InputHook to NULL and return the previous one."""
331 """Set PyOS_InputHook to NULL and return the previous one.
332
333 Parameters
334 ----------
335 app : optional, ignored
336 This parameter is allowed only so that clear_inputhook() can be
337 called with a similar interface as all the ``enable_*`` methods. But
338 the actual value of the parameter is ignored. This uniform interface
339 makes it easier to have user-level entry points in the main IPython
340 app like :meth:`enable_gui`."""
331 pyos_inputhook_ptr = self.get_pyos_inputhook()
341 pyos_inputhook_ptr = self.get_pyos_inputhook()
332 original = self.get_pyos_inputhook_as_func()
342 original = self.get_pyos_inputhook_as_func()
333 pyos_inputhook_ptr.value = ctypes.c_void_p(None).value
343 pyos_inputhook_ptr.value = ctypes.c_void_p(None).value
334 self._reset()
344 self._reset()
335 return original
345 return original
336
346
337 def clear_app_refs(self, gui=None):
347 def clear_app_refs(self, gui=None):
338 """Clear IPython's internal reference to an application instance.
348 """Clear IPython's internal reference to an application instance.
339
349
340 Whenever we create an app for a user on qt4 or wx, we hold a
350 Whenever we create an app for a user on qt4 or wx, we hold a
341 reference to the app. This is needed because in some cases bad things
351 reference to the app. This is needed because in some cases bad things
342 can happen if a user doesn't hold a reference themselves. This
352 can happen if a user doesn't hold a reference themselves. This
343 method is provided to clear the references we are holding.
353 method is provided to clear the references we are holding.
344
354
345 Parameters
355 Parameters
346 ----------
356 ----------
347 gui : None or str
357 gui : None or str
348 If None, clear all app references. If ('wx', 'qt4') clear
358 If None, clear all app references. If ('wx', 'qt4') clear
349 the app for that toolkit. References are not held for gtk or tk
359 the app for that toolkit. References are not held for gtk or tk
350 as those toolkits don't have the notion of an app.
360 as those toolkits don't have the notion of an app.
351 """
361 """
352 if gui is None:
362 if gui is None:
353 self._apps = {}
363 self._apps = {}
354 elif self._apps.has_key(gui):
364 elif self._apps.has_key(gui):
355 del self._apps[gui]
365 del self._apps[gui]
356
366
357 def enable_wx(self, app=False):
367 def enable_wx(self, app=False):
358 """Enable event loop integration with wxPython.
368 """Enable event loop integration with wxPython.
359
369
360 Parameters
370 Parameters
361 ----------
371 ----------
362 app : bool
372 app : bool
363 Create a running application object or not.
373 Create a running application object or not.
364
374
365 Notes
375 Notes
366 -----
376 -----
367 This methods sets the ``PyOS_InputHook`` for wxPython, which allows
377 This methods sets the ``PyOS_InputHook`` for wxPython, which allows
368 the wxPython to integrate with terminal based applications like
378 the wxPython to integrate with terminal based applications like
369 IPython.
379 IPython.
370
380
371 If ``app`` is True, we create an :class:`wx.App` as follows::
381 If ``app`` is True, we create an :class:`wx.App` as follows::
372
382
373 import wx
383 import wx
374 app = wx.App(redirect=False, clearSigInt=False)
384 app = wx.App(redirect=False, clearSigInt=False)
375
385
376 Both options this constructor are important for things to work
386 Both options this constructor are important for things to work
377 properly in an interactive context.
387 properly in an interactive context.
378
388
379 But, we first check to see if an application has already been
389 But, we first check to see if an application has already been
380 created. If so, we simply return that instance.
390 created. If so, we simply return that instance.
381 """
391 """
382 from IPython.lib.inputhookwx import inputhook_wx
392 from IPython.lib.inputhookwx import inputhook_wx
383 self.set_inputhook(inputhook_wx)
393 self.set_inputhook(inputhook_wx)
384 self._current_gui = GUI_WX
394 self._current_gui = GUI_WX
385 if app:
395 if app:
386 import wx
396 import wx
387 app = wx.GetApp()
397 app = wx.GetApp()
388 if app is None:
398 if app is None:
389 app = wx.App(redirect=False, clearSigInt=False)
399 app = wx.App(redirect=False, clearSigInt=False)
390 self._apps[GUI_WX] = app
400 self._apps[GUI_WX] = app
391 return app
401 return app
392
402
393 def disable_wx(self):
403 def disable_wx(self):
394 """Disable event loop integration with wxPython.
404 """Disable event loop integration with wxPython.
395
405
396 This merely sets PyOS_InputHook to NULL.
406 This merely sets PyOS_InputHook to NULL.
397 """
407 """
398 self.clear_inputhook()
408 self.clear_inputhook()
399
409
400 def enable_qt4(self, app=False):
410 def enable_qt4(self, app=False):
401 """Enable event loop integration with PyQt4.
411 """Enable event loop integration with PyQt4.
402
412
403 Parameters
413 Parameters
404 ----------
414 ----------
405 app : bool
415 app : bool
406 Create a running application object or not.
416 Create a running application object or not.
407
417
408 Notes
418 Notes
409 -----
419 -----
410 This methods sets the PyOS_InputHook for PyQt4, which allows
420 This methods sets the PyOS_InputHook for PyQt4, which allows
411 the PyQt4 to integrate with terminal based applications like
421 the PyQt4 to integrate with terminal based applications like
412 IPython.
422 IPython.
413
423
414 If ``app`` is True, we create an :class:`QApplication` as follows::
424 If ``app`` is True, we create an :class:`QApplication` as follows::
415
425
416 from PyQt4 import QtCore
426 from PyQt4 import QtCore
417 app = QtGui.QApplication(sys.argv)
427 app = QtGui.QApplication(sys.argv)
418
428
419 But, we first check to see if an application has already been
429 But, we first check to see if an application has already been
420 created. If so, we simply return that instance.
430 created. If so, we simply return that instance.
421 """
431 """
422 from PyQt4 import QtCore
432 from PyQt4 import QtCore
423 # PyQt4 has had this since 4.3.1. In version 4.2, PyOS_InputHook
433 # PyQt4 has had this since 4.3.1. In version 4.2, PyOS_InputHook
424 # was set when QtCore was imported, but if it ever got removed,
434 # was set when QtCore was imported, but if it ever got removed,
425 # you couldn't reset it. For earlier versions we can
435 # you couldn't reset it. For earlier versions we can
426 # probably implement a ctypes version.
436 # probably implement a ctypes version.
427 try:
437 try:
428 QtCore.pyqtRestoreInputHook()
438 QtCore.pyqtRestoreInputHook()
429 except AttributeError:
439 except AttributeError:
430 pass
440 pass
431 self._current_gui = GUI_QT4
441 self._current_gui = GUI_QT4
432 if app:
442 if app:
433 from PyQt4 import QtGui
443 from PyQt4 import QtGui
434 app = QtCore.QCoreApplication.instance()
444 app = QtCore.QCoreApplication.instance()
435 if app is None:
445 if app is None:
436 app = QtGui.QApplication(sys.argv)
446 app = QtGui.QApplication(sys.argv)
437 self._apps[GUI_QT4] = app
447 self._apps[GUI_QT4] = app
438 return app
448 return app
439
449
440 def disable_qt4(self):
450 def disable_qt4(self):
441 """Disable event loop integration with PyQt4.
451 """Disable event loop integration with PyQt4.
442
452
443 This merely sets PyOS_InputHook to NULL.
453 This merely sets PyOS_InputHook to NULL.
444 """
454 """
445 self.clear_inputhook()
455 self.clear_inputhook()
446
456
447 def enable_gtk(self, app=False):
457 def enable_gtk(self, app=False):
448 """Enable event loop integration with PyGTK.
458 """Enable event loop integration with PyGTK.
449
459
450 Parameters
460 Parameters
451 ----------
461 ----------
452 app : bool
462 app : bool
453 Create a running application object or not. Because gtk does't
463 Create a running application object or not. Because gtk does't
454 have an app class, this does nothing.
464 have an app class, this does nothing.
455
465
456 Notes
466 Notes
457 -----
467 -----
458 This methods sets the PyOS_InputHook for PyGTK, which allows
468 This methods sets the PyOS_InputHook for PyGTK, which allows
459 the PyGTK to integrate with terminal based applications like
469 the PyGTK to integrate with terminal based applications like
460 IPython.
470 IPython.
461 """
471 """
462 import gtk
472 import gtk
463 try:
473 try:
464 gtk.set_interactive(True)
474 gtk.set_interactive(True)
465 self._current_gui = GUI_GTK
475 self._current_gui = GUI_GTK
466 except AttributeError:
476 except AttributeError:
467 # For older versions of gtk, use our own ctypes version
477 # For older versions of gtk, use our own ctypes version
468 from IPython.lib.inputhookgtk import inputhook_gtk
478 from IPython.lib.inputhookgtk import inputhook_gtk
469 self.set_inputhook(inputhook_gtk)
479 self.set_inputhook(inputhook_gtk)
470 self._current_gui = GUI_GTK
480 self._current_gui = GUI_GTK
471
481
472 def disable_gtk(self):
482 def disable_gtk(self):
473 """Disable event loop integration with PyGTK.
483 """Disable event loop integration with PyGTK.
474
484
475 This merely sets PyOS_InputHook to NULL.
485 This merely sets PyOS_InputHook to NULL.
476 """
486 """
477 self.clear_inputhook()
487 self.clear_inputhook()
478
488
479 def enable_tk(self, app=False):
489 def enable_tk(self, app=False):
480 """Enable event loop integration with Tk.
490 """Enable event loop integration with Tk.
481
491
482 Parameters
492 Parameters
483 ----------
493 ----------
484 app : bool
494 app : bool
485 Create a running application object or not.
495 Create a running application object or not.
486
496
487 Notes
497 Notes
488 -----
498 -----
489 Currently this is a no-op as creating a :class:`Tkinter.Tk` object
499 Currently this is a no-op as creating a :class:`Tkinter.Tk` object
490 sets ``PyOS_InputHook``.
500 sets ``PyOS_InputHook``.
491 """
501 """
492 self._current_gui = GUI_TK
502 self._current_gui = GUI_TK
493 if app:
503 if app:
494 import Tkinter
504 import Tkinter
495 app = Tkinter.Tk()
505 app = Tkinter.Tk()
496 app.withdraw()
506 app.withdraw()
497 self._apps[GUI_TK] = app
507 self._apps[GUI_TK] = app
498 return app
508 return app
499
509
500 def disable_tk(self):
510 def disable_tk(self):
501 """Disable event loop integration with Tkinter.
511 """Disable event loop integration with Tkinter.
502
512
503 This merely sets PyOS_InputHook to NULL.
513 This merely sets PyOS_InputHook to NULL.
504 """
514 """
505 self.clear_inputhook()
515 self.clear_inputhook()
506
516
507 def current_gui(self):
517 def current_gui(self):
508 """Return a string indicating the currently active GUI or None."""
518 """Return a string indicating the currently active GUI or None."""
509 return self._current_gui
519 return self._current_gui
510
520
511 inputhook_manager = InputHookManager()
521 inputhook_manager = InputHookManager()
512
522
513 enable_wx = inputhook_manager.enable_wx
523 enable_wx = inputhook_manager.enable_wx
514 disable_wx = inputhook_manager.disable_wx
524 disable_wx = inputhook_manager.disable_wx
515 enable_qt4 = inputhook_manager.enable_qt4
525 enable_qt4 = inputhook_manager.enable_qt4
516 disable_qt4 = inputhook_manager.disable_qt4
526 disable_qt4 = inputhook_manager.disable_qt4
517 enable_gtk = inputhook_manager.enable_gtk
527 enable_gtk = inputhook_manager.enable_gtk
518 disable_gtk = inputhook_manager.disable_gtk
528 disable_gtk = inputhook_manager.disable_gtk
519 enable_tk = inputhook_manager.enable_tk
529 enable_tk = inputhook_manager.enable_tk
520 disable_tk = inputhook_manager.disable_tk
530 disable_tk = inputhook_manager.disable_tk
521 clear_inputhook = inputhook_manager.clear_inputhook
531 clear_inputhook = inputhook_manager.clear_inputhook
522 set_inputhook = inputhook_manager.set_inputhook
532 set_inputhook = inputhook_manager.set_inputhook
523 current_gui = inputhook_manager.current_gui
533 current_gui = inputhook_manager.current_gui
524 clear_app_refs = inputhook_manager.clear_app_refs
534 clear_app_refs = inputhook_manager.clear_app_refs
525 spin = inputhook_manager.spin
535 spin = inputhook_manager.spin
536
537
538 # Convenience function to switch amongst them
539 def enable_gui(gui=None, app=True):
540 """Switch amongst GUI input hooks by name.
541
542 This is just a utility wrapper around the methods of the InputHookManager
543 object.
544
545 Parameters
546 ----------
547 gui : optional, string or None
548 If None, clears input hook, otherwise it must be one of the recognized
549 GUI names (see ``GUI_*`` constants in module).
550
551 app : optional, bool
552 If true, create an app object and return it.
553
554 Returns
555 -------
556 The output of the underlying gui switch routine, typically the actual
557 PyOS_InputHook wrapper object or the GUI toolkit app created, if there was
558 one.
559 """
560 guis = {None: clear_inputhook,
561 GUI_TK: enable_tk,
562 GUI_GTK: enable_gtk,
563 GUI_WX: enable_wx,
564 GUI_QT: enable_qt4, # qt3 not supported
565 GUI_QT4: enable_qt4 }
566 try:
567 gui_hook = guis[gui]
568 except KeyError:
569 e="Invalid GUI request %r, valid ones are:%s" % (gui, guis.keys())
570 raise ValueError(e)
571 return gui_hook(app)
General Comments 0
You need to be logged in to leave comments. Login now