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