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