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