##// END OF EJS Templates
Better handling of `__file__` when running scripts....
Bradley M. Froehle -
Show More
@@ -0,0 +1,71 b''
1 # encoding: utf-8
2 """
3 Context managers for temporarily updating dictionaries.
4
5 Authors:
6
7 * Bradley Froehle
8 """
9
10 #-----------------------------------------------------------------------------
11 # Copyright (C) 2012 The IPython Development Team
12 #
13 # Distributed under the terms of the BSD License. The full license is in
14 # the file COPYING, distributed as part of this software.
15 #-----------------------------------------------------------------------------
16
17 #-----------------------------------------------------------------------------
18 # Code
19 #-----------------------------------------------------------------------------
20
21 class preserve_keys(object):
22 """Preserve a set of keys in a dictionary.
23
24 Upon entering the context manager the current values of the keys
25 will be saved. Upon exiting, the dictionary will be updated to
26 restore the original value of the preserved keys. Preserved keys
27 which did not exist when entering the context manager will be
28 deleted.
29
30 Example
31 -------
32
33 >>> d = {'a': 1, 'b': 2, 'c': 3}
34 >>> with preserve_keys(d, 'b', 'c', 'd'):
35 ... del d['a']
36 ... del d['b'] # will be reset to 2
37 ... d['c'] = None # will be reset to 3
38 ... d['d'] = 4 # will be deleted
39 ... d['e'] = 5
40 ... print(sorted(d.items()))
41 ...
42 [('c', None), ('d', 4), ('e', 5)]
43 >>> print(sorted(d.items()))
44 [('b', 2), ('c', 3), ('e', 5)]
45 """
46
47 def __init__(self, dictionary, *keys):
48 self.dictionary = dictionary
49 self.keys = keys
50
51 def __enter__(self):
52 # Actions to perform upon exiting.
53 to_delete = []
54 to_update = {}
55
56 d = self.dictionary
57 for k in self.keys:
58 if k in d:
59 to_update[k] = d[k]
60 else:
61 to_delete.append(k)
62
63 self.to_delete = to_delete
64 self.to_update = to_update
65
66 def __exit__(self, *exc_info):
67 d = self.dictionary
68
69 for k in self.to_delete:
70 d.pop(k, None)
71 d.update(self.to_update)
@@ -1,1016 +1,1020 b''
1 """Implementation of execution-related magic functions.
1 """Implementation of execution-related magic functions.
2 """
2 """
3 #-----------------------------------------------------------------------------
3 #-----------------------------------------------------------------------------
4 # Copyright (c) 2012 The IPython Development Team.
4 # Copyright (c) 2012 The IPython Development Team.
5 #
5 #
6 # Distributed under the terms of the Modified BSD License.
6 # Distributed under the terms of the Modified BSD License.
7 #
7 #
8 # The full license is in the file COPYING.txt, distributed with this software.
8 # The full license is in the file COPYING.txt, distributed with this software.
9 #-----------------------------------------------------------------------------
9 #-----------------------------------------------------------------------------
10
10
11 #-----------------------------------------------------------------------------
11 #-----------------------------------------------------------------------------
12 # Imports
12 # Imports
13 #-----------------------------------------------------------------------------
13 #-----------------------------------------------------------------------------
14
14
15 # Stdlib
15 # Stdlib
16 import __builtin__ as builtin_mod
16 import __builtin__ as builtin_mod
17 import bdb
17 import bdb
18 import os
18 import os
19 import sys
19 import sys
20 import time
20 import time
21 from StringIO import StringIO
21 from StringIO import StringIO
22
22
23 # cProfile was added in Python2.5
23 # cProfile was added in Python2.5
24 try:
24 try:
25 import cProfile as profile
25 import cProfile as profile
26 import pstats
26 import pstats
27 except ImportError:
27 except ImportError:
28 # profile isn't bundled by default in Debian for license reasons
28 # profile isn't bundled by default in Debian for license reasons
29 try:
29 try:
30 import profile, pstats
30 import profile, pstats
31 except ImportError:
31 except ImportError:
32 profile = pstats = None
32 profile = pstats = None
33
33
34 # Our own packages
34 # Our own packages
35 from IPython.core import debugger, oinspect
35 from IPython.core import debugger, oinspect
36 from IPython.core import magic_arguments
36 from IPython.core import magic_arguments
37 from IPython.core import page
37 from IPython.core import page
38 from IPython.core.error import UsageError
38 from IPython.core.error import UsageError
39 from IPython.core.macro import Macro
39 from IPython.core.macro import Macro
40 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
40 from IPython.core.magic import (Magics, magics_class, line_magic, cell_magic,
41 line_cell_magic, on_off, needs_local_scope)
41 line_cell_magic, on_off, needs_local_scope)
42 from IPython.testing.skipdoctest import skip_doctest
42 from IPython.testing.skipdoctest import skip_doctest
43 from IPython.utils import py3compat
43 from IPython.utils import py3compat
44 from IPython.utils.contexts import preserve_keys
44 from IPython.utils.io import capture_output
45 from IPython.utils.io import capture_output
45 from IPython.utils.ipstruct import Struct
46 from IPython.utils.ipstruct import Struct
46 from IPython.utils.module_paths import find_mod
47 from IPython.utils.module_paths import find_mod
47 from IPython.utils.path import get_py_filename, unquote_filename
48 from IPython.utils.path import get_py_filename, unquote_filename
48 from IPython.utils.timing import clock, clock2
49 from IPython.utils.timing import clock, clock2
49 from IPython.utils.warn import warn, error
50 from IPython.utils.warn import warn, error
50
51
51 #-----------------------------------------------------------------------------
52 #-----------------------------------------------------------------------------
52 # Magic implementation classes
53 # Magic implementation classes
53 #-----------------------------------------------------------------------------
54 #-----------------------------------------------------------------------------
54
55
55 @magics_class
56 @magics_class
56 class ExecutionMagics(Magics):
57 class ExecutionMagics(Magics):
57 """Magics related to code execution, debugging, profiling, etc.
58 """Magics related to code execution, debugging, profiling, etc.
58
59
59 """
60 """
60
61
61 def __init__(self, shell):
62 def __init__(self, shell):
62 super(ExecutionMagics, self).__init__(shell)
63 super(ExecutionMagics, self).__init__(shell)
63 if profile is None:
64 if profile is None:
64 self.prun = self.profile_missing_notice
65 self.prun = self.profile_missing_notice
65 # Default execution function used to actually run user code.
66 # Default execution function used to actually run user code.
66 self.default_runner = None
67 self.default_runner = None
67
68
68 def profile_missing_notice(self, *args, **kwargs):
69 def profile_missing_notice(self, *args, **kwargs):
69 error("""\
70 error("""\
70 The profile module could not be found. It has been removed from the standard
71 The profile module could not be found. It has been removed from the standard
71 python packages because of its non-free license. To use profiling, install the
72 python packages because of its non-free license. To use profiling, install the
72 python-profiler package from non-free.""")
73 python-profiler package from non-free.""")
73
74
74 @skip_doctest
75 @skip_doctest
75 @line_cell_magic
76 @line_cell_magic
76 def prun(self, parameter_s='', cell=None, user_mode=True,
77 def prun(self, parameter_s='', cell=None, user_mode=True,
77 opts=None,arg_lst=None,prog_ns=None):
78 opts=None,arg_lst=None,prog_ns=None):
78
79
79 """Run a statement through the python code profiler.
80 """Run a statement through the python code profiler.
80
81
81 Usage, in line mode:
82 Usage, in line mode:
82 %prun [options] statement
83 %prun [options] statement
83
84
84 Usage, in cell mode:
85 Usage, in cell mode:
85 %%prun [options] [statement]
86 %%prun [options] [statement]
86 code...
87 code...
87 code...
88 code...
88
89
89 In cell mode, the additional code lines are appended to the (possibly
90 In cell mode, the additional code lines are appended to the (possibly
90 empty) statement in the first line. Cell mode allows you to easily
91 empty) statement in the first line. Cell mode allows you to easily
91 profile multiline blocks without having to put them in a separate
92 profile multiline blocks without having to put them in a separate
92 function.
93 function.
93
94
94 The given statement (which doesn't require quote marks) is run via the
95 The given statement (which doesn't require quote marks) is run via the
95 python profiler in a manner similar to the profile.run() function.
96 python profiler in a manner similar to the profile.run() function.
96 Namespaces are internally managed to work correctly; profile.run
97 Namespaces are internally managed to work correctly; profile.run
97 cannot be used in IPython because it makes certain assumptions about
98 cannot be used in IPython because it makes certain assumptions about
98 namespaces which do not hold under IPython.
99 namespaces which do not hold under IPython.
99
100
100 Options:
101 Options:
101
102
102 -l <limit>: you can place restrictions on what or how much of the
103 -l <limit>: you can place restrictions on what or how much of the
103 profile gets printed. The limit value can be:
104 profile gets printed. The limit value can be:
104
105
105 * A string: only information for function names containing this string
106 * A string: only information for function names containing this string
106 is printed.
107 is printed.
107
108
108 * An integer: only these many lines are printed.
109 * An integer: only these many lines are printed.
109
110
110 * A float (between 0 and 1): this fraction of the report is printed
111 * A float (between 0 and 1): this fraction of the report is printed
111 (for example, use a limit of 0.4 to see the topmost 40% only).
112 (for example, use a limit of 0.4 to see the topmost 40% only).
112
113
113 You can combine several limits with repeated use of the option. For
114 You can combine several limits with repeated use of the option. For
114 example, '-l __init__ -l 5' will print only the topmost 5 lines of
115 example, '-l __init__ -l 5' will print only the topmost 5 lines of
115 information about class constructors.
116 information about class constructors.
116
117
117 -r: return the pstats.Stats object generated by the profiling. This
118 -r: return the pstats.Stats object generated by the profiling. This
118 object has all the information about the profile in it, and you can
119 object has all the information about the profile in it, and you can
119 later use it for further analysis or in other functions.
120 later use it for further analysis or in other functions.
120
121
121 -s <key>: sort profile by given key. You can provide more than one key
122 -s <key>: sort profile by given key. You can provide more than one key
122 by using the option several times: '-s key1 -s key2 -s key3...'. The
123 by using the option several times: '-s key1 -s key2 -s key3...'. The
123 default sorting key is 'time'.
124 default sorting key is 'time'.
124
125
125 The following is copied verbatim from the profile documentation
126 The following is copied verbatim from the profile documentation
126 referenced below:
127 referenced below:
127
128
128 When more than one key is provided, additional keys are used as
129 When more than one key is provided, additional keys are used as
129 secondary criteria when the there is equality in all keys selected
130 secondary criteria when the there is equality in all keys selected
130 before them.
131 before them.
131
132
132 Abbreviations can be used for any key names, as long as the
133 Abbreviations can be used for any key names, as long as the
133 abbreviation is unambiguous. The following are the keys currently
134 abbreviation is unambiguous. The following are the keys currently
134 defined:
135 defined:
135
136
136 Valid Arg Meaning
137 Valid Arg Meaning
137 "calls" call count
138 "calls" call count
138 "cumulative" cumulative time
139 "cumulative" cumulative time
139 "file" file name
140 "file" file name
140 "module" file name
141 "module" file name
141 "pcalls" primitive call count
142 "pcalls" primitive call count
142 "line" line number
143 "line" line number
143 "name" function name
144 "name" function name
144 "nfl" name/file/line
145 "nfl" name/file/line
145 "stdname" standard name
146 "stdname" standard name
146 "time" internal time
147 "time" internal time
147
148
148 Note that all sorts on statistics are in descending order (placing
149 Note that all sorts on statistics are in descending order (placing
149 most time consuming items first), where as name, file, and line number
150 most time consuming items first), where as name, file, and line number
150 searches are in ascending order (i.e., alphabetical). The subtle
151 searches are in ascending order (i.e., alphabetical). The subtle
151 distinction between "nfl" and "stdname" is that the standard name is a
152 distinction between "nfl" and "stdname" is that the standard name is a
152 sort of the name as printed, which means that the embedded line
153 sort of the name as printed, which means that the embedded line
153 numbers get compared in an odd way. For example, lines 3, 20, and 40
154 numbers get compared in an odd way. For example, lines 3, 20, and 40
154 would (if the file names were the same) appear in the string order
155 would (if the file names were the same) appear in the string order
155 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
156 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
156 line numbers. In fact, sort_stats("nfl") is the same as
157 line numbers. In fact, sort_stats("nfl") is the same as
157 sort_stats("name", "file", "line").
158 sort_stats("name", "file", "line").
158
159
159 -T <filename>: save profile results as shown on screen to a text
160 -T <filename>: save profile results as shown on screen to a text
160 file. The profile is still shown on screen.
161 file. The profile is still shown on screen.
161
162
162 -D <filename>: save (via dump_stats) profile statistics to given
163 -D <filename>: save (via dump_stats) profile statistics to given
163 filename. This data is in a format understood by the pstats module, and
164 filename. This data is in a format understood by the pstats module, and
164 is generated by a call to the dump_stats() method of profile
165 is generated by a call to the dump_stats() method of profile
165 objects. The profile is still shown on screen.
166 objects. The profile is still shown on screen.
166
167
167 -q: suppress output to the pager. Best used with -T and/or -D above.
168 -q: suppress output to the pager. Best used with -T and/or -D above.
168
169
169 If you want to run complete programs under the profiler's control, use
170 If you want to run complete programs under the profiler's control, use
170 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
171 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
171 contains profiler specific options as described here.
172 contains profiler specific options as described here.
172
173
173 You can read the complete documentation for the profile module with::
174 You can read the complete documentation for the profile module with::
174
175
175 In [1]: import profile; profile.help()
176 In [1]: import profile; profile.help()
176 """
177 """
177
178
178 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
179 opts_def = Struct(D=[''],l=[],s=['time'],T=[''])
179
180
180 if user_mode: # regular user call
181 if user_mode: # regular user call
181 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
182 opts,arg_str = self.parse_options(parameter_s,'D:l:rs:T:q',
182 list_all=True, posix=False)
183 list_all=True, posix=False)
183 namespace = self.shell.user_ns
184 namespace = self.shell.user_ns
184 if cell is not None:
185 if cell is not None:
185 arg_str += '\n' + cell
186 arg_str += '\n' + cell
186 else: # called to run a program by %run -p
187 else: # called to run a program by %run -p
187 try:
188 try:
188 filename = get_py_filename(arg_lst[0])
189 filename = get_py_filename(arg_lst[0])
189 except IOError as e:
190 except IOError as e:
190 try:
191 try:
191 msg = str(e)
192 msg = str(e)
192 except UnicodeError:
193 except UnicodeError:
193 msg = e.message
194 msg = e.message
194 error(msg)
195 error(msg)
195 return
196 return
196
197
197 arg_str = 'execfile(filename,prog_ns)'
198 arg_str = 'execfile(filename,prog_ns)'
198 namespace = {
199 namespace = {
199 'execfile': self.shell.safe_execfile,
200 'execfile': self.shell.safe_execfile,
200 'prog_ns': prog_ns,
201 'prog_ns': prog_ns,
201 'filename': filename
202 'filename': filename
202 }
203 }
203
204
204 opts.merge(opts_def)
205 opts.merge(opts_def)
205
206
206 prof = profile.Profile()
207 prof = profile.Profile()
207 try:
208 try:
208 prof = prof.runctx(arg_str,namespace,namespace)
209 prof = prof.runctx(arg_str,namespace,namespace)
209 sys_exit = ''
210 sys_exit = ''
210 except SystemExit:
211 except SystemExit:
211 sys_exit = """*** SystemExit exception caught in code being profiled."""
212 sys_exit = """*** SystemExit exception caught in code being profiled."""
212
213
213 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
214 stats = pstats.Stats(prof).strip_dirs().sort_stats(*opts.s)
214
215
215 lims = opts.l
216 lims = opts.l
216 if lims:
217 if lims:
217 lims = [] # rebuild lims with ints/floats/strings
218 lims = [] # rebuild lims with ints/floats/strings
218 for lim in opts.l:
219 for lim in opts.l:
219 try:
220 try:
220 lims.append(int(lim))
221 lims.append(int(lim))
221 except ValueError:
222 except ValueError:
222 try:
223 try:
223 lims.append(float(lim))
224 lims.append(float(lim))
224 except ValueError:
225 except ValueError:
225 lims.append(lim)
226 lims.append(lim)
226
227
227 # Trap output.
228 # Trap output.
228 stdout_trap = StringIO()
229 stdout_trap = StringIO()
229 stats_stream = stats.stream
230 stats_stream = stats.stream
230 try:
231 try:
231 stats.stream = stdout_trap
232 stats.stream = stdout_trap
232 stats.print_stats(*lims)
233 stats.print_stats(*lims)
233 finally:
234 finally:
234 stats.stream = stats_stream
235 stats.stream = stats_stream
235
236
236 output = stdout_trap.getvalue()
237 output = stdout_trap.getvalue()
237 output = output.rstrip()
238 output = output.rstrip()
238
239
239 if 'q' not in opts:
240 if 'q' not in opts:
240 page.page(output)
241 page.page(output)
241 print sys_exit,
242 print sys_exit,
242
243
243 dump_file = opts.D[0]
244 dump_file = opts.D[0]
244 text_file = opts.T[0]
245 text_file = opts.T[0]
245 if dump_file:
246 if dump_file:
246 dump_file = unquote_filename(dump_file)
247 dump_file = unquote_filename(dump_file)
247 prof.dump_stats(dump_file)
248 prof.dump_stats(dump_file)
248 print '\n*** Profile stats marshalled to file',\
249 print '\n*** Profile stats marshalled to file',\
249 repr(dump_file)+'.',sys_exit
250 repr(dump_file)+'.',sys_exit
250 if text_file:
251 if text_file:
251 text_file = unquote_filename(text_file)
252 text_file = unquote_filename(text_file)
252 pfile = open(text_file,'w')
253 pfile = open(text_file,'w')
253 pfile.write(output)
254 pfile.write(output)
254 pfile.close()
255 pfile.close()
255 print '\n*** Profile printout saved to text file',\
256 print '\n*** Profile printout saved to text file',\
256 repr(text_file)+'.',sys_exit
257 repr(text_file)+'.',sys_exit
257
258
258 if 'r' in opts:
259 if 'r' in opts:
259 return stats
260 return stats
260 else:
261 else:
261 return None
262 return None
262
263
263 @line_magic
264 @line_magic
264 def pdb(self, parameter_s=''):
265 def pdb(self, parameter_s=''):
265 """Control the automatic calling of the pdb interactive debugger.
266 """Control the automatic calling of the pdb interactive debugger.
266
267
267 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
268 Call as '%pdb on', '%pdb 1', '%pdb off' or '%pdb 0'. If called without
268 argument it works as a toggle.
269 argument it works as a toggle.
269
270
270 When an exception is triggered, IPython can optionally call the
271 When an exception is triggered, IPython can optionally call the
271 interactive pdb debugger after the traceback printout. %pdb toggles
272 interactive pdb debugger after the traceback printout. %pdb toggles
272 this feature on and off.
273 this feature on and off.
273
274
274 The initial state of this feature is set in your configuration
275 The initial state of this feature is set in your configuration
275 file (the option is ``InteractiveShell.pdb``).
276 file (the option is ``InteractiveShell.pdb``).
276
277
277 If you want to just activate the debugger AFTER an exception has fired,
278 If you want to just activate the debugger AFTER an exception has fired,
278 without having to type '%pdb on' and rerunning your code, you can use
279 without having to type '%pdb on' and rerunning your code, you can use
279 the %debug magic."""
280 the %debug magic."""
280
281
281 par = parameter_s.strip().lower()
282 par = parameter_s.strip().lower()
282
283
283 if par:
284 if par:
284 try:
285 try:
285 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
286 new_pdb = {'off':0,'0':0,'on':1,'1':1}[par]
286 except KeyError:
287 except KeyError:
287 print ('Incorrect argument. Use on/1, off/0, '
288 print ('Incorrect argument. Use on/1, off/0, '
288 'or nothing for a toggle.')
289 'or nothing for a toggle.')
289 return
290 return
290 else:
291 else:
291 # toggle
292 # toggle
292 new_pdb = not self.shell.call_pdb
293 new_pdb = not self.shell.call_pdb
293
294
294 # set on the shell
295 # set on the shell
295 self.shell.call_pdb = new_pdb
296 self.shell.call_pdb = new_pdb
296 print 'Automatic pdb calling has been turned',on_off(new_pdb)
297 print 'Automatic pdb calling has been turned',on_off(new_pdb)
297
298
298 @line_magic
299 @line_magic
299 def debug(self, parameter_s=''):
300 def debug(self, parameter_s=''):
300 """Activate the interactive debugger in post-mortem mode.
301 """Activate the interactive debugger in post-mortem mode.
301
302
302 If an exception has just occurred, this lets you inspect its stack
303 If an exception has just occurred, this lets you inspect its stack
303 frames interactively. Note that this will always work only on the last
304 frames interactively. Note that this will always work only on the last
304 traceback that occurred, so you must call this quickly after an
305 traceback that occurred, so you must call this quickly after an
305 exception that you wish to inspect has fired, because if another one
306 exception that you wish to inspect has fired, because if another one
306 occurs, it clobbers the previous one.
307 occurs, it clobbers the previous one.
307
308
308 If you want IPython to automatically do this on every exception, see
309 If you want IPython to automatically do this on every exception, see
309 the %pdb magic for more details.
310 the %pdb magic for more details.
310 """
311 """
311 self.shell.debugger(force=True)
312 self.shell.debugger(force=True)
312
313
313 @line_magic
314 @line_magic
314 def tb(self, s):
315 def tb(self, s):
315 """Print the last traceback with the currently active exception mode.
316 """Print the last traceback with the currently active exception mode.
316
317
317 See %xmode for changing exception reporting modes."""
318 See %xmode for changing exception reporting modes."""
318 self.shell.showtraceback()
319 self.shell.showtraceback()
319
320
320 @skip_doctest
321 @skip_doctest
321 @line_magic
322 @line_magic
322 def run(self, parameter_s='', runner=None,
323 def run(self, parameter_s='', runner=None,
323 file_finder=get_py_filename):
324 file_finder=get_py_filename):
324 """Run the named file inside IPython as a program.
325 """Run the named file inside IPython as a program.
325
326
326 Usage:\\
327 Usage:\\
327 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
328 %run [-n -i -t [-N<N>] -d [-b<N>] -p [profile options]] file [args]
328
329
329 Parameters after the filename are passed as command-line arguments to
330 Parameters after the filename are passed as command-line arguments to
330 the program (put in sys.argv). Then, control returns to IPython's
331 the program (put in sys.argv). Then, control returns to IPython's
331 prompt.
332 prompt.
332
333
333 This is similar to running at a system prompt:\\
334 This is similar to running at a system prompt:\\
334 $ python file args\\
335 $ python file args\\
335 but with the advantage of giving you IPython's tracebacks, and of
336 but with the advantage of giving you IPython's tracebacks, and of
336 loading all variables into your interactive namespace for further use
337 loading all variables into your interactive namespace for further use
337 (unless -p is used, see below).
338 (unless -p is used, see below).
338
339
339 The file is executed in a namespace initially consisting only of
340 The file is executed in a namespace initially consisting only of
340 __name__=='__main__' and sys.argv constructed as indicated. It thus
341 __name__=='__main__' and sys.argv constructed as indicated. It thus
341 sees its environment as if it were being run as a stand-alone program
342 sees its environment as if it were being run as a stand-alone program
342 (except for sharing global objects such as previously imported
343 (except for sharing global objects such as previously imported
343 modules). But after execution, the IPython interactive namespace gets
344 modules). But after execution, the IPython interactive namespace gets
344 updated with all variables defined in the program (except for __name__
345 updated with all variables defined in the program (except for __name__
345 and sys.argv). This allows for very convenient loading of code for
346 and sys.argv). This allows for very convenient loading of code for
346 interactive work, while giving each program a 'clean sheet' to run in.
347 interactive work, while giving each program a 'clean sheet' to run in.
347
348
348 Options:
349 Options:
349
350
350 -n: __name__ is NOT set to '__main__', but to the running file's name
351 -n: __name__ is NOT set to '__main__', but to the running file's name
351 without extension (as python does under import). This allows running
352 without extension (as python does under import). This allows running
352 scripts and reloading the definitions in them without calling code
353 scripts and reloading the definitions in them without calling code
353 protected by an ' if __name__ == "__main__" ' clause.
354 protected by an ' if __name__ == "__main__" ' clause.
354
355
355 -i: run the file in IPython's namespace instead of an empty one. This
356 -i: run the file in IPython's namespace instead of an empty one. This
356 is useful if you are experimenting with code written in a text editor
357 is useful if you are experimenting with code written in a text editor
357 which depends on variables defined interactively.
358 which depends on variables defined interactively.
358
359
359 -e: ignore sys.exit() calls or SystemExit exceptions in the script
360 -e: ignore sys.exit() calls or SystemExit exceptions in the script
360 being run. This is particularly useful if IPython is being used to
361 being run. This is particularly useful if IPython is being used to
361 run unittests, which always exit with a sys.exit() call. In such
362 run unittests, which always exit with a sys.exit() call. In such
362 cases you are interested in the output of the test results, not in
363 cases you are interested in the output of the test results, not in
363 seeing a traceback of the unittest module.
364 seeing a traceback of the unittest module.
364
365
365 -t: print timing information at the end of the run. IPython will give
366 -t: print timing information at the end of the run. IPython will give
366 you an estimated CPU time consumption for your script, which under
367 you an estimated CPU time consumption for your script, which under
367 Unix uses the resource module to avoid the wraparound problems of
368 Unix uses the resource module to avoid the wraparound problems of
368 time.clock(). Under Unix, an estimate of time spent on system tasks
369 time.clock(). Under Unix, an estimate of time spent on system tasks
369 is also given (for Windows platforms this is reported as 0.0).
370 is also given (for Windows platforms this is reported as 0.0).
370
371
371 If -t is given, an additional -N<N> option can be given, where <N>
372 If -t is given, an additional -N<N> option can be given, where <N>
372 must be an integer indicating how many times you want the script to
373 must be an integer indicating how many times you want the script to
373 run. The final timing report will include total and per run results.
374 run. The final timing report will include total and per run results.
374
375
375 For example (testing the script uniq_stable.py)::
376 For example (testing the script uniq_stable.py)::
376
377
377 In [1]: run -t uniq_stable
378 In [1]: run -t uniq_stable
378
379
379 IPython CPU timings (estimated):\\
380 IPython CPU timings (estimated):\\
380 User : 0.19597 s.\\
381 User : 0.19597 s.\\
381 System: 0.0 s.\\
382 System: 0.0 s.\\
382
383
383 In [2]: run -t -N5 uniq_stable
384 In [2]: run -t -N5 uniq_stable
384
385
385 IPython CPU timings (estimated):\\
386 IPython CPU timings (estimated):\\
386 Total runs performed: 5\\
387 Total runs performed: 5\\
387 Times : Total Per run\\
388 Times : Total Per run\\
388 User : 0.910862 s, 0.1821724 s.\\
389 User : 0.910862 s, 0.1821724 s.\\
389 System: 0.0 s, 0.0 s.
390 System: 0.0 s, 0.0 s.
390
391
391 -d: run your program under the control of pdb, the Python debugger.
392 -d: run your program under the control of pdb, the Python debugger.
392 This allows you to execute your program step by step, watch variables,
393 This allows you to execute your program step by step, watch variables,
393 etc. Internally, what IPython does is similar to calling:
394 etc. Internally, what IPython does is similar to calling:
394
395
395 pdb.run('execfile("YOURFILENAME")')
396 pdb.run('execfile("YOURFILENAME")')
396
397
397 with a breakpoint set on line 1 of your file. You can change the line
398 with a breakpoint set on line 1 of your file. You can change the line
398 number for this automatic breakpoint to be <N> by using the -bN option
399 number for this automatic breakpoint to be <N> by using the -bN option
399 (where N must be an integer). For example::
400 (where N must be an integer). For example::
400
401
401 %run -d -b40 myscript
402 %run -d -b40 myscript
402
403
403 will set the first breakpoint at line 40 in myscript.py. Note that
404 will set the first breakpoint at line 40 in myscript.py. Note that
404 the first breakpoint must be set on a line which actually does
405 the first breakpoint must be set on a line which actually does
405 something (not a comment or docstring) for it to stop execution.
406 something (not a comment or docstring) for it to stop execution.
406
407
407 When the pdb debugger starts, you will see a (Pdb) prompt. You must
408 When the pdb debugger starts, you will see a (Pdb) prompt. You must
408 first enter 'c' (without quotes) to start execution up to the first
409 first enter 'c' (without quotes) to start execution up to the first
409 breakpoint.
410 breakpoint.
410
411
411 Entering 'help' gives information about the use of the debugger. You
412 Entering 'help' gives information about the use of the debugger. You
412 can easily see pdb's full documentation with "import pdb;pdb.help()"
413 can easily see pdb's full documentation with "import pdb;pdb.help()"
413 at a prompt.
414 at a prompt.
414
415
415 -p: run program under the control of the Python profiler module (which
416 -p: run program under the control of the Python profiler module (which
416 prints a detailed report of execution times, function calls, etc).
417 prints a detailed report of execution times, function calls, etc).
417
418
418 You can pass other options after -p which affect the behavior of the
419 You can pass other options after -p which affect the behavior of the
419 profiler itself. See the docs for %prun for details.
420 profiler itself. See the docs for %prun for details.
420
421
421 In this mode, the program's variables do NOT propagate back to the
422 In this mode, the program's variables do NOT propagate back to the
422 IPython interactive namespace (because they remain in the namespace
423 IPython interactive namespace (because they remain in the namespace
423 where the profiler executes them).
424 where the profiler executes them).
424
425
425 Internally this triggers a call to %prun, see its documentation for
426 Internally this triggers a call to %prun, see its documentation for
426 details on the options available specifically for profiling.
427 details on the options available specifically for profiling.
427
428
428 There is one special usage for which the text above doesn't apply:
429 There is one special usage for which the text above doesn't apply:
429 if the filename ends with .ipy, the file is run as ipython script,
430 if the filename ends with .ipy, the file is run as ipython script,
430 just as if the commands were written on IPython prompt.
431 just as if the commands were written on IPython prompt.
431
432
432 -m: specify module name to load instead of script path. Similar to
433 -m: specify module name to load instead of script path. Similar to
433 the -m option for the python interpreter. Use this option last if you
434 the -m option for the python interpreter. Use this option last if you
434 want to combine with other %run options. Unlike the python interpreter
435 want to combine with other %run options. Unlike the python interpreter
435 only source modules are allowed no .pyc or .pyo files.
436 only source modules are allowed no .pyc or .pyo files.
436 For example::
437 For example::
437
438
438 %run -m example
439 %run -m example
439
440
440 will run the example module.
441 will run the example module.
441
442
442 """
443 """
443
444
444 # get arguments and set sys.argv for program to be run.
445 # get arguments and set sys.argv for program to be run.
445 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
446 opts, arg_lst = self.parse_options(parameter_s, 'nidtN:b:pD:l:rs:T:em:',
446 mode='list', list_all=1)
447 mode='list', list_all=1)
447 if "m" in opts:
448 if "m" in opts:
448 modulename = opts["m"][0]
449 modulename = opts["m"][0]
449 modpath = find_mod(modulename)
450 modpath = find_mod(modulename)
450 if modpath is None:
451 if modpath is None:
451 warn('%r is not a valid modulename on sys.path'%modulename)
452 warn('%r is not a valid modulename on sys.path'%modulename)
452 return
453 return
453 arg_lst = [modpath] + arg_lst
454 arg_lst = [modpath] + arg_lst
454 try:
455 try:
455 filename = file_finder(arg_lst[0])
456 filename = file_finder(arg_lst[0])
456 except IndexError:
457 except IndexError:
457 warn('you must provide at least a filename.')
458 warn('you must provide at least a filename.')
458 print '\n%run:\n', oinspect.getdoc(self.run)
459 print '\n%run:\n', oinspect.getdoc(self.run)
459 return
460 return
460 except IOError as e:
461 except IOError as e:
461 try:
462 try:
462 msg = str(e)
463 msg = str(e)
463 except UnicodeError:
464 except UnicodeError:
464 msg = e.message
465 msg = e.message
465 error(msg)
466 error(msg)
466 return
467 return
467
468
468 if filename.lower().endswith('.ipy'):
469 if filename.lower().endswith('.ipy'):
470 with preserve_keys(self.shell.user_ns, '__file__'):
471 self.shell.user_ns['__file__'] = filename
469 self.shell.safe_execfile_ipy(filename)
472 self.shell.safe_execfile_ipy(filename)
470 return
473 return
471
474
472 # Control the response to exit() calls made by the script being run
475 # Control the response to exit() calls made by the script being run
473 exit_ignore = 'e' in opts
476 exit_ignore = 'e' in opts
474
477
475 # Make sure that the running script gets a proper sys.argv as if it
478 # Make sure that the running script gets a proper sys.argv as if it
476 # were run from a system shell.
479 # were run from a system shell.
477 save_argv = sys.argv # save it for later restoring
480 save_argv = sys.argv # save it for later restoring
478
481
479 # simulate shell expansion on arguments, at least tilde expansion
482 # simulate shell expansion on arguments, at least tilde expansion
480 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
483 args = [ os.path.expanduser(a) for a in arg_lst[1:] ]
481
484
482 sys.argv = [filename] + args # put in the proper filename
485 sys.argv = [filename] + args # put in the proper filename
483 # protect sys.argv from potential unicode strings on Python 2:
486 # protect sys.argv from potential unicode strings on Python 2:
484 if not py3compat.PY3:
487 if not py3compat.PY3:
485 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
488 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
486
489
487 if 'i' in opts:
490 if 'i' in opts:
488 # Run in user's interactive namespace
491 # Run in user's interactive namespace
489 prog_ns = self.shell.user_ns
492 prog_ns = self.shell.user_ns
490 __name__save = self.shell.user_ns['__name__']
493 __name__save = self.shell.user_ns['__name__']
491 prog_ns['__name__'] = '__main__'
494 prog_ns['__name__'] = '__main__'
492 main_mod = self.shell.new_main_mod(prog_ns)
495 main_mod = self.shell.new_main_mod(prog_ns)
493 else:
496 else:
494 # Run in a fresh, empty namespace
497 # Run in a fresh, empty namespace
495 if 'n' in opts:
498 if 'n' in opts:
496 name = os.path.splitext(os.path.basename(filename))[0]
499 name = os.path.splitext(os.path.basename(filename))[0]
497 else:
500 else:
498 name = '__main__'
501 name = '__main__'
499
502
500 main_mod = self.shell.new_main_mod()
503 main_mod = self.shell.new_main_mod()
501 prog_ns = main_mod.__dict__
504 prog_ns = main_mod.__dict__
502 prog_ns['__name__'] = name
505 prog_ns['__name__'] = name
503
506
504 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
507 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
505 # set the __file__ global in the script's namespace
508 # set the __file__ global in the script's namespace
506 prog_ns['__file__'] = filename
509 prog_ns['__file__'] = filename
507
510
508 # pickle fix. See interactiveshell for an explanation. But we need to
511 # pickle fix. See interactiveshell for an explanation. But we need to
509 # make sure that, if we overwrite __main__, we replace it at the end
512 # make sure that, if we overwrite __main__, we replace it at the end
510 main_mod_name = prog_ns['__name__']
513 main_mod_name = prog_ns['__name__']
511
514
512 if main_mod_name == '__main__':
515 if main_mod_name == '__main__':
513 restore_main = sys.modules['__main__']
516 restore_main = sys.modules['__main__']
514 else:
517 else:
515 restore_main = False
518 restore_main = False
516
519
517 # This needs to be undone at the end to prevent holding references to
520 # This needs to be undone at the end to prevent holding references to
518 # every single object ever created.
521 # every single object ever created.
519 sys.modules[main_mod_name] = main_mod
522 sys.modules[main_mod_name] = main_mod
520
523
521 try:
524 try:
522 stats = None
525 stats = None
523 with self.shell.readline_no_record:
526 with self.shell.readline_no_record:
524 if 'p' in opts:
527 if 'p' in opts:
525 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
528 stats = self.prun('', None, False, opts, arg_lst, prog_ns)
526 else:
529 else:
527 if 'd' in opts:
530 if 'd' in opts:
528 deb = debugger.Pdb(self.shell.colors)
531 deb = debugger.Pdb(self.shell.colors)
529 # reset Breakpoint state, which is moronically kept
532 # reset Breakpoint state, which is moronically kept
530 # in a class
533 # in a class
531 bdb.Breakpoint.next = 1
534 bdb.Breakpoint.next = 1
532 bdb.Breakpoint.bplist = {}
535 bdb.Breakpoint.bplist = {}
533 bdb.Breakpoint.bpbynumber = [None]
536 bdb.Breakpoint.bpbynumber = [None]
534 # Set an initial breakpoint to stop execution
537 # Set an initial breakpoint to stop execution
535 maxtries = 10
538 maxtries = 10
536 bp = int(opts.get('b', [1])[0])
539 bp = int(opts.get('b', [1])[0])
537 checkline = deb.checkline(filename, bp)
540 checkline = deb.checkline(filename, bp)
538 if not checkline:
541 if not checkline:
539 for bp in range(bp + 1, bp + maxtries + 1):
542 for bp in range(bp + 1, bp + maxtries + 1):
540 if deb.checkline(filename, bp):
543 if deb.checkline(filename, bp):
541 break
544 break
542 else:
545 else:
543 msg = ("\nI failed to find a valid line to set "
546 msg = ("\nI failed to find a valid line to set "
544 "a breakpoint\n"
547 "a breakpoint\n"
545 "after trying up to line: %s.\n"
548 "after trying up to line: %s.\n"
546 "Please set a valid breakpoint manually "
549 "Please set a valid breakpoint manually "
547 "with the -b option." % bp)
550 "with the -b option." % bp)
548 error(msg)
551 error(msg)
549 return
552 return
550 # if we find a good linenumber, set the breakpoint
553 # if we find a good linenumber, set the breakpoint
551 deb.do_break('%s:%s' % (filename, bp))
554 deb.do_break('%s:%s' % (filename, bp))
552 # Start file run
555 # Start file run
553 print "NOTE: Enter 'c' at the",
556 print "NOTE: Enter 'c' at the",
554 print "%s prompt to start your script." % deb.prompt
557 print "%s prompt to start your script." % deb.prompt
555 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
558 ns = {'execfile': py3compat.execfile, 'prog_ns': prog_ns}
556 try:
559 try:
557 #save filename so it can be used by methods on the deb object
560 #save filename so it can be used by methods on the deb object
558 deb._exec_filename = filename
561 deb._exec_filename = filename
559 deb.run('execfile("%s", prog_ns)' % filename, ns)
562 deb.run('execfile("%s", prog_ns)' % filename, ns)
560
563
561 except:
564 except:
562 etype, value, tb = sys.exc_info()
565 etype, value, tb = sys.exc_info()
563 # Skip three frames in the traceback: the %run one,
566 # Skip three frames in the traceback: the %run one,
564 # one inside bdb.py, and the command-line typed by the
567 # one inside bdb.py, and the command-line typed by the
565 # user (run by exec in pdb itself).
568 # user (run by exec in pdb itself).
566 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
569 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
567 else:
570 else:
568 if runner is None:
571 if runner is None:
569 runner = self.default_runner
572 runner = self.default_runner
570 if runner is None:
573 if runner is None:
571 runner = self.shell.safe_execfile
574 runner = self.shell.safe_execfile
572 if 't' in opts:
575 if 't' in opts:
573 # timed execution
576 # timed execution
574 try:
577 try:
575 nruns = int(opts['N'][0])
578 nruns = int(opts['N'][0])
576 if nruns < 1:
579 if nruns < 1:
577 error('Number of runs must be >=1')
580 error('Number of runs must be >=1')
578 return
581 return
579 except (KeyError):
582 except (KeyError):
580 nruns = 1
583 nruns = 1
581 twall0 = time.time()
584 twall0 = time.time()
582 if nruns == 1:
585 if nruns == 1:
583 t0 = clock2()
586 t0 = clock2()
584 runner(filename, prog_ns, prog_ns,
587 runner(filename, prog_ns, prog_ns,
585 exit_ignore=exit_ignore)
588 exit_ignore=exit_ignore)
586 t1 = clock2()
589 t1 = clock2()
587 t_usr = t1[0] - t0[0]
590 t_usr = t1[0] - t0[0]
588 t_sys = t1[1] - t0[1]
591 t_sys = t1[1] - t0[1]
589 print "\nIPython CPU timings (estimated):"
592 print "\nIPython CPU timings (estimated):"
590 print " User : %10.2f s." % t_usr
593 print " User : %10.2f s." % t_usr
591 print " System : %10.2f s." % t_sys
594 print " System : %10.2f s." % t_sys
592 else:
595 else:
593 runs = range(nruns)
596 runs = range(nruns)
594 t0 = clock2()
597 t0 = clock2()
595 for nr in runs:
598 for nr in runs:
596 runner(filename, prog_ns, prog_ns,
599 runner(filename, prog_ns, prog_ns,
597 exit_ignore=exit_ignore)
600 exit_ignore=exit_ignore)
598 t1 = clock2()
601 t1 = clock2()
599 t_usr = t1[0] - t0[0]
602 t_usr = t1[0] - t0[0]
600 t_sys = t1[1] - t0[1]
603 t_sys = t1[1] - t0[1]
601 print "\nIPython CPU timings (estimated):"
604 print "\nIPython CPU timings (estimated):"
602 print "Total runs performed:", nruns
605 print "Total runs performed:", nruns
603 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
606 print " Times : %10.2f %10.2f" % ('Total', 'Per run')
604 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
607 print " User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns)
605 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
608 print " System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns)
606 twall1 = time.time()
609 twall1 = time.time()
607 print "Wall time: %10.2f s." % (twall1 - twall0)
610 print "Wall time: %10.2f s." % (twall1 - twall0)
608
611
609 else:
612 else:
610 # regular execution
613 # regular execution
611 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
614 runner(filename, prog_ns, prog_ns, exit_ignore=exit_ignore)
612
615
613 if 'i' in opts:
616 if 'i' in opts:
614 self.shell.user_ns['__name__'] = __name__save
617 self.shell.user_ns['__name__'] = __name__save
615 else:
618 else:
616 # The shell MUST hold a reference to prog_ns so after %run
619 # The shell MUST hold a reference to prog_ns so after %run
617 # exits, the python deletion mechanism doesn't zero it out
620 # exits, the python deletion mechanism doesn't zero it out
618 # (leaving dangling references).
621 # (leaving dangling references).
619 self.shell.cache_main_mod(prog_ns, filename)
622 self.shell.cache_main_mod(prog_ns, filename)
620 # update IPython interactive namespace
623 # update IPython interactive namespace
621
624
622 # Some forms of read errors on the file may mean the
625 # Some forms of read errors on the file may mean the
623 # __name__ key was never set; using pop we don't have to
626 # __name__ key was never set; using pop we don't have to
624 # worry about a possible KeyError.
627 # worry about a possible KeyError.
625 prog_ns.pop('__name__', None)
628 prog_ns.pop('__name__', None)
626
629
630 with preserve_keys(self.shell.user_ns, '__file__'):
627 self.shell.user_ns.update(prog_ns)
631 self.shell.user_ns.update(prog_ns)
628 finally:
632 finally:
629 # It's a bit of a mystery why, but __builtins__ can change from
633 # It's a bit of a mystery why, but __builtins__ can change from
630 # being a module to becoming a dict missing some key data after
634 # being a module to becoming a dict missing some key data after
631 # %run. As best I can see, this is NOT something IPython is doing
635 # %run. As best I can see, this is NOT something IPython is doing
632 # at all, and similar problems have been reported before:
636 # at all, and similar problems have been reported before:
633 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
637 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
634 # Since this seems to be done by the interpreter itself, the best
638 # Since this seems to be done by the interpreter itself, the best
635 # we can do is to at least restore __builtins__ for the user on
639 # we can do is to at least restore __builtins__ for the user on
636 # exit.
640 # exit.
637 self.shell.user_ns['__builtins__'] = builtin_mod
641 self.shell.user_ns['__builtins__'] = builtin_mod
638
642
639 # Ensure key global structures are restored
643 # Ensure key global structures are restored
640 sys.argv = save_argv
644 sys.argv = save_argv
641 if restore_main:
645 if restore_main:
642 sys.modules['__main__'] = restore_main
646 sys.modules['__main__'] = restore_main
643 else:
647 else:
644 # Remove from sys.modules the reference to main_mod we'd
648 # Remove from sys.modules the reference to main_mod we'd
645 # added. Otherwise it will trap references to objects
649 # added. Otherwise it will trap references to objects
646 # contained therein.
650 # contained therein.
647 del sys.modules[main_mod_name]
651 del sys.modules[main_mod_name]
648
652
649 return stats
653 return stats
650
654
651 @skip_doctest
655 @skip_doctest
652 @line_cell_magic
656 @line_cell_magic
653 def timeit(self, line='', cell=None):
657 def timeit(self, line='', cell=None):
654 """Time execution of a Python statement or expression
658 """Time execution of a Python statement or expression
655
659
656 Usage, in line mode:
660 Usage, in line mode:
657 %timeit [-n<N> -r<R> [-t|-c]] statement
661 %timeit [-n<N> -r<R> [-t|-c]] statement
658 or in cell mode:
662 or in cell mode:
659 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
663 %%timeit [-n<N> -r<R> [-t|-c]] setup_code
660 code
664 code
661 code...
665 code...
662
666
663 Time execution of a Python statement or expression using the timeit
667 Time execution of a Python statement or expression using the timeit
664 module. This function can be used both as a line and cell magic:
668 module. This function can be used both as a line and cell magic:
665
669
666 - In line mode you can time a single-line statement (though multiple
670 - In line mode you can time a single-line statement (though multiple
667 ones can be chained with using semicolons).
671 ones can be chained with using semicolons).
668
672
669 - In cell mode, the statement in the first line is used as setup code
673 - In cell mode, the statement in the first line is used as setup code
670 (executed but not timed) and the body of the cell is timed. The cell
674 (executed but not timed) and the body of the cell is timed. The cell
671 body has access to any variables created in the setup code.
675 body has access to any variables created in the setup code.
672
676
673 Options:
677 Options:
674 -n<N>: execute the given statement <N> times in a loop. If this value
678 -n<N>: execute the given statement <N> times in a loop. If this value
675 is not given, a fitting value is chosen.
679 is not given, a fitting value is chosen.
676
680
677 -r<R>: repeat the loop iteration <R> times and take the best result.
681 -r<R>: repeat the loop iteration <R> times and take the best result.
678 Default: 3
682 Default: 3
679
683
680 -t: use time.time to measure the time, which is the default on Unix.
684 -t: use time.time to measure the time, which is the default on Unix.
681 This function measures wall time.
685 This function measures wall time.
682
686
683 -c: use time.clock to measure the time, which is the default on
687 -c: use time.clock to measure the time, which is the default on
684 Windows and measures wall time. On Unix, resource.getrusage is used
688 Windows and measures wall time. On Unix, resource.getrusage is used
685 instead and returns the CPU user time.
689 instead and returns the CPU user time.
686
690
687 -p<P>: use a precision of <P> digits to display the timing result.
691 -p<P>: use a precision of <P> digits to display the timing result.
688 Default: 3
692 Default: 3
689
693
690
694
691 Examples
695 Examples
692 --------
696 --------
693 ::
697 ::
694
698
695 In [1]: %timeit pass
699 In [1]: %timeit pass
696 10000000 loops, best of 3: 53.3 ns per loop
700 10000000 loops, best of 3: 53.3 ns per loop
697
701
698 In [2]: u = None
702 In [2]: u = None
699
703
700 In [3]: %timeit u is None
704 In [3]: %timeit u is None
701 10000000 loops, best of 3: 184 ns per loop
705 10000000 loops, best of 3: 184 ns per loop
702
706
703 In [4]: %timeit -r 4 u == None
707 In [4]: %timeit -r 4 u == None
704 1000000 loops, best of 4: 242 ns per loop
708 1000000 loops, best of 4: 242 ns per loop
705
709
706 In [5]: import time
710 In [5]: import time
707
711
708 In [6]: %timeit -n1 time.sleep(2)
712 In [6]: %timeit -n1 time.sleep(2)
709 1 loops, best of 3: 2 s per loop
713 1 loops, best of 3: 2 s per loop
710
714
711
715
712 The times reported by %timeit will be slightly higher than those
716 The times reported by %timeit will be slightly higher than those
713 reported by the timeit.py script when variables are accessed. This is
717 reported by the timeit.py script when variables are accessed. This is
714 due to the fact that %timeit executes the statement in the namespace
718 due to the fact that %timeit executes the statement in the namespace
715 of the shell, compared with timeit.py, which uses a single setup
719 of the shell, compared with timeit.py, which uses a single setup
716 statement to import function or create variables. Generally, the bias
720 statement to import function or create variables. Generally, the bias
717 does not matter as long as results from timeit.py are not mixed with
721 does not matter as long as results from timeit.py are not mixed with
718 those from %timeit."""
722 those from %timeit."""
719
723
720 import timeit
724 import timeit
721 import math
725 import math
722
726
723 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
727 # XXX: Unfortunately the unicode 'micro' symbol can cause problems in
724 # certain terminals. Until we figure out a robust way of
728 # certain terminals. Until we figure out a robust way of
725 # auto-detecting if the terminal can deal with it, use plain 'us' for
729 # auto-detecting if the terminal can deal with it, use plain 'us' for
726 # microseconds. I am really NOT happy about disabling the proper
730 # microseconds. I am really NOT happy about disabling the proper
727 # 'micro' prefix, but crashing is worse... If anyone knows what the
731 # 'micro' prefix, but crashing is worse... If anyone knows what the
728 # right solution for this is, I'm all ears...
732 # right solution for this is, I'm all ears...
729 #
733 #
730 # Note: using
734 # Note: using
731 #
735 #
732 # s = u'\xb5'
736 # s = u'\xb5'
733 # s.encode(sys.getdefaultencoding())
737 # s.encode(sys.getdefaultencoding())
734 #
738 #
735 # is not sufficient, as I've seen terminals where that fails but
739 # is not sufficient, as I've seen terminals where that fails but
736 # print s
740 # print s
737 #
741 #
738 # succeeds
742 # succeeds
739 #
743 #
740 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
744 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
741
745
742 #units = [u"s", u"ms",u'\xb5',"ns"]
746 #units = [u"s", u"ms",u'\xb5',"ns"]
743 units = [u"s", u"ms",u'us',"ns"]
747 units = [u"s", u"ms",u'us',"ns"]
744
748
745 scaling = [1, 1e3, 1e6, 1e9]
749 scaling = [1, 1e3, 1e6, 1e9]
746
750
747 opts, stmt = self.parse_options(line,'n:r:tcp:',
751 opts, stmt = self.parse_options(line,'n:r:tcp:',
748 posix=False, strict=False)
752 posix=False, strict=False)
749 if stmt == "" and cell is None:
753 if stmt == "" and cell is None:
750 return
754 return
751 timefunc = timeit.default_timer
755 timefunc = timeit.default_timer
752 number = int(getattr(opts, "n", 0))
756 number = int(getattr(opts, "n", 0))
753 repeat = int(getattr(opts, "r", timeit.default_repeat))
757 repeat = int(getattr(opts, "r", timeit.default_repeat))
754 precision = int(getattr(opts, "p", 3))
758 precision = int(getattr(opts, "p", 3))
755 if hasattr(opts, "t"):
759 if hasattr(opts, "t"):
756 timefunc = time.time
760 timefunc = time.time
757 if hasattr(opts, "c"):
761 if hasattr(opts, "c"):
758 timefunc = clock
762 timefunc = clock
759
763
760 timer = timeit.Timer(timer=timefunc)
764 timer = timeit.Timer(timer=timefunc)
761 # this code has tight coupling to the inner workings of timeit.Timer,
765 # this code has tight coupling to the inner workings of timeit.Timer,
762 # but is there a better way to achieve that the code stmt has access
766 # but is there a better way to achieve that the code stmt has access
763 # to the shell namespace?
767 # to the shell namespace?
764 transform = self.shell.input_splitter.transform_cell
768 transform = self.shell.input_splitter.transform_cell
765 if cell is None:
769 if cell is None:
766 # called as line magic
770 # called as line magic
767 setup = 'pass'
771 setup = 'pass'
768 stmt = timeit.reindent(transform(stmt), 8)
772 stmt = timeit.reindent(transform(stmt), 8)
769 else:
773 else:
770 setup = timeit.reindent(transform(stmt), 4)
774 setup = timeit.reindent(transform(stmt), 4)
771 stmt = timeit.reindent(transform(cell), 8)
775 stmt = timeit.reindent(transform(cell), 8)
772
776
773 # From Python 3.3, this template uses new-style string formatting.
777 # From Python 3.3, this template uses new-style string formatting.
774 if sys.version_info >= (3, 3):
778 if sys.version_info >= (3, 3):
775 src = timeit.template.format(stmt=stmt, setup=setup)
779 src = timeit.template.format(stmt=stmt, setup=setup)
776 else:
780 else:
777 src = timeit.template % dict(stmt=stmt, setup=setup)
781 src = timeit.template % dict(stmt=stmt, setup=setup)
778
782
779 # Track compilation time so it can be reported if too long
783 # Track compilation time so it can be reported if too long
780 # Minimum time above which compilation time will be reported
784 # Minimum time above which compilation time will be reported
781 tc_min = 0.1
785 tc_min = 0.1
782
786
783 t0 = clock()
787 t0 = clock()
784 code = compile(src, "<magic-timeit>", "exec")
788 code = compile(src, "<magic-timeit>", "exec")
785 tc = clock()-t0
789 tc = clock()-t0
786
790
787 ns = {}
791 ns = {}
788 exec code in self.shell.user_ns, ns
792 exec code in self.shell.user_ns, ns
789 timer.inner = ns["inner"]
793 timer.inner = ns["inner"]
790
794
791 if number == 0:
795 if number == 0:
792 # determine number so that 0.2 <= total time < 2.0
796 # determine number so that 0.2 <= total time < 2.0
793 number = 1
797 number = 1
794 for i in range(1, 10):
798 for i in range(1, 10):
795 if timer.timeit(number) >= 0.2:
799 if timer.timeit(number) >= 0.2:
796 break
800 break
797 number *= 10
801 number *= 10
798
802
799 best = min(timer.repeat(repeat, number)) / number
803 best = min(timer.repeat(repeat, number)) / number
800
804
801 if best > 0.0 and best < 1000.0:
805 if best > 0.0 and best < 1000.0:
802 order = min(-int(math.floor(math.log10(best)) // 3), 3)
806 order = min(-int(math.floor(math.log10(best)) // 3), 3)
803 elif best >= 1000.0:
807 elif best >= 1000.0:
804 order = 0
808 order = 0
805 else:
809 else:
806 order = 3
810 order = 3
807 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
811 print u"%d loops, best of %d: %.*g %s per loop" % (number, repeat,
808 precision,
812 precision,
809 best * scaling[order],
813 best * scaling[order],
810 units[order])
814 units[order])
811 if tc > tc_min:
815 if tc > tc_min:
812 print "Compiler time: %.2f s" % tc
816 print "Compiler time: %.2f s" % tc
813
817
814 @skip_doctest
818 @skip_doctest
815 @needs_local_scope
819 @needs_local_scope
816 @line_magic
820 @line_magic
817 def time(self,parameter_s, local_ns=None):
821 def time(self,parameter_s, local_ns=None):
818 """Time execution of a Python statement or expression.
822 """Time execution of a Python statement or expression.
819
823
820 The CPU and wall clock times are printed, and the value of the
824 The CPU and wall clock times are printed, and the value of the
821 expression (if any) is returned. Note that under Win32, system time
825 expression (if any) is returned. Note that under Win32, system time
822 is always reported as 0, since it can not be measured.
826 is always reported as 0, since it can not be measured.
823
827
824 This function provides very basic timing functionality. In Python
828 This function provides very basic timing functionality. In Python
825 2.3, the timeit module offers more control and sophistication, so this
829 2.3, the timeit module offers more control and sophistication, so this
826 could be rewritten to use it (patches welcome).
830 could be rewritten to use it (patches welcome).
827
831
828 Examples
832 Examples
829 --------
833 --------
830 ::
834 ::
831
835
832 In [1]: time 2**128
836 In [1]: time 2**128
833 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
837 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
834 Wall time: 0.00
838 Wall time: 0.00
835 Out[1]: 340282366920938463463374607431768211456L
839 Out[1]: 340282366920938463463374607431768211456L
836
840
837 In [2]: n = 1000000
841 In [2]: n = 1000000
838
842
839 In [3]: time sum(range(n))
843 In [3]: time sum(range(n))
840 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
844 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
841 Wall time: 1.37
845 Wall time: 1.37
842 Out[3]: 499999500000L
846 Out[3]: 499999500000L
843
847
844 In [4]: time print 'hello world'
848 In [4]: time print 'hello world'
845 hello world
849 hello world
846 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
850 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
847 Wall time: 0.00
851 Wall time: 0.00
848
852
849 Note that the time needed by Python to compile the given expression
853 Note that the time needed by Python to compile the given expression
850 will be reported if it is more than 0.1s. In this example, the
854 will be reported if it is more than 0.1s. In this example, the
851 actual exponentiation is done by Python at compilation time, so while
855 actual exponentiation is done by Python at compilation time, so while
852 the expression can take a noticeable amount of time to compute, that
856 the expression can take a noticeable amount of time to compute, that
853 time is purely due to the compilation:
857 time is purely due to the compilation:
854
858
855 In [5]: time 3**9999;
859 In [5]: time 3**9999;
856 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
860 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
857 Wall time: 0.00 s
861 Wall time: 0.00 s
858
862
859 In [6]: time 3**999999;
863 In [6]: time 3**999999;
860 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
864 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
861 Wall time: 0.00 s
865 Wall time: 0.00 s
862 Compiler : 0.78 s
866 Compiler : 0.78 s
863 """
867 """
864
868
865 # fail immediately if the given expression can't be compiled
869 # fail immediately if the given expression can't be compiled
866
870
867 expr = self.shell.prefilter(parameter_s,False)
871 expr = self.shell.prefilter(parameter_s,False)
868
872
869 # Minimum time above which compilation time will be reported
873 # Minimum time above which compilation time will be reported
870 tc_min = 0.1
874 tc_min = 0.1
871
875
872 try:
876 try:
873 mode = 'eval'
877 mode = 'eval'
874 t0 = clock()
878 t0 = clock()
875 code = compile(expr,'<timed eval>',mode)
879 code = compile(expr,'<timed eval>',mode)
876 tc = clock()-t0
880 tc = clock()-t0
877 except SyntaxError:
881 except SyntaxError:
878 mode = 'exec'
882 mode = 'exec'
879 t0 = clock()
883 t0 = clock()
880 code = compile(expr,'<timed exec>',mode)
884 code = compile(expr,'<timed exec>',mode)
881 tc = clock()-t0
885 tc = clock()-t0
882 # skew measurement as little as possible
886 # skew measurement as little as possible
883 glob = self.shell.user_ns
887 glob = self.shell.user_ns
884 wtime = time.time
888 wtime = time.time
885 # time execution
889 # time execution
886 wall_st = wtime()
890 wall_st = wtime()
887 if mode=='eval':
891 if mode=='eval':
888 st = clock2()
892 st = clock2()
889 out = eval(code, glob, local_ns)
893 out = eval(code, glob, local_ns)
890 end = clock2()
894 end = clock2()
891 else:
895 else:
892 st = clock2()
896 st = clock2()
893 exec code in glob, local_ns
897 exec code in glob, local_ns
894 end = clock2()
898 end = clock2()
895 out = None
899 out = None
896 wall_end = wtime()
900 wall_end = wtime()
897 # Compute actual times and report
901 # Compute actual times and report
898 wall_time = wall_end-wall_st
902 wall_time = wall_end-wall_st
899 cpu_user = end[0]-st[0]
903 cpu_user = end[0]-st[0]
900 cpu_sys = end[1]-st[1]
904 cpu_sys = end[1]-st[1]
901 cpu_tot = cpu_user+cpu_sys
905 cpu_tot = cpu_user+cpu_sys
902 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
906 print "CPU times: user %.2f s, sys: %.2f s, total: %.2f s" % \
903 (cpu_user,cpu_sys,cpu_tot)
907 (cpu_user,cpu_sys,cpu_tot)
904 print "Wall time: %.2f s" % wall_time
908 print "Wall time: %.2f s" % wall_time
905 if tc > tc_min:
909 if tc > tc_min:
906 print "Compiler : %.2f s" % tc
910 print "Compiler : %.2f s" % tc
907 return out
911 return out
908
912
909 @skip_doctest
913 @skip_doctest
910 @line_magic
914 @line_magic
911 def macro(self, parameter_s=''):
915 def macro(self, parameter_s=''):
912 """Define a macro for future re-execution. It accepts ranges of history,
916 """Define a macro for future re-execution. It accepts ranges of history,
913 filenames or string objects.
917 filenames or string objects.
914
918
915 Usage:\\
919 Usage:\\
916 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
920 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
917
921
918 Options:
922 Options:
919
923
920 -r: use 'raw' input. By default, the 'processed' history is used,
924 -r: use 'raw' input. By default, the 'processed' history is used,
921 so that magics are loaded in their transformed version to valid
925 so that magics are loaded in their transformed version to valid
922 Python. If this option is given, the raw input as typed as the
926 Python. If this option is given, the raw input as typed as the
923 command line is used instead.
927 command line is used instead.
924
928
925 This will define a global variable called `name` which is a string
929 This will define a global variable called `name` which is a string
926 made of joining the slices and lines you specify (n1,n2,... numbers
930 made of joining the slices and lines you specify (n1,n2,... numbers
927 above) from your input history into a single string. This variable
931 above) from your input history into a single string. This variable
928 acts like an automatic function which re-executes those lines as if
932 acts like an automatic function which re-executes those lines as if
929 you had typed them. You just type 'name' at the prompt and the code
933 you had typed them. You just type 'name' at the prompt and the code
930 executes.
934 executes.
931
935
932 The syntax for indicating input ranges is described in %history.
936 The syntax for indicating input ranges is described in %history.
933
937
934 Note: as a 'hidden' feature, you can also use traditional python slice
938 Note: as a 'hidden' feature, you can also use traditional python slice
935 notation, where N:M means numbers N through M-1.
939 notation, where N:M means numbers N through M-1.
936
940
937 For example, if your history contains (%hist prints it)::
941 For example, if your history contains (%hist prints it)::
938
942
939 44: x=1
943 44: x=1
940 45: y=3
944 45: y=3
941 46: z=x+y
945 46: z=x+y
942 47: print x
946 47: print x
943 48: a=5
947 48: a=5
944 49: print 'x',x,'y',y
948 49: print 'x',x,'y',y
945
949
946 you can create a macro with lines 44 through 47 (included) and line 49
950 you can create a macro with lines 44 through 47 (included) and line 49
947 called my_macro with::
951 called my_macro with::
948
952
949 In [55]: %macro my_macro 44-47 49
953 In [55]: %macro my_macro 44-47 49
950
954
951 Now, typing `my_macro` (without quotes) will re-execute all this code
955 Now, typing `my_macro` (without quotes) will re-execute all this code
952 in one pass.
956 in one pass.
953
957
954 You don't need to give the line-numbers in order, and any given line
958 You don't need to give the line-numbers in order, and any given line
955 number can appear multiple times. You can assemble macros with any
959 number can appear multiple times. You can assemble macros with any
956 lines from your input history in any order.
960 lines from your input history in any order.
957
961
958 The macro is a simple object which holds its value in an attribute,
962 The macro is a simple object which holds its value in an attribute,
959 but IPython's display system checks for macros and executes them as
963 but IPython's display system checks for macros and executes them as
960 code instead of printing them when you type their name.
964 code instead of printing them when you type their name.
961
965
962 You can view a macro's contents by explicitly printing it with::
966 You can view a macro's contents by explicitly printing it with::
963
967
964 print macro_name
968 print macro_name
965
969
966 """
970 """
967 opts,args = self.parse_options(parameter_s,'r',mode='list')
971 opts,args = self.parse_options(parameter_s,'r',mode='list')
968 if not args: # List existing macros
972 if not args: # List existing macros
969 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
973 return sorted(k for k,v in self.shell.user_ns.iteritems() if\
970 isinstance(v, Macro))
974 isinstance(v, Macro))
971 if len(args) == 1:
975 if len(args) == 1:
972 raise UsageError(
976 raise UsageError(
973 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
977 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
974 name, codefrom = args[0], " ".join(args[1:])
978 name, codefrom = args[0], " ".join(args[1:])
975
979
976 #print 'rng',ranges # dbg
980 #print 'rng',ranges # dbg
977 try:
981 try:
978 lines = self.shell.find_user_code(codefrom, 'r' in opts)
982 lines = self.shell.find_user_code(codefrom, 'r' in opts)
979 except (ValueError, TypeError) as e:
983 except (ValueError, TypeError) as e:
980 print e.args[0]
984 print e.args[0]
981 return
985 return
982 macro = Macro(lines)
986 macro = Macro(lines)
983 self.shell.define_macro(name, macro)
987 self.shell.define_macro(name, macro)
984 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
988 print 'Macro `%s` created. To execute, type its name (without quotes).' % name
985 print '=== Macro contents: ==='
989 print '=== Macro contents: ==='
986 print macro,
990 print macro,
987
991
988 @magic_arguments.magic_arguments()
992 @magic_arguments.magic_arguments()
989 @magic_arguments.argument('output', type=str, default='', nargs='?',
993 @magic_arguments.argument('output', type=str, default='', nargs='?',
990 help="""The name of the variable in which to store output.
994 help="""The name of the variable in which to store output.
991 This is a utils.io.CapturedIO object with stdout/err attributes
995 This is a utils.io.CapturedIO object with stdout/err attributes
992 for the text of the captured output.
996 for the text of the captured output.
993
997
994 CapturedOutput also has a show() method for displaying the output,
998 CapturedOutput also has a show() method for displaying the output,
995 and __call__ as well, so you can use that to quickly display the
999 and __call__ as well, so you can use that to quickly display the
996 output.
1000 output.
997
1001
998 If unspecified, captured output is discarded.
1002 If unspecified, captured output is discarded.
999 """
1003 """
1000 )
1004 )
1001 @magic_arguments.argument('--no-stderr', action="store_true",
1005 @magic_arguments.argument('--no-stderr', action="store_true",
1002 help="""Don't capture stderr."""
1006 help="""Don't capture stderr."""
1003 )
1007 )
1004 @magic_arguments.argument('--no-stdout', action="store_true",
1008 @magic_arguments.argument('--no-stdout', action="store_true",
1005 help="""Don't capture stdout."""
1009 help="""Don't capture stdout."""
1006 )
1010 )
1007 @cell_magic
1011 @cell_magic
1008 def capture(self, line, cell):
1012 def capture(self, line, cell):
1009 """run the cell, capturing stdout/err"""
1013 """run the cell, capturing stdout/err"""
1010 args = magic_arguments.parse_argstring(self.capture, line)
1014 args = magic_arguments.parse_argstring(self.capture, line)
1011 out = not args.no_stdout
1015 out = not args.no_stdout
1012 err = not args.no_stderr
1016 err = not args.no_stderr
1013 with capture_output(out, err) as io:
1017 with capture_output(out, err) as io:
1014 self.shell.run_cell(cell)
1018 self.shell.run_cell(cell)
1015 if args.output:
1019 if args.output:
1016 self.shell.user_ns[args.output] = io
1020 self.shell.user_ns[args.output] = io
@@ -1,360 +1,359 b''
1 # encoding: utf-8
1 # encoding: utf-8
2 """
2 """
3 A mixin for :class:`~IPython.core.application.Application` classes that
3 A mixin for :class:`~IPython.core.application.Application` classes that
4 launch InteractiveShell instances, load extensions, etc.
4 launch InteractiveShell instances, load extensions, etc.
5
5
6 Authors
6 Authors
7 -------
7 -------
8
8
9 * Min Ragan-Kelley
9 * Min Ragan-Kelley
10 """
10 """
11
11
12 #-----------------------------------------------------------------------------
12 #-----------------------------------------------------------------------------
13 # Copyright (C) 2008-2011 The IPython Development Team
13 # Copyright (C) 2008-2011 The IPython Development Team
14 #
14 #
15 # Distributed under the terms of the BSD License. The full license is in
15 # Distributed under the terms of the BSD License. The full license is in
16 # the file COPYING, distributed as part of this software.
16 # the file COPYING, distributed as part of this software.
17 #-----------------------------------------------------------------------------
17 #-----------------------------------------------------------------------------
18
18
19 #-----------------------------------------------------------------------------
19 #-----------------------------------------------------------------------------
20 # Imports
20 # Imports
21 #-----------------------------------------------------------------------------
21 #-----------------------------------------------------------------------------
22
22
23 from __future__ import absolute_import
23 from __future__ import absolute_import
24
24
25 import glob
25 import glob
26 import os
26 import os
27 import sys
27 import sys
28
28
29 from IPython.config.application import boolean_flag
29 from IPython.config.application import boolean_flag
30 from IPython.config.configurable import Configurable
30 from IPython.config.configurable import Configurable
31 from IPython.config.loader import Config
31 from IPython.config.loader import Config
32 from IPython.core import pylabtools
32 from IPython.core import pylabtools
33 from IPython.utils import py3compat
33 from IPython.utils import py3compat
34 from IPython.utils.contexts import preserve_keys
34 from IPython.utils.path import filefind
35 from IPython.utils.path import filefind
35 from IPython.utils.traitlets import (
36 from IPython.utils.traitlets import (
36 Unicode, Instance, List, Bool, CaselessStrEnum
37 Unicode, Instance, List, Bool, CaselessStrEnum
37 )
38 )
38
39
39 #-----------------------------------------------------------------------------
40 #-----------------------------------------------------------------------------
40 # Aliases and Flags
41 # Aliases and Flags
41 #-----------------------------------------------------------------------------
42 #-----------------------------------------------------------------------------
42
43
43 shell_flags = {}
44 shell_flags = {}
44
45
45 addflag = lambda *args: shell_flags.update(boolean_flag(*args))
46 addflag = lambda *args: shell_flags.update(boolean_flag(*args))
46 addflag('autoindent', 'InteractiveShell.autoindent',
47 addflag('autoindent', 'InteractiveShell.autoindent',
47 'Turn on autoindenting.', 'Turn off autoindenting.'
48 'Turn on autoindenting.', 'Turn off autoindenting.'
48 )
49 )
49 addflag('automagic', 'InteractiveShell.automagic',
50 addflag('automagic', 'InteractiveShell.automagic',
50 """Turn on the auto calling of magic commands. Type %%magic at the
51 """Turn on the auto calling of magic commands. Type %%magic at the
51 IPython prompt for more information.""",
52 IPython prompt for more information.""",
52 'Turn off the auto calling of magic commands.'
53 'Turn off the auto calling of magic commands.'
53 )
54 )
54 addflag('pdb', 'InteractiveShell.pdb',
55 addflag('pdb', 'InteractiveShell.pdb',
55 "Enable auto calling the pdb debugger after every exception.",
56 "Enable auto calling the pdb debugger after every exception.",
56 "Disable auto calling the pdb debugger after every exception."
57 "Disable auto calling the pdb debugger after every exception."
57 )
58 )
58 # pydb flag doesn't do any config, as core.debugger switches on import,
59 # pydb flag doesn't do any config, as core.debugger switches on import,
59 # which is before parsing. This just allows the flag to be passed.
60 # which is before parsing. This just allows the flag to be passed.
60 shell_flags.update(dict(
61 shell_flags.update(dict(
61 pydb = ({},
62 pydb = ({},
62 """Use the third party 'pydb' package as debugger, instead of pdb.
63 """Use the third party 'pydb' package as debugger, instead of pdb.
63 Requires that pydb is installed."""
64 Requires that pydb is installed."""
64 )
65 )
65 ))
66 ))
66 addflag('pprint', 'PlainTextFormatter.pprint',
67 addflag('pprint', 'PlainTextFormatter.pprint',
67 "Enable auto pretty printing of results.",
68 "Enable auto pretty printing of results.",
68 "Disable auto auto pretty printing of results."
69 "Disable auto auto pretty printing of results."
69 )
70 )
70 addflag('color-info', 'InteractiveShell.color_info',
71 addflag('color-info', 'InteractiveShell.color_info',
71 """IPython can display information about objects via a set of func-
72 """IPython can display information about objects via a set of func-
72 tions, and optionally can use colors for this, syntax highlighting
73 tions, and optionally can use colors for this, syntax highlighting
73 source code and various other elements. However, because this
74 source code and various other elements. However, because this
74 information is passed through a pager (like 'less') and many pagers get
75 information is passed through a pager (like 'less') and many pagers get
75 confused with color codes, this option is off by default. You can test
76 confused with color codes, this option is off by default. You can test
76 it and turn it on permanently in your ipython_config.py file if it
77 it and turn it on permanently in your ipython_config.py file if it
77 works for you. Test it and turn it on permanently if it works with
78 works for you. Test it and turn it on permanently if it works with
78 your system. The magic function %%color_info allows you to toggle this
79 your system. The magic function %%color_info allows you to toggle this
79 interactively for testing.""",
80 interactively for testing.""",
80 "Disable using colors for info related things."
81 "Disable using colors for info related things."
81 )
82 )
82 addflag('deep-reload', 'InteractiveShell.deep_reload',
83 addflag('deep-reload', 'InteractiveShell.deep_reload',
83 """Enable deep (recursive) reloading by default. IPython can use the
84 """Enable deep (recursive) reloading by default. IPython can use the
84 deep_reload module which reloads changes in modules recursively (it
85 deep_reload module which reloads changes in modules recursively (it
85 replaces the reload() function, so you don't need to change anything to
86 replaces the reload() function, so you don't need to change anything to
86 use it). deep_reload() forces a full reload of modules whose code may
87 use it). deep_reload() forces a full reload of modules whose code may
87 have changed, which the default reload() function does not. When
88 have changed, which the default reload() function does not. When
88 deep_reload is off, IPython will use the normal reload(), but
89 deep_reload is off, IPython will use the normal reload(), but
89 deep_reload will still be available as dreload(). This feature is off
90 deep_reload will still be available as dreload(). This feature is off
90 by default [which means that you have both normal reload() and
91 by default [which means that you have both normal reload() and
91 dreload()].""",
92 dreload()].""",
92 "Disable deep (recursive) reloading by default."
93 "Disable deep (recursive) reloading by default."
93 )
94 )
94 nosep_config = Config()
95 nosep_config = Config()
95 nosep_config.InteractiveShell.separate_in = ''
96 nosep_config.InteractiveShell.separate_in = ''
96 nosep_config.InteractiveShell.separate_out = ''
97 nosep_config.InteractiveShell.separate_out = ''
97 nosep_config.InteractiveShell.separate_out2 = ''
98 nosep_config.InteractiveShell.separate_out2 = ''
98
99
99 shell_flags['nosep']=(nosep_config, "Eliminate all spacing between prompts.")
100 shell_flags['nosep']=(nosep_config, "Eliminate all spacing between prompts.")
100 shell_flags['pylab'] = (
101 shell_flags['pylab'] = (
101 {'InteractiveShellApp' : {'pylab' : 'auto'}},
102 {'InteractiveShellApp' : {'pylab' : 'auto'}},
102 """Pre-load matplotlib and numpy for interactive use with
103 """Pre-load matplotlib and numpy for interactive use with
103 the default matplotlib backend."""
104 the default matplotlib backend."""
104 )
105 )
105
106
106 # it's possible we don't want short aliases for *all* of these:
107 # it's possible we don't want short aliases for *all* of these:
107 shell_aliases = dict(
108 shell_aliases = dict(
108 autocall='InteractiveShell.autocall',
109 autocall='InteractiveShell.autocall',
109 colors='InteractiveShell.colors',
110 colors='InteractiveShell.colors',
110 logfile='InteractiveShell.logfile',
111 logfile='InteractiveShell.logfile',
111 logappend='InteractiveShell.logappend',
112 logappend='InteractiveShell.logappend',
112 c='InteractiveShellApp.code_to_run',
113 c='InteractiveShellApp.code_to_run',
113 m='InteractiveShellApp.module_to_run',
114 m='InteractiveShellApp.module_to_run',
114 ext='InteractiveShellApp.extra_extension',
115 ext='InteractiveShellApp.extra_extension',
115 gui='InteractiveShellApp.gui',
116 gui='InteractiveShellApp.gui',
116 pylab='InteractiveShellApp.pylab',
117 pylab='InteractiveShellApp.pylab',
117 )
118 )
118 shell_aliases['cache-size'] = 'InteractiveShell.cache_size'
119 shell_aliases['cache-size'] = 'InteractiveShell.cache_size'
119
120
120 #-----------------------------------------------------------------------------
121 #-----------------------------------------------------------------------------
121 # Main classes and functions
122 # Main classes and functions
122 #-----------------------------------------------------------------------------
123 #-----------------------------------------------------------------------------
123
124
124 class InteractiveShellApp(Configurable):
125 class InteractiveShellApp(Configurable):
125 """A Mixin for applications that start InteractiveShell instances.
126 """A Mixin for applications that start InteractiveShell instances.
126
127
127 Provides configurables for loading extensions and executing files
128 Provides configurables for loading extensions and executing files
128 as part of configuring a Shell environment.
129 as part of configuring a Shell environment.
129
130
130 The following methods should be called by the :meth:`initialize` method
131 The following methods should be called by the :meth:`initialize` method
131 of the subclass:
132 of the subclass:
132
133
133 - :meth:`init_path`
134 - :meth:`init_path`
134 - :meth:`init_shell` (to be implemented by the subclass)
135 - :meth:`init_shell` (to be implemented by the subclass)
135 - :meth:`init_gui_pylab`
136 - :meth:`init_gui_pylab`
136 - :meth:`init_extensions`
137 - :meth:`init_extensions`
137 - :meth:`init_code`
138 - :meth:`init_code`
138 """
139 """
139 extensions = List(Unicode, config=True,
140 extensions = List(Unicode, config=True,
140 help="A list of dotted module names of IPython extensions to load."
141 help="A list of dotted module names of IPython extensions to load."
141 )
142 )
142 extra_extension = Unicode('', config=True,
143 extra_extension = Unicode('', config=True,
143 help="dotted module name of an IPython extension to load."
144 help="dotted module name of an IPython extension to load."
144 )
145 )
145 def _extra_extension_changed(self, name, old, new):
146 def _extra_extension_changed(self, name, old, new):
146 if new:
147 if new:
147 # add to self.extensions
148 # add to self.extensions
148 self.extensions.append(new)
149 self.extensions.append(new)
149
150
150 # Extensions that are always loaded (not configurable)
151 # Extensions that are always loaded (not configurable)
151 default_extensions = List(Unicode, [u'storemagic'], config=False)
152 default_extensions = List(Unicode, [u'storemagic'], config=False)
152
153
153 exec_files = List(Unicode, config=True,
154 exec_files = List(Unicode, config=True,
154 help="""List of files to run at IPython startup."""
155 help="""List of files to run at IPython startup."""
155 )
156 )
156 file_to_run = Unicode('', config=True,
157 file_to_run = Unicode('', config=True,
157 help="""A file to be run""")
158 help="""A file to be run""")
158
159
159 exec_lines = List(Unicode, config=True,
160 exec_lines = List(Unicode, config=True,
160 help="""lines of code to run at IPython startup."""
161 help="""lines of code to run at IPython startup."""
161 )
162 )
162 code_to_run = Unicode('', config=True,
163 code_to_run = Unicode('', config=True,
163 help="Execute the given command string."
164 help="Execute the given command string."
164 )
165 )
165 module_to_run = Unicode('', config=True,
166 module_to_run = Unicode('', config=True,
166 help="Run the module as a script."
167 help="Run the module as a script."
167 )
168 )
168 gui = CaselessStrEnum(('qt', 'wx', 'gtk', 'glut', 'pyglet', 'osx'), config=True,
169 gui = CaselessStrEnum(('qt', 'wx', 'gtk', 'glut', 'pyglet', 'osx'), config=True,
169 help="Enable GUI event loop integration ('qt', 'wx', 'gtk', 'glut', 'pyglet', 'osx')."
170 help="Enable GUI event loop integration ('qt', 'wx', 'gtk', 'glut', 'pyglet', 'osx')."
170 )
171 )
171 pylab = CaselessStrEnum(['tk', 'qt', 'wx', 'gtk', 'osx', 'inline', 'auto'],
172 pylab = CaselessStrEnum(['tk', 'qt', 'wx', 'gtk', 'osx', 'inline', 'auto'],
172 config=True,
173 config=True,
173 help="""Pre-load matplotlib and numpy for interactive use,
174 help="""Pre-load matplotlib and numpy for interactive use,
174 selecting a particular matplotlib backend and loop integration.
175 selecting a particular matplotlib backend and loop integration.
175 """
176 """
176 )
177 )
177 pylab_import_all = Bool(True, config=True,
178 pylab_import_all = Bool(True, config=True,
178 help="""If true, an 'import *' is done from numpy and pylab,
179 help="""If true, an 'import *' is done from numpy and pylab,
179 when using pylab"""
180 when using pylab"""
180 )
181 )
181 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
182 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC')
182
183
183 def init_path(self):
184 def init_path(self):
184 """Add current working directory, '', to sys.path"""
185 """Add current working directory, '', to sys.path"""
185 if sys.path[0] != '':
186 if sys.path[0] != '':
186 sys.path.insert(0, '')
187 sys.path.insert(0, '')
187
188
188 def init_shell(self):
189 def init_shell(self):
189 raise NotImplementedError("Override in subclasses")
190 raise NotImplementedError("Override in subclasses")
190
191
191 def init_gui_pylab(self):
192 def init_gui_pylab(self):
192 """Enable GUI event loop integration, taking pylab into account."""
193 """Enable GUI event loop integration, taking pylab into account."""
193 if self.gui or self.pylab:
194 if self.gui or self.pylab:
194 shell = self.shell
195 shell = self.shell
195 try:
196 try:
196 if self.pylab:
197 if self.pylab:
197 gui, backend = pylabtools.find_gui_and_backend(self.pylab)
198 gui, backend = pylabtools.find_gui_and_backend(self.pylab)
198 self.log.info("Enabling GUI event loop integration, "
199 self.log.info("Enabling GUI event loop integration, "
199 "toolkit=%s, pylab=%s" % (gui, self.pylab))
200 "toolkit=%s, pylab=%s" % (gui, self.pylab))
200 shell.enable_pylab(gui, import_all=self.pylab_import_all, welcome_message=True)
201 shell.enable_pylab(gui, import_all=self.pylab_import_all, welcome_message=True)
201 else:
202 else:
202 self.log.info("Enabling GUI event loop integration, "
203 self.log.info("Enabling GUI event loop integration, "
203 "toolkit=%s" % self.gui)
204 "toolkit=%s" % self.gui)
204 shell.enable_gui(self.gui)
205 shell.enable_gui(self.gui)
205 except Exception:
206 except Exception:
206 self.log.warn("GUI event loop or pylab initialization failed")
207 self.log.warn("GUI event loop or pylab initialization failed")
207 self.shell.showtraceback()
208 self.shell.showtraceback()
208
209
209 def init_extensions(self):
210 def init_extensions(self):
210 """Load all IPython extensions in IPythonApp.extensions.
211 """Load all IPython extensions in IPythonApp.extensions.
211
212
212 This uses the :meth:`ExtensionManager.load_extensions` to load all
213 This uses the :meth:`ExtensionManager.load_extensions` to load all
213 the extensions listed in ``self.extensions``.
214 the extensions listed in ``self.extensions``.
214 """
215 """
215 try:
216 try:
216 self.log.debug("Loading IPython extensions...")
217 self.log.debug("Loading IPython extensions...")
217 extensions = self.default_extensions + self.extensions
218 extensions = self.default_extensions + self.extensions
218 for ext in extensions:
219 for ext in extensions:
219 try:
220 try:
220 self.log.info("Loading IPython extension: %s" % ext)
221 self.log.info("Loading IPython extension: %s" % ext)
221 self.shell.extension_manager.load_extension(ext)
222 self.shell.extension_manager.load_extension(ext)
222 except:
223 except:
223 self.log.warn("Error in loading extension: %s" % ext +
224 self.log.warn("Error in loading extension: %s" % ext +
224 "\nCheck your config files in %s" % self.profile_dir.location
225 "\nCheck your config files in %s" % self.profile_dir.location
225 )
226 )
226 self.shell.showtraceback()
227 self.shell.showtraceback()
227 except:
228 except:
228 self.log.warn("Unknown error in loading extensions:")
229 self.log.warn("Unknown error in loading extensions:")
229 self.shell.showtraceback()
230 self.shell.showtraceback()
230
231
231 def init_code(self):
232 def init_code(self):
232 """run the pre-flight code, specified via exec_lines"""
233 """run the pre-flight code, specified via exec_lines"""
233 self._run_startup_files()
234 self._run_startup_files()
234 self._run_exec_lines()
235 self._run_exec_lines()
235 self._run_exec_files()
236 self._run_exec_files()
236 self._run_cmd_line_code()
237 self._run_cmd_line_code()
237 self._run_module()
238 self._run_module()
238
239
239 # flush output, so itwon't be attached to the first cell
240 # flush output, so itwon't be attached to the first cell
240 sys.stdout.flush()
241 sys.stdout.flush()
241 sys.stderr.flush()
242 sys.stderr.flush()
242
243
243 # Hide variables defined here from %who etc.
244 # Hide variables defined here from %who etc.
244 self.shell.user_ns_hidden.update(self.shell.user_ns)
245 self.shell.user_ns_hidden.update(self.shell.user_ns)
245
246
246 def _run_exec_lines(self):
247 def _run_exec_lines(self):
247 """Run lines of code in IPythonApp.exec_lines in the user's namespace."""
248 """Run lines of code in IPythonApp.exec_lines in the user's namespace."""
248 if not self.exec_lines:
249 if not self.exec_lines:
249 return
250 return
250 try:
251 try:
251 self.log.debug("Running code from IPythonApp.exec_lines...")
252 self.log.debug("Running code from IPythonApp.exec_lines...")
252 for line in self.exec_lines:
253 for line in self.exec_lines:
253 try:
254 try:
254 self.log.info("Running code in user namespace: %s" %
255 self.log.info("Running code in user namespace: %s" %
255 line)
256 line)
256 self.shell.run_cell(line, store_history=False)
257 self.shell.run_cell(line, store_history=False)
257 except:
258 except:
258 self.log.warn("Error in executing line in user "
259 self.log.warn("Error in executing line in user "
259 "namespace: %s" % line)
260 "namespace: %s" % line)
260 self.shell.showtraceback()
261 self.shell.showtraceback()
261 except:
262 except:
262 self.log.warn("Unknown error in handling IPythonApp.exec_lines:")
263 self.log.warn("Unknown error in handling IPythonApp.exec_lines:")
263 self.shell.showtraceback()
264 self.shell.showtraceback()
264
265
265 def _exec_file(self, fname):
266 def _exec_file(self, fname):
266 try:
267 try:
267 full_filename = filefind(fname, [u'.', self.ipython_dir])
268 full_filename = filefind(fname, [u'.', self.ipython_dir])
268 except IOError as e:
269 except IOError as e:
269 self.log.warn("File not found: %r"%fname)
270 self.log.warn("File not found: %r"%fname)
270 return
271 return
271 # Make sure that the running script gets a proper sys.argv as if it
272 # Make sure that the running script gets a proper sys.argv as if it
272 # were run from a system shell.
273 # were run from a system shell.
273 save_argv = sys.argv
274 save_argv = sys.argv
274 sys.argv = [full_filename] + self.extra_args[1:]
275 sys.argv = [full_filename] + self.extra_args[1:]
275 # protect sys.argv from potential unicode strings on Python 2:
276 # protect sys.argv from potential unicode strings on Python 2:
276 if not py3compat.PY3:
277 if not py3compat.PY3:
277 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
278 sys.argv = [ py3compat.cast_bytes(a) for a in sys.argv ]
278 try:
279 try:
279 if os.path.isfile(full_filename):
280 if os.path.isfile(full_filename):
280 if full_filename.endswith('.ipy'):
281 self.log.info("Running file in user namespace: %s" %
281 self.log.info("Running file in user namespace: %s" %
282 full_filename)
282 full_filename)
283 # Ensure that __file__ is always defined to match Python
284 # behavior.
285 with preserve_keys(self.shell.user_ns, '__file__'):
286 self.shell.user_ns['__file__'] = fname
287 if full_filename.endswith('.ipy'):
283 self.shell.safe_execfile_ipy(full_filename)
288 self.shell.safe_execfile_ipy(full_filename)
284 else:
289 else:
285 # default to python, even without extension
290 # default to python, even without extension
286 self.log.info("Running file in user namespace: %s" %
291 self.shell.safe_execfile(full_filename,
287 full_filename)
292 self.shell.user_ns)
288 # Ensure that __file__ is always defined to match Python behavior
289 self.shell.user_ns['__file__'] = fname
290 try:
291 self.shell.safe_execfile(full_filename, self.shell.user_ns)
292 finally:
293 del self.shell.user_ns['__file__']
294 finally:
293 finally:
295 sys.argv = save_argv
294 sys.argv = save_argv
296
295
297 def _run_startup_files(self):
296 def _run_startup_files(self):
298 """Run files from profile startup directory"""
297 """Run files from profile startup directory"""
299 startup_dir = self.profile_dir.startup_dir
298 startup_dir = self.profile_dir.startup_dir
300 startup_files = glob.glob(os.path.join(startup_dir, '*.py'))
299 startup_files = glob.glob(os.path.join(startup_dir, '*.py'))
301 startup_files += glob.glob(os.path.join(startup_dir, '*.ipy'))
300 startup_files += glob.glob(os.path.join(startup_dir, '*.ipy'))
302 if not startup_files:
301 if not startup_files:
303 return
302 return
304
303
305 self.log.debug("Running startup files from %s...", startup_dir)
304 self.log.debug("Running startup files from %s...", startup_dir)
306 try:
305 try:
307 for fname in sorted(startup_files):
306 for fname in sorted(startup_files):
308 self._exec_file(fname)
307 self._exec_file(fname)
309 except:
308 except:
310 self.log.warn("Unknown error in handling startup files:")
309 self.log.warn("Unknown error in handling startup files:")
311 self.shell.showtraceback()
310 self.shell.showtraceback()
312
311
313 def _run_exec_files(self):
312 def _run_exec_files(self):
314 """Run files from IPythonApp.exec_files"""
313 """Run files from IPythonApp.exec_files"""
315 if not self.exec_files:
314 if not self.exec_files:
316 return
315 return
317
316
318 self.log.debug("Running files in IPythonApp.exec_files...")
317 self.log.debug("Running files in IPythonApp.exec_files...")
319 try:
318 try:
320 for fname in self.exec_files:
319 for fname in self.exec_files:
321 self._exec_file(fname)
320 self._exec_file(fname)
322 except:
321 except:
323 self.log.warn("Unknown error in handling IPythonApp.exec_files:")
322 self.log.warn("Unknown error in handling IPythonApp.exec_files:")
324 self.shell.showtraceback()
323 self.shell.showtraceback()
325
324
326 def _run_cmd_line_code(self):
325 def _run_cmd_line_code(self):
327 """Run code or file specified at the command-line"""
326 """Run code or file specified at the command-line"""
328 if self.code_to_run:
327 if self.code_to_run:
329 line = self.code_to_run
328 line = self.code_to_run
330 try:
329 try:
331 self.log.info("Running code given at command line (c=): %s" %
330 self.log.info("Running code given at command line (c=): %s" %
332 line)
331 line)
333 self.shell.run_cell(line, store_history=False)
332 self.shell.run_cell(line, store_history=False)
334 except:
333 except:
335 self.log.warn("Error in executing line in user namespace: %s" %
334 self.log.warn("Error in executing line in user namespace: %s" %
336 line)
335 line)
337 self.shell.showtraceback()
336 self.shell.showtraceback()
338
337
339 # Like Python itself, ignore the second if the first of these is present
338 # Like Python itself, ignore the second if the first of these is present
340 elif self.file_to_run:
339 elif self.file_to_run:
341 fname = self.file_to_run
340 fname = self.file_to_run
342 try:
341 try:
343 self._exec_file(fname)
342 self._exec_file(fname)
344 except:
343 except:
345 self.log.warn("Error in executing file in user namespace: %s" %
344 self.log.warn("Error in executing file in user namespace: %s" %
346 fname)
345 fname)
347 self.shell.showtraceback()
346 self.shell.showtraceback()
348
347
349 def _run_module(self):
348 def _run_module(self):
350 """Run module specified at the command-line."""
349 """Run module specified at the command-line."""
351 if self.module_to_run:
350 if self.module_to_run:
352 # Make sure that the module gets a proper sys.argv as if it were
351 # Make sure that the module gets a proper sys.argv as if it were
353 # run using `python -m`.
352 # run using `python -m`.
354 save_argv = sys.argv
353 save_argv = sys.argv
355 sys.argv = [sys.executable] + self.extra_args
354 sys.argv = [sys.executable] + self.extra_args
356 try:
355 try:
357 self.shell.safe_run_module(self.module_to_run,
356 self.shell.safe_run_module(self.module_to_run,
358 self.shell.user_ns)
357 self.shell.user_ns)
359 finally:
358 finally:
360 sys.argv = save_argv
359 sys.argv = save_argv
General Comments 0
You need to be logged in to leave comments. Login now