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