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