##// END OF EJS Templates
Fix misc. comment typos...
luz.paz -
Show More
@@ -1,1427 +1,1427 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.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 On Windows systems, the use of single quotes `'` when specifing
510 On Windows systems, the use of single quotes `'` when specifying
511 511 a file is not supported. Use double quotes `"`.
512 512
513 513 Options:
514 514
515 515 -n
516 516 __name__ is NOT set to '__main__', but to the running file's name
517 517 without extension (as python does under import). This allows running
518 518 scripts and reloading the definitions in them without calling code
519 519 protected by an ``if __name__ == "__main__"`` clause.
520 520
521 521 -i
522 522 run the file in IPython's namespace instead of an empty one. This
523 523 is useful if you are experimenting with code written in a text editor
524 524 which depends on variables defined interactively.
525 525
526 526 -e
527 527 ignore sys.exit() calls or SystemExit exceptions in the script
528 528 being run. This is particularly useful if IPython is being used to
529 529 run unittests, which always exit with a sys.exit() call. In such
530 530 cases you are interested in the output of the test results, not in
531 531 seeing a traceback of the unittest module.
532 532
533 533 -t
534 534 print timing information at the end of the run. IPython will give
535 535 you an estimated CPU time consumption for your script, which under
536 536 Unix uses the resource module to avoid the wraparound problems of
537 537 time.clock(). Under Unix, an estimate of time spent on system tasks
538 538 is also given (for Windows platforms this is reported as 0.0).
539 539
540 540 If -t is given, an additional ``-N<N>`` option can be given, where <N>
541 541 must be an integer indicating how many times you want the script to
542 542 run. The final timing report will include total and per run results.
543 543
544 544 For example (testing the script uniq_stable.py)::
545 545
546 546 In [1]: run -t uniq_stable
547 547
548 548 IPython CPU timings (estimated):
549 549 User : 0.19597 s.
550 550 System: 0.0 s.
551 551
552 552 In [2]: run -t -N5 uniq_stable
553 553
554 554 IPython CPU timings (estimated):
555 555 Total runs performed: 5
556 556 Times : Total Per run
557 557 User : 0.910862 s, 0.1821724 s.
558 558 System: 0.0 s, 0.0 s.
559 559
560 560 -d
561 561 run your program under the control of pdb, the Python debugger.
562 562 This allows you to execute your program step by step, watch variables,
563 563 etc. Internally, what IPython does is similar to calling::
564 564
565 565 pdb.run('execfile("YOURFILENAME")')
566 566
567 567 with a breakpoint set on line 1 of your file. You can change the line
568 568 number for this automatic breakpoint to be <N> by using the -bN option
569 569 (where N must be an integer). For example::
570 570
571 571 %run -d -b40 myscript
572 572
573 573 will set the first breakpoint at line 40 in myscript.py. Note that
574 574 the first breakpoint must be set on a line which actually does
575 575 something (not a comment or docstring) for it to stop execution.
576 576
577 577 Or you can specify a breakpoint in a different file::
578 578
579 579 %run -d -b myotherfile.py:20 myscript
580 580
581 581 When the pdb debugger starts, you will see a (Pdb) prompt. You must
582 582 first enter 'c' (without quotes) to start execution up to the first
583 583 breakpoint.
584 584
585 585 Entering 'help' gives information about the use of the debugger. You
586 586 can easily see pdb's full documentation with "import pdb;pdb.help()"
587 587 at a prompt.
588 588
589 589 -p
590 590 run program under the control of the Python profiler module (which
591 591 prints a detailed report of execution times, function calls, etc).
592 592
593 593 You can pass other options after -p which affect the behavior of the
594 594 profiler itself. See the docs for %prun for details.
595 595
596 596 In this mode, the program's variables do NOT propagate back to the
597 597 IPython interactive namespace (because they remain in the namespace
598 598 where the profiler executes them).
599 599
600 600 Internally this triggers a call to %prun, see its documentation for
601 601 details on the options available specifically for profiling.
602 602
603 603 There is one special usage for which the text above doesn't apply:
604 604 if the filename ends with .ipy[nb], the file is run as ipython script,
605 605 just as if the commands were written on IPython prompt.
606 606
607 607 -m
608 608 specify module name to load instead of script path. Similar to
609 609 the -m option for the python interpreter. Use this option last if you
610 610 want to combine with other %run options. Unlike the python interpreter
611 611 only source modules are allowed no .pyc or .pyo files.
612 612 For example::
613 613
614 614 %run -m example
615 615
616 616 will run the example module.
617 617
618 618 -G
619 619 disable shell-like glob expansion of arguments.
620 620
621 621 """
622 622
623 623 # Logic to handle issue #3664
624 624 # Add '--' after '-m <module_name>' to ignore additional args passed to a module.
625 625 if '-m' in parameter_s and '--' not in parameter_s:
626 626 argv = shlex.split(parameter_s, posix=(os.name == 'posix'))
627 627 for idx, arg in enumerate(argv):
628 628 if arg and arg.startswith('-') and arg != '-':
629 629 if arg == '-m':
630 630 argv.insert(idx + 2, '--')
631 631 break
632 632 else:
633 633 # Positional arg, break
634 634 break
635 635 parameter_s = ' '.join(shlex.quote(arg) for arg in argv)
636 636
637 637 # get arguments and set sys.argv for program to be run.
638 638 opts, arg_lst = self.parse_options(parameter_s,
639 639 'nidtN:b:pD:l:rs:T:em:G',
640 640 mode='list', list_all=1)
641 641 if "m" in opts:
642 642 modulename = opts["m"][0]
643 643 modpath = find_mod(modulename)
644 644 if modpath is None:
645 645 warn('%r is not a valid modulename on sys.path'%modulename)
646 646 return
647 647 arg_lst = [modpath] + arg_lst
648 648 try:
649 649 filename = file_finder(arg_lst[0])
650 650 except IndexError:
651 651 warn('you must provide at least a filename.')
652 652 print('\n%run:\n', oinspect.getdoc(self.run))
653 653 return
654 654 except IOError as e:
655 655 try:
656 656 msg = str(e)
657 657 except UnicodeError:
658 658 msg = e.message
659 659 error(msg)
660 660 return
661 661
662 662 if filename.lower().endswith(('.ipy', '.ipynb')):
663 663 with preserve_keys(self.shell.user_ns, '__file__'):
664 664 self.shell.user_ns['__file__'] = filename
665 665 self.shell.safe_execfile_ipy(filename)
666 666 return
667 667
668 668 # Control the response to exit() calls made by the script being run
669 669 exit_ignore = 'e' in opts
670 670
671 671 # Make sure that the running script gets a proper sys.argv as if it
672 672 # were run from a system shell.
673 673 save_argv = sys.argv # save it for later restoring
674 674
675 675 if 'G' in opts:
676 676 args = arg_lst[1:]
677 677 else:
678 678 # tilde and glob expansion
679 679 args = shellglob(map(os.path.expanduser, arg_lst[1:]))
680 680
681 681 sys.argv = [filename] + args # put in the proper filename
682 682
683 683 if 'n' in opts:
684 684 name = os.path.splitext(os.path.basename(filename))[0]
685 685 else:
686 686 name = '__main__'
687 687
688 688 if 'i' in opts:
689 689 # Run in user's interactive namespace
690 690 prog_ns = self.shell.user_ns
691 691 __name__save = self.shell.user_ns['__name__']
692 692 prog_ns['__name__'] = name
693 693 main_mod = self.shell.user_module
694 694
695 695 # Since '%run foo' emulates 'python foo.py' at the cmd line, we must
696 696 # set the __file__ global in the script's namespace
697 697 # TK: Is this necessary in interactive mode?
698 698 prog_ns['__file__'] = filename
699 699 else:
700 700 # Run in a fresh, empty namespace
701 701
702 702 # The shell MUST hold a reference to prog_ns so after %run
703 703 # exits, the python deletion mechanism doesn't zero it out
704 704 # (leaving dangling references). See interactiveshell for details
705 705 main_mod = self.shell.new_main_mod(filename, name)
706 706 prog_ns = main_mod.__dict__
707 707
708 708 # pickle fix. See interactiveshell for an explanation. But we need to
709 709 # make sure that, if we overwrite __main__, we replace it at the end
710 710 main_mod_name = prog_ns['__name__']
711 711
712 712 if main_mod_name == '__main__':
713 713 restore_main = sys.modules['__main__']
714 714 else:
715 715 restore_main = False
716 716
717 717 # This needs to be undone at the end to prevent holding references to
718 718 # every single object ever created.
719 719 sys.modules[main_mod_name] = main_mod
720 720
721 721 if 'p' in opts or 'd' in opts:
722 722 if 'm' in opts:
723 723 code = 'run_module(modulename, prog_ns)'
724 724 code_ns = {
725 725 'run_module': self.shell.safe_run_module,
726 726 'prog_ns': prog_ns,
727 727 'modulename': modulename,
728 728 }
729 729 else:
730 730 if 'd' in opts:
731 731 # allow exceptions to raise in debug mode
732 732 code = 'execfile(filename, prog_ns, raise_exceptions=True)'
733 733 else:
734 734 code = 'execfile(filename, prog_ns)'
735 735 code_ns = {
736 736 'execfile': self.shell.safe_execfile,
737 737 'prog_ns': prog_ns,
738 738 'filename': get_py_filename(filename),
739 739 }
740 740
741 741 try:
742 742 stats = None
743 743 if 'p' in opts:
744 744 stats = self._run_with_profiler(code, opts, code_ns)
745 745 else:
746 746 if 'd' in opts:
747 747 bp_file, bp_line = parse_breakpoint(
748 748 opts.get('b', ['1'])[0], filename)
749 749 self._run_with_debugger(
750 750 code, code_ns, filename, bp_line, bp_file)
751 751 else:
752 752 if 'm' in opts:
753 753 def run():
754 754 self.shell.safe_run_module(modulename, prog_ns)
755 755 else:
756 756 if runner is None:
757 757 runner = self.default_runner
758 758 if runner is None:
759 759 runner = self.shell.safe_execfile
760 760
761 761 def run():
762 762 runner(filename, prog_ns, prog_ns,
763 763 exit_ignore=exit_ignore)
764 764
765 765 if 't' in opts:
766 766 # timed execution
767 767 try:
768 768 nruns = int(opts['N'][0])
769 769 if nruns < 1:
770 770 error('Number of runs must be >=1')
771 771 return
772 772 except (KeyError):
773 773 nruns = 1
774 774 self._run_with_timing(run, nruns)
775 775 else:
776 776 # regular execution
777 777 run()
778 778
779 779 if 'i' in opts:
780 780 self.shell.user_ns['__name__'] = __name__save
781 781 else:
782 782 # update IPython interactive namespace
783 783
784 784 # Some forms of read errors on the file may mean the
785 785 # __name__ key was never set; using pop we don't have to
786 786 # worry about a possible KeyError.
787 787 prog_ns.pop('__name__', None)
788 788
789 789 with preserve_keys(self.shell.user_ns, '__file__'):
790 790 self.shell.user_ns.update(prog_ns)
791 791 finally:
792 792 # It's a bit of a mystery why, but __builtins__ can change from
793 793 # being a module to becoming a dict missing some key data after
794 794 # %run. As best I can see, this is NOT something IPython is doing
795 795 # at all, and similar problems have been reported before:
796 796 # http://coding.derkeiler.com/Archive/Python/comp.lang.python/2004-10/0188.html
797 797 # Since this seems to be done by the interpreter itself, the best
798 798 # we can do is to at least restore __builtins__ for the user on
799 799 # exit.
800 800 self.shell.user_ns['__builtins__'] = builtin_mod
801 801
802 802 # Ensure key global structures are restored
803 803 sys.argv = save_argv
804 804 if restore_main:
805 805 sys.modules['__main__'] = restore_main
806 806 else:
807 807 # Remove from sys.modules the reference to main_mod we'd
808 808 # added. Otherwise it will trap references to objects
809 809 # contained therein.
810 810 del sys.modules[main_mod_name]
811 811
812 812 return stats
813 813
814 814 def _run_with_debugger(self, code, code_ns, filename=None,
815 815 bp_line=None, bp_file=None):
816 816 """
817 817 Run `code` in debugger with a break point.
818 818
819 819 Parameters
820 820 ----------
821 821 code : str
822 822 Code to execute.
823 823 code_ns : dict
824 824 A namespace in which `code` is executed.
825 825 filename : str
826 826 `code` is ran as if it is in `filename`.
827 827 bp_line : int, optional
828 828 Line number of the break point.
829 829 bp_file : str, optional
830 830 Path to the file in which break point is specified.
831 831 `filename` is used if not given.
832 832
833 833 Raises
834 834 ------
835 835 UsageError
836 836 If the break point given by `bp_line` is not valid.
837 837
838 838 """
839 839 deb = self.shell.InteractiveTB.pdb
840 840 if not deb:
841 841 self.shell.InteractiveTB.pdb = self.shell.InteractiveTB.debugger_cls()
842 842 deb = self.shell.InteractiveTB.pdb
843 843
844 844 # deb.checkline() fails if deb.curframe exists but is None; it can
845 845 # handle it not existing. https://github.com/ipython/ipython/issues/10028
846 846 if hasattr(deb, 'curframe'):
847 847 del deb.curframe
848 848
849 849 # reset Breakpoint state, which is moronically kept
850 850 # in a class
851 851 bdb.Breakpoint.next = 1
852 852 bdb.Breakpoint.bplist = {}
853 853 bdb.Breakpoint.bpbynumber = [None]
854 854 deb.clear_all_breaks()
855 855 if bp_line is not None:
856 856 # Set an initial breakpoint to stop execution
857 857 maxtries = 10
858 858 bp_file = bp_file or filename
859 859 checkline = deb.checkline(bp_file, bp_line)
860 860 if not checkline:
861 861 for bp in range(bp_line + 1, bp_line + maxtries + 1):
862 862 if deb.checkline(bp_file, bp):
863 863 break
864 864 else:
865 865 msg = ("\nI failed to find a valid line to set "
866 866 "a breakpoint\n"
867 867 "after trying up to line: %s.\n"
868 868 "Please set a valid breakpoint manually "
869 869 "with the -b option." % bp)
870 870 raise UsageError(msg)
871 871 # if we find a good linenumber, set the breakpoint
872 872 deb.do_break('%s:%s' % (bp_file, bp_line))
873 873
874 874 if filename:
875 875 # Mimic Pdb._runscript(...)
876 876 deb._wait_for_mainpyfile = True
877 877 deb.mainpyfile = deb.canonic(filename)
878 878
879 879 # Start file run
880 880 print("NOTE: Enter 'c' at the %s prompt to continue execution." % deb.prompt)
881 881 try:
882 882 if filename:
883 883 # save filename so it can be used by methods on the deb object
884 884 deb._exec_filename = filename
885 885 while True:
886 886 try:
887 887 deb.run(code, code_ns)
888 888 except Restart:
889 889 print("Restarting")
890 890 if filename:
891 891 deb._wait_for_mainpyfile = True
892 892 deb.mainpyfile = deb.canonic(filename)
893 893 continue
894 894 else:
895 895 break
896 896
897 897
898 898 except:
899 899 etype, value, tb = sys.exc_info()
900 900 # Skip three frames in the traceback: the %run one,
901 901 # one inside bdb.py, and the command-line typed by the
902 902 # user (run by exec in pdb itself).
903 903 self.shell.InteractiveTB(etype, value, tb, tb_offset=3)
904 904
905 905 @staticmethod
906 906 def _run_with_timing(run, nruns):
907 907 """
908 908 Run function `run` and print timing information.
909 909
910 910 Parameters
911 911 ----------
912 912 run : callable
913 913 Any callable object which takes no argument.
914 914 nruns : int
915 915 Number of times to execute `run`.
916 916
917 917 """
918 918 twall0 = time.perf_counter()
919 919 if nruns == 1:
920 920 t0 = clock2()
921 921 run()
922 922 t1 = clock2()
923 923 t_usr = t1[0] - t0[0]
924 924 t_sys = t1[1] - t0[1]
925 925 print("\nIPython CPU timings (estimated):")
926 926 print(" User : %10.2f s." % t_usr)
927 927 print(" System : %10.2f s." % t_sys)
928 928 else:
929 929 runs = range(nruns)
930 930 t0 = clock2()
931 931 for nr in runs:
932 932 run()
933 933 t1 = clock2()
934 934 t_usr = t1[0] - t0[0]
935 935 t_sys = t1[1] - t0[1]
936 936 print("\nIPython CPU timings (estimated):")
937 937 print("Total runs performed:", nruns)
938 938 print(" Times : %10s %10s" % ('Total', 'Per run'))
939 939 print(" User : %10.2f s, %10.2f s." % (t_usr, t_usr / nruns))
940 940 print(" System : %10.2f s, %10.2f s." % (t_sys, t_sys / nruns))
941 941 twall1 = time.perf_counter()
942 942 print("Wall time: %10.2f s." % (twall1 - twall0))
943 943
944 944 @skip_doctest
945 945 @line_cell_magic
946 946 @needs_local_scope
947 947 def timeit(self, line='', cell=None, local_ns=None):
948 948 """Time execution of a Python statement or expression
949 949
950 950 Usage, in line mode:
951 951 %timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] statement
952 952 or in cell mode:
953 953 %%timeit [-n<N> -r<R> [-t|-c] -q -p<P> -o] setup_code
954 954 code
955 955 code...
956 956
957 957 Time execution of a Python statement or expression using the timeit
958 958 module. This function can be used both as a line and cell magic:
959 959
960 960 - In line mode you can time a single-line statement (though multiple
961 961 ones can be chained with using semicolons).
962 962
963 963 - In cell mode, the statement in the first line is used as setup code
964 964 (executed but not timed) and the body of the cell is timed. The cell
965 965 body has access to any variables created in the setup code.
966 966
967 967 Options:
968 968 -n<N>: execute the given statement <N> times in a loop. If <N> is not
969 969 provided, <N> is determined so as to get sufficient accuracy.
970 970
971 971 -r<R>: number of repeats <R>, each consisting of <N> loops, and take the
972 972 best result.
973 973 Default: 7
974 974
975 975 -t: use time.time to measure the time, which is the default on Unix.
976 976 This function measures wall time.
977 977
978 978 -c: use time.clock to measure the time, which is the default on
979 979 Windows and measures wall time. On Unix, resource.getrusage is used
980 980 instead and returns the CPU user time.
981 981
982 982 -p<P>: use a precision of <P> digits to display the timing result.
983 983 Default: 3
984 984
985 985 -q: Quiet, do not print result.
986 986
987 987 -o: return a TimeitResult that can be stored in a variable to inspect
988 988 the result in more details.
989 989
990 990
991 991 Examples
992 992 --------
993 993 ::
994 994
995 995 In [1]: %timeit pass
996 996 8.26 ns Β± 0.12 ns per loop (mean Β± std. dev. of 7 runs, 100000000 loops each)
997 997
998 998 In [2]: u = None
999 999
1000 1000 In [3]: %timeit u is None
1001 1001 29.9 ns Β± 0.643 ns per loop (mean Β± std. dev. of 7 runs, 10000000 loops each)
1002 1002
1003 1003 In [4]: %timeit -r 4 u == None
1004 1004
1005 1005 In [5]: import time
1006 1006
1007 1007 In [6]: %timeit -n1 time.sleep(2)
1008 1008
1009 1009
1010 1010 The times reported by %timeit will be slightly higher than those
1011 1011 reported by the timeit.py script when variables are accessed. This is
1012 1012 due to the fact that %timeit executes the statement in the namespace
1013 1013 of the shell, compared with timeit.py, which uses a single setup
1014 1014 statement to import function or create variables. Generally, the bias
1015 1015 does not matter as long as results from timeit.py are not mixed with
1016 1016 those from %timeit."""
1017 1017
1018 1018 opts, stmt = self.parse_options(line,'n:r:tcp:qo',
1019 1019 posix=False, strict=False)
1020 1020 if stmt == "" and cell is None:
1021 1021 return
1022 1022
1023 1023 timefunc = timeit.default_timer
1024 1024 number = int(getattr(opts, "n", 0))
1025 1025 default_repeat = 7 if timeit.default_repeat < 7 else timeit.default_repeat
1026 1026 repeat = int(getattr(opts, "r", default_repeat))
1027 1027 precision = int(getattr(opts, "p", 3))
1028 1028 quiet = 'q' in opts
1029 1029 return_result = 'o' in opts
1030 1030 if hasattr(opts, "t"):
1031 1031 timefunc = time.time
1032 1032 if hasattr(opts, "c"):
1033 1033 timefunc = clock
1034 1034
1035 1035 timer = Timer(timer=timefunc)
1036 1036 # this code has tight coupling to the inner workings of timeit.Timer,
1037 1037 # but is there a better way to achieve that the code stmt has access
1038 1038 # to the shell namespace?
1039 1039 transform = self.shell.transform_cell
1040 1040
1041 1041 if cell is None:
1042 1042 # called as line magic
1043 1043 ast_setup = self.shell.compile.ast_parse("pass")
1044 1044 ast_stmt = self.shell.compile.ast_parse(transform(stmt))
1045 1045 else:
1046 1046 ast_setup = self.shell.compile.ast_parse(transform(stmt))
1047 1047 ast_stmt = self.shell.compile.ast_parse(transform(cell))
1048 1048
1049 1049 ast_setup = self.shell.transform_ast(ast_setup)
1050 1050 ast_stmt = self.shell.transform_ast(ast_stmt)
1051 1051
1052 1052 # Check that these compile to valid Python code *outside* the timer func
1053 1053 # Invalid code may become valid when put inside the function & loop,
1054 1054 # which messes up error messages.
1055 1055 # https://github.com/ipython/ipython/issues/10636
1056 1056 self.shell.compile(ast_setup, "<magic-timeit-setup>", "exec")
1057 1057 self.shell.compile(ast_stmt, "<magic-timeit-stmt>", "exec")
1058 1058
1059 1059 # This codestring is taken from timeit.template - we fill it in as an
1060 1060 # AST, so that we can apply our AST transformations to the user code
1061 1061 # without affecting the timing code.
1062 1062 timeit_ast_template = ast.parse('def inner(_it, _timer):\n'
1063 1063 ' setup\n'
1064 1064 ' _t0 = _timer()\n'
1065 1065 ' for _i in _it:\n'
1066 1066 ' stmt\n'
1067 1067 ' _t1 = _timer()\n'
1068 1068 ' return _t1 - _t0\n')
1069 1069
1070 1070 timeit_ast = TimeitTemplateFiller(ast_setup, ast_stmt).visit(timeit_ast_template)
1071 1071 timeit_ast = ast.fix_missing_locations(timeit_ast)
1072 1072
1073 1073 # Track compilation time so it can be reported if too long
1074 1074 # Minimum time above which compilation time will be reported
1075 1075 tc_min = 0.1
1076 1076
1077 1077 t0 = clock()
1078 1078 code = self.shell.compile(timeit_ast, "<magic-timeit>", "exec")
1079 1079 tc = clock()-t0
1080 1080
1081 1081 ns = {}
1082 1082 glob = self.shell.user_ns
1083 1083 # handles global vars with same name as local vars. We store them in conflict_globs.
1084 1084 if local_ns is not None:
1085 1085 conflict_globs = {}
1086 1086 for var_name, var_val in glob.items():
1087 1087 if var_name in local_ns:
1088 1088 conflict_globs[var_name] = var_val
1089 1089 glob.update(local_ns)
1090 1090
1091 1091 exec(code, glob, ns)
1092 1092 timer.inner = ns["inner"]
1093 1093
1094 1094 # This is used to check if there is a huge difference between the
1095 1095 # best and worst timings.
1096 1096 # Issue: https://github.com/ipython/ipython/issues/6471
1097 1097 if number == 0:
1098 1098 # determine number so that 0.2 <= total time < 2.0
1099 1099 for index in range(0, 10):
1100 1100 number = 10 ** index
1101 1101 time_number = timer.timeit(number)
1102 1102 if time_number >= 0.2:
1103 1103 break
1104 1104
1105 1105 all_runs = timer.repeat(repeat, number)
1106 1106 best = min(all_runs) / number
1107 1107 worst = max(all_runs) / number
1108 1108 timeit_result = TimeitResult(number, repeat, best, worst, all_runs, tc, precision)
1109 1109
1110 1110 # Restore global vars from conflict_globs
1111 1111 if local_ns is not None:
1112 1112 if len(conflict_globs) > 0:
1113 1113 glob.update(conflict_globs)
1114 1114
1115 1115 if not quiet :
1116 1116 # Check best timing is greater than zero to avoid a
1117 1117 # ZeroDivisionError.
1118 1118 # In cases where the slowest timing is lesser than a micosecond
1119 1119 # we assume that it does not really matter if the fastest
1120 1120 # timing is 4 times faster than the slowest timing or not.
1121 1121 if worst > 4 * best and best > 0 and worst > 1e-6:
1122 1122 print("The slowest run took %0.2f times longer than the "
1123 1123 "fastest. This could mean that an intermediate result "
1124 1124 "is being cached." % (worst / best))
1125 1125
1126 1126 print( timeit_result )
1127 1127
1128 1128 if tc > tc_min:
1129 1129 print("Compiler time: %.2f s" % tc)
1130 1130 if return_result:
1131 1131 return timeit_result
1132 1132
1133 1133 @skip_doctest
1134 1134 @needs_local_scope
1135 1135 @line_cell_magic
1136 1136 def time(self,line='', cell=None, local_ns=None):
1137 1137 """Time execution of a Python statement or expression.
1138 1138
1139 1139 The CPU and wall clock times are printed, and the value of the
1140 1140 expression (if any) is returned. Note that under Win32, system time
1141 1141 is always reported as 0, since it can not be measured.
1142 1142
1143 1143 This function can be used both as a line and cell magic:
1144 1144
1145 1145 - In line mode you can time a single-line statement (though multiple
1146 1146 ones can be chained with using semicolons).
1147 1147
1148 1148 - In cell mode, you can time the cell body (a directly
1149 1149 following statement raises an error).
1150 1150
1151 1151 This function provides very basic timing functionality. Use the timeit
1152 1152 magic for more control over the measurement.
1153 1153
1154 1154 Examples
1155 1155 --------
1156 1156 ::
1157 1157
1158 1158 In [1]: %time 2**128
1159 1159 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1160 1160 Wall time: 0.00
1161 1161 Out[1]: 340282366920938463463374607431768211456L
1162 1162
1163 1163 In [2]: n = 1000000
1164 1164
1165 1165 In [3]: %time sum(range(n))
1166 1166 CPU times: user 1.20 s, sys: 0.05 s, total: 1.25 s
1167 1167 Wall time: 1.37
1168 1168 Out[3]: 499999500000L
1169 1169
1170 1170 In [4]: %time print 'hello world'
1171 1171 hello world
1172 1172 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1173 1173 Wall time: 0.00
1174 1174
1175 1175 Note that the time needed by Python to compile the given expression
1176 1176 will be reported if it is more than 0.1s. In this example, the
1177 1177 actual exponentiation is done by Python at compilation time, so while
1178 1178 the expression can take a noticeable amount of time to compute, that
1179 1179 time is purely due to the compilation:
1180 1180
1181 1181 In [5]: %time 3**9999;
1182 1182 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1183 1183 Wall time: 0.00 s
1184 1184
1185 1185 In [6]: %time 3**999999;
1186 1186 CPU times: user 0.00 s, sys: 0.00 s, total: 0.00 s
1187 1187 Wall time: 0.00 s
1188 1188 Compiler : 0.78 s
1189 1189 """
1190 1190
1191 1191 # fail immediately if the given expression can't be compiled
1192 1192
1193 1193 if line and cell:
1194 1194 raise UsageError("Can't use statement directly after '%%time'!")
1195 1195
1196 1196 if cell:
1197 1197 expr = self.shell.transform_cell(cell)
1198 1198 else:
1199 1199 expr = self.shell.transform_cell(line)
1200 1200
1201 1201 # Minimum time above which parse time will be reported
1202 1202 tp_min = 0.1
1203 1203
1204 1204 t0 = clock()
1205 1205 expr_ast = self.shell.compile.ast_parse(expr)
1206 1206 tp = clock()-t0
1207 1207
1208 1208 # Apply AST transformations
1209 1209 expr_ast = self.shell.transform_ast(expr_ast)
1210 1210
1211 1211 # Minimum time above which compilation time will be reported
1212 1212 tc_min = 0.1
1213 1213
1214 1214 if len(expr_ast.body)==1 and isinstance(expr_ast.body[0], ast.Expr):
1215 1215 mode = 'eval'
1216 1216 source = '<timed eval>'
1217 1217 expr_ast = ast.Expression(expr_ast.body[0].value)
1218 1218 else:
1219 1219 mode = 'exec'
1220 1220 source = '<timed exec>'
1221 1221 t0 = clock()
1222 1222 code = self.shell.compile(expr_ast, source, mode)
1223 1223 tc = clock()-t0
1224 1224
1225 1225 # skew measurement as little as possible
1226 1226 glob = self.shell.user_ns
1227 1227 wtime = time.time
1228 1228 # time execution
1229 1229 wall_st = wtime()
1230 1230 if mode=='eval':
1231 1231 st = clock2()
1232 1232 try:
1233 1233 out = eval(code, glob, local_ns)
1234 1234 except:
1235 1235 self.shell.showtraceback()
1236 1236 return
1237 1237 end = clock2()
1238 1238 else:
1239 1239 st = clock2()
1240 1240 try:
1241 1241 exec(code, glob, local_ns)
1242 1242 except:
1243 1243 self.shell.showtraceback()
1244 1244 return
1245 1245 end = clock2()
1246 1246 out = None
1247 1247 wall_end = wtime()
1248 1248 # Compute actual times and report
1249 1249 wall_time = wall_end-wall_st
1250 1250 cpu_user = end[0]-st[0]
1251 1251 cpu_sys = end[1]-st[1]
1252 1252 cpu_tot = cpu_user+cpu_sys
1253 1253 # On windows cpu_sys is always zero, so no new information to the next print
1254 1254 if sys.platform != 'win32':
1255 1255 print("CPU times: user %s, sys: %s, total: %s" % \
1256 1256 (_format_time(cpu_user),_format_time(cpu_sys),_format_time(cpu_tot)))
1257 1257 print("Wall time: %s" % _format_time(wall_time))
1258 1258 if tc > tc_min:
1259 1259 print("Compiler : %s" % _format_time(tc))
1260 1260 if tp > tp_min:
1261 1261 print("Parser : %s" % _format_time(tp))
1262 1262 return out
1263 1263
1264 1264 @skip_doctest
1265 1265 @line_magic
1266 1266 def macro(self, parameter_s=''):
1267 1267 """Define a macro for future re-execution. It accepts ranges of history,
1268 1268 filenames or string objects.
1269 1269
1270 1270 Usage:\\
1271 1271 %macro [options] name n1-n2 n3-n4 ... n5 .. n6 ...
1272 1272
1273 1273 Options:
1274 1274
1275 1275 -r: use 'raw' input. By default, the 'processed' history is used,
1276 1276 so that magics are loaded in their transformed version to valid
1277 1277 Python. If this option is given, the raw input as typed at the
1278 1278 command line is used instead.
1279 1279
1280 1280 -q: quiet macro definition. By default, a tag line is printed
1281 1281 to indicate the macro has been created, and then the contents of
1282 1282 the macro are printed. If this option is given, then no printout
1283 1283 is produced once the macro is created.
1284 1284
1285 1285 This will define a global variable called `name` which is a string
1286 1286 made of joining the slices and lines you specify (n1,n2,... numbers
1287 1287 above) from your input history into a single string. This variable
1288 1288 acts like an automatic function which re-executes those lines as if
1289 1289 you had typed them. You just type 'name' at the prompt and the code
1290 1290 executes.
1291 1291
1292 1292 The syntax for indicating input ranges is described in %history.
1293 1293
1294 1294 Note: as a 'hidden' feature, you can also use traditional python slice
1295 1295 notation, where N:M means numbers N through M-1.
1296 1296
1297 1297 For example, if your history contains (print using %hist -n )::
1298 1298
1299 1299 44: x=1
1300 1300 45: y=3
1301 1301 46: z=x+y
1302 1302 47: print x
1303 1303 48: a=5
1304 1304 49: print 'x',x,'y',y
1305 1305
1306 1306 you can create a macro with lines 44 through 47 (included) and line 49
1307 1307 called my_macro with::
1308 1308
1309 1309 In [55]: %macro my_macro 44-47 49
1310 1310
1311 1311 Now, typing `my_macro` (without quotes) will re-execute all this code
1312 1312 in one pass.
1313 1313
1314 1314 You don't need to give the line-numbers in order, and any given line
1315 1315 number can appear multiple times. You can assemble macros with any
1316 1316 lines from your input history in any order.
1317 1317
1318 1318 The macro is a simple object which holds its value in an attribute,
1319 1319 but IPython's display system checks for macros and executes them as
1320 1320 code instead of printing them when you type their name.
1321 1321
1322 1322 You can view a macro's contents by explicitly printing it with::
1323 1323
1324 1324 print macro_name
1325 1325
1326 1326 """
1327 1327 opts,args = self.parse_options(parameter_s,'rq',mode='list')
1328 1328 if not args: # List existing macros
1329 1329 return sorted(k for k,v in self.shell.user_ns.items() if isinstance(v, Macro))
1330 1330 if len(args) == 1:
1331 1331 raise UsageError(
1332 1332 "%macro insufficient args; usage '%macro name n1-n2 n3-4...")
1333 1333 name, codefrom = args[0], " ".join(args[1:])
1334 1334
1335 1335 #print 'rng',ranges # dbg
1336 1336 try:
1337 1337 lines = self.shell.find_user_code(codefrom, 'r' in opts)
1338 1338 except (ValueError, TypeError) as e:
1339 1339 print(e.args[0])
1340 1340 return
1341 1341 macro = Macro(lines)
1342 1342 self.shell.define_macro(name, macro)
1343 1343 if not ( 'q' in opts) :
1344 1344 print('Macro `%s` created. To execute, type its name (without quotes).' % name)
1345 1345 print('=== Macro contents: ===')
1346 1346 print(macro, end=' ')
1347 1347
1348 1348 @magic_arguments.magic_arguments()
1349 1349 @magic_arguments.argument('output', type=str, default='', nargs='?',
1350 1350 help="""The name of the variable in which to store output.
1351 1351 This is a utils.io.CapturedIO object with stdout/err attributes
1352 1352 for the text of the captured output.
1353 1353
1354 1354 CapturedOutput also has a show() method for displaying the output,
1355 1355 and __call__ as well, so you can use that to quickly display the
1356 1356 output.
1357 1357
1358 1358 If unspecified, captured output is discarded.
1359 1359 """
1360 1360 )
1361 1361 @magic_arguments.argument('--no-stderr', action="store_true",
1362 1362 help="""Don't capture stderr."""
1363 1363 )
1364 1364 @magic_arguments.argument('--no-stdout', action="store_true",
1365 1365 help="""Don't capture stdout."""
1366 1366 )
1367 1367 @magic_arguments.argument('--no-display', action="store_true",
1368 1368 help="""Don't capture IPython's rich display."""
1369 1369 )
1370 1370 @cell_magic
1371 1371 def capture(self, line, cell):
1372 1372 """run the cell, capturing stdout, stderr, and IPython's rich display() calls."""
1373 1373 args = magic_arguments.parse_argstring(self.capture, line)
1374 1374 out = not args.no_stdout
1375 1375 err = not args.no_stderr
1376 1376 disp = not args.no_display
1377 1377 with capture_output(out, err, disp) as io:
1378 1378 self.shell.run_cell(cell)
1379 1379 if args.output:
1380 1380 self.shell.user_ns[args.output] = io
1381 1381
1382 1382 def parse_breakpoint(text, current_file):
1383 1383 '''Returns (file, line) for file:line and (current_file, line) for line'''
1384 1384 colon = text.find(':')
1385 1385 if colon == -1:
1386 1386 return current_file, int(text)
1387 1387 else:
1388 1388 return text[:colon], int(text[colon+1:])
1389 1389
1390 1390 def _format_time(timespan, precision=3):
1391 1391 """Formats the timespan in a human readable form"""
1392 1392
1393 1393 if timespan >= 60.0:
1394 1394 # we have more than a minute, format that in a human readable form
1395 1395 # Idea from http://snipplr.com/view/5713/
1396 1396 parts = [("d", 60*60*24),("h", 60*60),("min", 60), ("s", 1)]
1397 1397 time = []
1398 1398 leftover = timespan
1399 1399 for suffix, length in parts:
1400 1400 value = int(leftover / length)
1401 1401 if value > 0:
1402 1402 leftover = leftover % length
1403 1403 time.append(u'%s%s' % (str(value), suffix))
1404 1404 if leftover < 1:
1405 1405 break
1406 1406 return " ".join(time)
1407 1407
1408 1408
1409 1409 # Unfortunately the unicode 'micro' symbol can cause problems in
1410 1410 # certain terminals.
1411 1411 # See bug: https://bugs.launchpad.net/ipython/+bug/348466
1412 1412 # Try to prevent crashes by being more secure than it needs to
1413 1413 # E.g. eclipse is able to print a Β΅, but has no sys.stdout.encoding set.
1414 1414 units = [u"s", u"ms",u'us',"ns"] # the save value
1415 1415 if hasattr(sys.stdout, 'encoding') and sys.stdout.encoding:
1416 1416 try:
1417 1417 u'\xb5'.encode(sys.stdout.encoding)
1418 1418 units = [u"s", u"ms",u'\xb5s',"ns"]
1419 1419 except:
1420 1420 pass
1421 1421 scaling = [1, 1e3, 1e6, 1e9]
1422 1422
1423 1423 if timespan > 0.0:
1424 1424 order = min(-int(math.floor(math.log10(timespan)) // 3), 3)
1425 1425 else:
1426 1426 order = 3
1427 1427 return u"%.*g %s" % (precision, timespan * scaling[order], units[order])
@@ -1,281 +1,281 b''
1 1 """Tests for the token-based transformers in IPython.core.inputtransformer2
2 2
3 3 Line-based transformers are the simpler ones; token-based transformers are
4 4 more complex. See test_inputtransformer2_line for tests for line-based
5 5 transformations.
6 6 """
7 7 import nose.tools as nt
8 8 import string
9 9
10 10 from IPython.core import inputtransformer2 as ipt2
11 11 from IPython.core.inputtransformer2 import make_tokens_by_line, _find_assign_op
12 12
13 13 from textwrap import dedent
14 14
15 15 MULTILINE_MAGIC = ("""\
16 16 a = f()
17 17 %foo \\
18 18 bar
19 19 g()
20 20 """.splitlines(keepends=True), (2, 0), """\
21 21 a = f()
22 22 get_ipython().run_line_magic('foo', ' bar')
23 23 g()
24 24 """.splitlines(keepends=True))
25 25
26 26 INDENTED_MAGIC = ("""\
27 27 for a in range(5):
28 28 %ls
29 29 """.splitlines(keepends=True), (2, 4), """\
30 30 for a in range(5):
31 31 get_ipython().run_line_magic('ls', '')
32 32 """.splitlines(keepends=True))
33 33
34 34 MULTILINE_MAGIC_ASSIGN = ("""\
35 35 a = f()
36 36 b = %foo \\
37 37 bar
38 38 g()
39 39 """.splitlines(keepends=True), (2, 4), """\
40 40 a = f()
41 41 b = get_ipython().run_line_magic('foo', ' bar')
42 42 g()
43 43 """.splitlines(keepends=True))
44 44
45 45 MULTILINE_SYSTEM_ASSIGN = ("""\
46 46 a = f()
47 47 b = !foo \\
48 48 bar
49 49 g()
50 50 """.splitlines(keepends=True), (2, 4), """\
51 51 a = f()
52 52 b = get_ipython().getoutput('foo bar')
53 53 g()
54 54 """.splitlines(keepends=True))
55 55
56 56 #####
57 57
58 58 MULTILINE_SYSTEM_ASSIGN_AFTER_DEDENT = ("""\
59 59 def test():
60 60 for i in range(1):
61 61 print(i)
62 62 res =! ls
63 63 """.splitlines(keepends=True), (4, 7), '''\
64 64 def test():
65 65 for i in range(1):
66 66 print(i)
67 67 res =get_ipython().getoutput(\' ls\')
68 68 '''.splitlines(keepends=True))
69 69
70 70 ######
71 71
72 72 AUTOCALL_QUOTE = (
73 73 [",f 1 2 3\n"], (1, 0),
74 74 ['f("1", "2", "3")\n']
75 75 )
76 76
77 77 AUTOCALL_QUOTE2 = (
78 78 [";f 1 2 3\n"], (1, 0),
79 79 ['f("1 2 3")\n']
80 80 )
81 81
82 82 AUTOCALL_PAREN = (
83 83 ["/f 1 2 3\n"], (1, 0),
84 84 ['f(1, 2, 3)\n']
85 85 )
86 86
87 87 SIMPLE_HELP = (
88 88 ["foo?\n"], (1, 0),
89 89 ["get_ipython().run_line_magic('pinfo', 'foo')\n"]
90 90 )
91 91
92 92 DETAILED_HELP = (
93 93 ["foo??\n"], (1, 0),
94 94 ["get_ipython().run_line_magic('pinfo2', 'foo')\n"]
95 95 )
96 96
97 97 MAGIC_HELP = (
98 98 ["%foo?\n"], (1, 0),
99 99 ["get_ipython().run_line_magic('pinfo', '%foo')\n"]
100 100 )
101 101
102 102 HELP_IN_EXPR = (
103 103 ["a = b + c?\n"], (1, 0),
104 104 ["get_ipython().set_next_input('a = b + c');"
105 105 "get_ipython().run_line_magic('pinfo', 'c')\n"]
106 106 )
107 107
108 108 HELP_CONTINUED_LINE = ("""\
109 109 a = \\
110 110 zip?
111 111 """.splitlines(keepends=True), (1, 0),
112 112 [r"get_ipython().set_next_input('a = \\\nzip');get_ipython().run_line_magic('pinfo', 'zip')" + "\n"]
113 113 )
114 114
115 115 HELP_MULTILINE = ("""\
116 116 (a,
117 117 b) = zip?
118 118 """.splitlines(keepends=True), (1, 0),
119 119 [r"get_ipython().set_next_input('(a,\nb) = zip');get_ipython().run_line_magic('pinfo', 'zip')" + "\n"]
120 120 )
121 121
122 122
123 123 def null_cleanup_transformer(lines):
124 124 """
125 125 A cleanup transform that returns an empty list.
126 126 """
127 127 return []
128 128
129 129 def check_make_token_by_line_never_ends_empty():
130 130 """
131 131 Check that not sequence of single or double characters ends up leading to en empty list of tokens
132 132 """
133 133 from string import printable
134 134 for c in printable:
135 135 nt.assert_not_equal(make_tokens_by_line(c)[-1], [])
136 136 for k in printable:
137 137 nt.assert_not_equal(make_tokens_by_line(c+k)[-1], [])
138 138
139 139 def check_find(transformer, case, match=True):
140 140 sample, expected_start, _ = case
141 141 tbl = make_tokens_by_line(sample)
142 142 res = transformer.find(tbl)
143 143 if match:
144 144 # start_line is stored 0-indexed, expected values are 1-indexed
145 145 nt.assert_equal((res.start_line+1, res.start_col), expected_start)
146 146 return res
147 147 else:
148 148 nt.assert_is(res, None)
149 149
150 150 def check_transform(transformer_cls, case):
151 151 lines, start, expected = case
152 152 transformer = transformer_cls(start)
153 153 nt.assert_equal(transformer.transform(lines), expected)
154 154
155 155 def test_continued_line():
156 156 lines = MULTILINE_MAGIC_ASSIGN[0]
157 157 nt.assert_equal(ipt2.find_end_of_continued_line(lines, 1), 2)
158 158
159 159 nt.assert_equal(ipt2.assemble_continued_line(lines, (1, 5), 2), "foo bar")
160 160
161 161 def test_find_assign_magic():
162 162 check_find(ipt2.MagicAssign, MULTILINE_MAGIC_ASSIGN)
163 163 check_find(ipt2.MagicAssign, MULTILINE_SYSTEM_ASSIGN, match=False)
164 164 check_find(ipt2.MagicAssign, MULTILINE_SYSTEM_ASSIGN_AFTER_DEDENT, match=False)
165 165
166 166 def test_transform_assign_magic():
167 167 check_transform(ipt2.MagicAssign, MULTILINE_MAGIC_ASSIGN)
168 168
169 169 def test_find_assign_system():
170 170 check_find(ipt2.SystemAssign, MULTILINE_SYSTEM_ASSIGN)
171 171 check_find(ipt2.SystemAssign, MULTILINE_SYSTEM_ASSIGN_AFTER_DEDENT)
172 172 check_find(ipt2.SystemAssign, (["a = !ls\n"], (1, 5), None))
173 173 check_find(ipt2.SystemAssign, (["a=!ls\n"], (1, 2), None))
174 174 check_find(ipt2.SystemAssign, MULTILINE_MAGIC_ASSIGN, match=False)
175 175
176 176 def test_transform_assign_system():
177 177 check_transform(ipt2.SystemAssign, MULTILINE_SYSTEM_ASSIGN)
178 178 check_transform(ipt2.SystemAssign, MULTILINE_SYSTEM_ASSIGN_AFTER_DEDENT)
179 179
180 180 def test_find_magic_escape():
181 181 check_find(ipt2.EscapedCommand, MULTILINE_MAGIC)
182 182 check_find(ipt2.EscapedCommand, INDENTED_MAGIC)
183 183 check_find(ipt2.EscapedCommand, MULTILINE_MAGIC_ASSIGN, match=False)
184 184
185 185 def test_transform_magic_escape():
186 186 check_transform(ipt2.EscapedCommand, MULTILINE_MAGIC)
187 187 check_transform(ipt2.EscapedCommand, INDENTED_MAGIC)
188 188
189 189 def test_find_autocalls():
190 190 for case in [AUTOCALL_QUOTE, AUTOCALL_QUOTE2, AUTOCALL_PAREN]:
191 191 print("Testing %r" % case[0])
192 192 check_find(ipt2.EscapedCommand, case)
193 193
194 194 def test_transform_autocall():
195 195 for case in [AUTOCALL_QUOTE, AUTOCALL_QUOTE2, AUTOCALL_PAREN]:
196 196 print("Testing %r" % case[0])
197 197 check_transform(ipt2.EscapedCommand, case)
198 198
199 199 def test_find_help():
200 200 for case in [SIMPLE_HELP, DETAILED_HELP, MAGIC_HELP, HELP_IN_EXPR]:
201 201 check_find(ipt2.HelpEnd, case)
202 202
203 203 tf = check_find(ipt2.HelpEnd, HELP_CONTINUED_LINE)
204 204 nt.assert_equal(tf.q_line, 1)
205 205 nt.assert_equal(tf.q_col, 3)
206 206
207 207 tf = check_find(ipt2.HelpEnd, HELP_MULTILINE)
208 208 nt.assert_equal(tf.q_line, 1)
209 209 nt.assert_equal(tf.q_col, 8)
210 210
211 211 # ? in a comment does not trigger help
212 212 check_find(ipt2.HelpEnd, (["foo # bar?\n"], None, None), match=False)
213 213 # Nor in a string
214 214 check_find(ipt2.HelpEnd, (["foo = '''bar?\n"], None, None), match=False)
215 215
216 216 def test_transform_help():
217 217 tf = ipt2.HelpEnd((1, 0), (1, 9))
218 218 nt.assert_equal(tf.transform(HELP_IN_EXPR[0]), HELP_IN_EXPR[2])
219 219
220 220 tf = ipt2.HelpEnd((1, 0), (2, 3))
221 221 nt.assert_equal(tf.transform(HELP_CONTINUED_LINE[0]), HELP_CONTINUED_LINE[2])
222 222
223 223 tf = ipt2.HelpEnd((1, 0), (2, 8))
224 224 nt.assert_equal(tf.transform(HELP_MULTILINE[0]), HELP_MULTILINE[2])
225 225
226 226 def test_find_assign_op_dedent():
227 227 """
228 be carefull that empty token like dedent are not counted as parens
228 be careful that empty token like dedent are not counted as parens
229 229 """
230 230 class Tk:
231 231 def __init__(self, s):
232 232 self.string = s
233 233
234 234 nt.assert_equal(_find_assign_op([Tk(s) for s in ('','a','=','b')]), 2)
235 235 nt.assert_equal(_find_assign_op([Tk(s) for s in ('','(', 'a','=','b', ')', '=' ,'5')]), 6)
236 236
237 237 def test_check_complete():
238 238 cc = ipt2.TransformerManager().check_complete
239 239 nt.assert_equal(cc("a = 1"), ('complete', None))
240 240 nt.assert_equal(cc("for a in range(5):"), ('incomplete', 4))
241 241 nt.assert_equal(cc("raise = 2"), ('invalid', None))
242 242 nt.assert_equal(cc("a = [1,\n2,"), ('incomplete', 0))
243 243 nt.assert_equal(cc(")"), ('incomplete', 0))
244 244 nt.assert_equal(cc("\\\r\n"), ('incomplete', 0))
245 245 nt.assert_equal(cc("a = '''\n hi"), ('incomplete', 3))
246 246 nt.assert_equal(cc("def a():\n x=1\n global x"), ('invalid', None))
247 247 nt.assert_equal(cc("a \\ "), ('invalid', None)) # Nothing allowed after backslash
248 248 nt.assert_equal(cc("1\\\n+2"), ('complete', None))
249 249 nt.assert_equal(cc("exit"), ('complete', None))
250 250
251 251 example = dedent("""
252 252 if True:
253 253 a=1""" )
254 254
255 255 nt.assert_equal(cc(example), ('incomplete', 4))
256 256 nt.assert_equal(cc(example+'\n'), ('complete', None))
257 257 nt.assert_equal(cc(example+'\n '), ('complete', None))
258 258
259 259 # no need to loop on all the letters/numbers.
260 260 short = '12abAB'+string.printable[62:]
261 261 for c in short:
262 262 # test does not raise:
263 263 cc(c)
264 264 for k in short:
265 265 cc(c+k)
266 266
267 267 def test_check_complete_II():
268 268 """
269 269 Test that multiple line strings are properly handled.
270 270
271 271 Separate test function for convenience
272 272
273 273 """
274 274 cc = ipt2.TransformerManager().check_complete
275 275 nt.assert_equal(cc('''def foo():\n """'''), ('incomplete', 4))
276 276
277 277
278 278 def test_null_cleanup_transformer():
279 279 manager = ipt2.TransformerManager()
280 280 manager.cleanup_transforms.insert(0, null_cleanup_transformer)
281 281 nt.assert_is(manager.transform_cell(""), "")
General Comments 0
You need to be logged in to leave comments. Login now