##// END OF EJS Templates
Improvements to docs formatting.
Thomas Kluyver -
r12553:43ed80e5
parent child
Show More
@@ -24,26 +24,26 Tip: to use the tab key as the completion key, call
24 Notes:
24 Notes:
25
25
26 - Exceptions raised by the completer function are *ignored* (and
26 - Exceptions raised by the completer function are *ignored* (and
27 generally cause the completion to fail). This is a feature -- since
27 generally cause the completion to fail). This is a feature -- since
28 readline sets the tty device in raw (or cbreak) mode, printing a
28 readline sets the tty device in raw (or cbreak) mode, printing a
29 traceback wouldn't work well without some complicated hoopla to save,
29 traceback wouldn't work well without some complicated hoopla to save,
30 reset and restore the tty state.
30 reset and restore the tty state.
31
31
32 - The evaluation of the NAME.NAME... form may cause arbitrary
32 - The evaluation of the NAME.NAME... form may cause arbitrary
33 application defined code to be executed if an object with a
33 application defined code to be executed if an object with a
34 __getattr__ hook is found. Since it is the responsibility of the
34 ``__getattr__`` hook is found. Since it is the responsibility of the
35 application (or the user) to enable this feature, I consider this an
35 application (or the user) to enable this feature, I consider this an
36 acceptable risk. More complicated expressions (e.g. function calls or
36 acceptable risk. More complicated expressions (e.g. function calls or
37 indexing operations) are *not* evaluated.
37 indexing operations) are *not* evaluated.
38
38
39 - GNU readline is also used by the built-in functions input() and
39 - GNU readline is also used by the built-in functions input() and
40 raw_input(), and thus these also benefit/suffer from the completer
40 raw_input(), and thus these also benefit/suffer from the completer
41 features. Clearly an interactive application can benefit by
41 features. Clearly an interactive application can benefit by
42 specifying its own completer function and using raw_input() for all
42 specifying its own completer function and using raw_input() for all
43 its input.
43 its input.
44
44
45 - When the original stdin is not a tty device, GNU readline is never
45 - When the original stdin is not a tty device, GNU readline is never
46 used, and this module (and the readline module) are silently inactive.
46 used, and this module (and the readline module) are silently inactive.
47 """
47 """
48
48
49 #*****************************************************************************
49 #*****************************************************************************
@@ -441,17 +441,17 class IPCompleter(Completer):
441 Inputs:
441 Inputs:
442
442
443 - shell: a pointer to the ipython shell itself. This is needed
443 - shell: a pointer to the ipython shell itself. This is needed
444 because this completer knows about magic functions, and those can
444 because this completer knows about magic functions, and those can
445 only be accessed via the ipython instance.
445 only be accessed via the ipython instance.
446
446
447 - namespace: an optional dict where completions are performed.
447 - namespace: an optional dict where completions are performed.
448
448
449 - global_namespace: secondary optional dict for completions, to
449 - global_namespace: secondary optional dict for completions, to
450 handle cases (such as IPython embedded inside functions) where
450 handle cases (such as IPython embedded inside functions) where
451 both Python scopes are visible.
451 both Python scopes are visible.
452
452
453 - If alias_table is supplied, it should be a dictionary of aliases
453 - If alias_table is supplied, it should be a dictionary of aliases
454 to complete.
454 to complete.
455
455
456 use_readline : bool, optional
456 use_readline : bool, optional
457 If true, use the readline library. This completer can still function
457 If true, use the readline library. This completer can still function
@@ -96,19 +96,24 class Tracer(object):
96 def __init__(self,colors=None):
96 def __init__(self,colors=None):
97 """Create a local debugger instance.
97 """Create a local debugger instance.
98
98
99 :Parameters:
99 Parameters
100 ----------
100
101
101 - `colors` (None): a string containing the name of the color scheme to
102 colors : str, optional
102 use, it must be one of IPython's valid color schemes. If not given, the
103 The name of the color scheme to use, it must be one of IPython's
103 function will default to the current IPython scheme when running inside
104 valid color schemes. If not given, the function will default to
104 IPython, and to 'NoColor' otherwise.
105 the current IPython scheme when running inside IPython, and to
106 'NoColor' otherwise.
105
107
106 Usage example:
108 Examples
109 --------
110 ::
107
111
108 from IPython.core.debugger import Tracer; debug_here = Tracer()
112 from IPython.core.debugger import Tracer; debug_here = Tracer()
109
113
110 ... later in your code
114 Later in your code::
111 debug_here() # -> will open up the debugger at that point.
115
116 debug_here() # -> will open up the debugger at that point.
112
117
113 Once the debugger activates, you can use all of its regular commands to
118 Once the debugger activates, you can use all of its regular commands to
114 step through code, set breakpoints, etc. See the pdb documentation
119 step through code, set breakpoints, etc. See the pdb documentation
@@ -907,9 +907,9 class InteractiveShell(SingletonConfigurable):
907 Keywords:
907 Keywords:
908
908
909 - force(False): by default, this routine checks the instance call_pdb
909 - force(False): by default, this routine checks the instance call_pdb
910 flag and does not actually invoke the debugger if the flag is false.
910 flag and does not actually invoke the debugger if the flag is false.
911 The 'force' option forces the debugger to activate even if the flag
911 The 'force' option forces the debugger to activate even if the flag
912 is false.
912 is false.
913 """
913 """
914
914
915 if not (force or self.call_pdb):
915 if not (force or self.call_pdb):
@@ -2978,7 +2978,7 class InteractiveShell(SingletonConfigurable):
2978 Optional inputs:
2978 Optional inputs:
2979
2979
2980 - data(None): if data is given, it gets written out to the temp file
2980 - data(None): if data is given, it gets written out to the temp file
2981 immediately, and the file is closed again."""
2981 immediately, and the file is closed again."""
2982
2982
2983 filename = tempfile.mktemp('.py', prefix)
2983 filename = tempfile.mktemp('.py', prefix)
2984 self.tempfiles.append(filename)
2984 self.tempfiles.append(filename)
@@ -3021,13 +3021,14 class InteractiveShell(SingletonConfigurable):
3021
3021
3022 Optional Parameters:
3022 Optional Parameters:
3023 - raw(False): by default, the processed input is used. If this is
3023 - raw(False): by default, the processed input is used. If this is
3024 true, the raw input history is used instead.
3024 true, the raw input history is used instead.
3025
3025
3026 Note that slices can be called with two notations:
3026 Note that slices can be called with two notations:
3027
3027
3028 N:M -> standard python form, means including items N...(M-1).
3028 N:M -> standard python form, means including items N...(M-1).
3029
3029
3030 N-M -> include items N..M (closed endpoint)."""
3030 N-M -> include items N..M (closed endpoint).
3031 """
3031 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3032 lines = self.history_manager.get_range_by_str(range_str, raw=raw)
3032 return "\n".join(x for _, _, x in lines)
3033 return "\n".join(x for _, _, x in lines)
3033
3034
@@ -171,11 +171,11 which already exists. But you must first start the logging process with
171 Inputs:
171 Inputs:
172
172
173 - line_mod: possibly modified input, such as the transformations made
173 - line_mod: possibly modified input, such as the transformations made
174 by input prefilters or input handlers of various kinds. This should
174 by input prefilters or input handlers of various kinds. This should
175 always be valid Python.
175 always be valid Python.
176
176
177 - line_ori: unmodified input line from the user. This is not
177 - line_ori: unmodified input line from the user. This is not
178 necessarily valid Python.
178 necessarily valid Python.
179 """
179 """
180
180
181 # Write the log line, but decide which one according to the
181 # Write the log line, but decide which one according to the
@@ -489,11 +489,11 class Magics(object):
489 MUST:
489 MUST:
490
490
491 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
491 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
492 individual methods as magic functions, AND
492 individual methods as magic functions, AND
493
493
494 - Use the class decorator `@magics_class` to ensure that the magic
494 - Use the class decorator `@magics_class` to ensure that the magic
495 methods are properly registered at the instance level upon instance
495 methods are properly registered at the instance level upon instance
496 initialization.
496 initialization.
497
497
498 See :mod:`magic_functions` for examples of actual implementation classes.
498 See :mod:`magic_functions` for examples of actual implementation classes.
499 """
499 """
@@ -102,75 +102,84 python-profiler package from non-free.""")
102
102
103 Options:
103 Options:
104
104
105 -l <limit>: you can place restrictions on what or how much of the
105 -l <limit>
106 profile gets printed. The limit value can be:
106 you can place restrictions on what or how much of the
107
107 profile gets printed. The limit value can be:
108 * A string: only information for function names containing this string
108
109 is printed.
109 * A string: only information for function names containing this string
110
110 is printed.
111 * An integer: only these many lines are printed.
111
112
112 * An integer: only these many lines are printed.
113 * A float (between 0 and 1): this fraction of the report is printed
113
114 (for example, use a limit of 0.4 to see the topmost 40% only).
114 * A float (between 0 and 1): this fraction of the report is printed
115
115 (for example, use a limit of 0.4 to see the topmost 40% only).
116 You can combine several limits with repeated use of the option. For
116
117 example, '-l __init__ -l 5' will print only the topmost 5 lines of
117 You can combine several limits with repeated use of the option. For
118 information about class constructors.
118 example, ``-l __init__ -l 5`` will print only the topmost 5 lines of
119
119 information about class constructors.
120 -r: return the pstats.Stats object generated by the profiling. This
120
121 object has all the information about the profile in it, and you can
121 -r
122 later use it for further analysis or in other functions.
122 return the pstats.Stats object generated by the profiling. This
123
123 object has all the information about the profile in it, and you can
124 -s <key>: sort profile by given key. You can provide more than one key
124 later use it for further analysis or in other functions.
125 by using the option several times: '-s key1 -s key2 -s key3...'. The
125
126 default sorting key is 'time'.
126 -s <key>
127
127 sort profile by given key. You can provide more than one key
128 The following is copied verbatim from the profile documentation
128 by using the option several times: '-s key1 -s key2 -s key3...'. The
129 referenced below:
129 default sorting key is 'time'.
130
130
131 When more than one key is provided, additional keys are used as
131 The following is copied verbatim from the profile documentation
132 secondary criteria when the there is equality in all keys selected
132 referenced below:
133 before them.
133
134
134 When more than one key is provided, additional keys are used as
135 Abbreviations can be used for any key names, as long as the
135 secondary criteria when the there is equality in all keys selected
136 abbreviation is unambiguous. The following are the keys currently
136 before them.
137 defined:
137
138
138 Abbreviations can be used for any key names, as long as the
139 Valid Arg Meaning
139 abbreviation is unambiguous. The following are the keys currently
140 "calls" call count
140 defined:
141 "cumulative" cumulative time
141
142 "file" file name
142 ============ =====================
143 "module" file name
143 Valid Arg Meaning
144 "pcalls" primitive call count
144 ============ =====================
145 "line" line number
145 "calls" call count
146 "name" function name
146 "cumulative" cumulative time
147 "nfl" name/file/line
147 "file" file name
148 "stdname" standard name
148 "module" file name
149 "time" internal time
149 "pcalls" primitive call count
150
150 "line" line number
151 Note that all sorts on statistics are in descending order (placing
151 "name" function name
152 most time consuming items first), where as name, file, and line number
152 "nfl" name/file/line
153 searches are in ascending order (i.e., alphabetical). The subtle
153 "stdname" standard name
154 distinction between "nfl" and "stdname" is that the standard name is a
154 "time" internal time
155 sort of the name as printed, which means that the embedded line
155 ============ =====================
156 numbers get compared in an odd way. For example, lines 3, 20, and 40
156
157 would (if the file names were the same) appear in the string order
157 Note that all sorts on statistics are in descending order (placing
158 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
158 most time consuming items first), where as name, file, and line number
159 line numbers. In fact, sort_stats("nfl") is the same as
159 searches are in ascending order (i.e., alphabetical). The subtle
160 sort_stats("name", "file", "line").
160 distinction between "nfl" and "stdname" is that the standard name is a
161
161 sort of the name as printed, which means that the embedded line
162 -T <filename>: save profile results as shown on screen to a text
162 numbers get compared in an odd way. For example, lines 3, 20, and 40
163 file. The profile is still shown on screen.
163 would (if the file names were the same) appear in the string order
164
164 "20" "3" and "40". In contrast, "nfl" does a numeric compare of the
165 -D <filename>: save (via dump_stats) profile statistics to given
165 line numbers. In fact, sort_stats("nfl") is the same as
166 filename. This data is in a format understood by the pstats module, and
166 sort_stats("name", "file", "line").
167 is generated by a call to the dump_stats() method of profile
167
168 objects. The profile is still shown on screen.
168 -T <filename>
169
169 save profile results as shown on screen to a text
170 -q: suppress output to the pager. Best used with -T and/or -D above.
170 file. The profile is still shown on screen.
171
172 -D <filename>
173 save (via dump_stats) profile statistics to given
174 filename. This data is in a format understood by the pstats module, and
175 is generated by a call to the dump_stats() method of profile
176 objects. The profile is still shown on screen.
177
178 -q
179 suppress output to the pager. Best used with -T and/or -D above.
171
180
172 If you want to run complete programs under the profiler's control, use
181 If you want to run complete programs under the profiler's control, use
173 '%run -p [prof_opts] filename.py [args to program]' where prof_opts
182 ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts
174 contains profiler specific options as described here.
183 contains profiler specific options as described here.
175
184
176 You can read the complete documentation for the profile module with::
185 You can read the complete documentation for the profile module with::
@@ -362,7 +371,8 python-profiler package from non-free.""")
362 file_finder=get_py_filename):
371 file_finder=get_py_filename):
363 """Run the named file inside IPython as a program.
372 """Run the named file inside IPython as a program.
364
373
365 Usage:
374 Usage::
375
366 %run [-n -i -e -G]
376 %run [-n -i -e -G]
367 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
377 [( -t [-N<N>] | -d [-b<N>] | -p [profile options] )]
368 ( -m mod | file ) [args]
378 ( -m mod | file ) [args]
@@ -371,14 +381,13 python-profiler package from non-free.""")
371 the program (put in sys.argv). Then, control returns to IPython's
381 the program (put in sys.argv). Then, control returns to IPython's
372 prompt.
382 prompt.
373
383
374 This is similar to running at a system prompt:\\
384 This is similar to running at a system prompt ``python file args``,
375 $ python file args\\
376 but with the advantage of giving you IPython's tracebacks, and of
385 but with the advantage of giving you IPython's tracebacks, and of
377 loading all variables into your interactive namespace for further use
386 loading all variables into your interactive namespace for further use
378 (unless -p is used, see below).
387 (unless -p is used, see below).
379
388
380 The file is executed in a namespace initially consisting only of
389 The file is executed in a namespace initially consisting only of
381 __name__=='__main__' and sys.argv constructed as indicated. It thus
390 ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus
382 sees its environment as if it were being run as a stand-alone program
391 sees its environment as if it were being run as a stand-alone program
383 (except for sharing global objects such as previously imported
392 (except for sharing global objects such as previously imported
384 modules). But after execution, the IPython interactive namespace gets
393 modules). But after execution, the IPython interactive namespace gets
@@ -390,33 +399,37 python-profiler package from non-free.""")
390 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
399 '*', '?', '[seq]' and '[!seq]' can be used. Additionally,
391 tilde '~' will be expanded into user's home directory. Unlike
400 tilde '~' will be expanded into user's home directory. Unlike
392 real shells, quotation does not suppress expansions. Use
401 real shells, quotation does not suppress expansions. Use
393 *two* back slashes (e.g., '\\\\*') to suppress expansions.
402 *two* back slashes (e.g. ``\\\\*``) to suppress expansions.
394 To completely disable these expansions, you can use -G flag.
403 To completely disable these expansions, you can use -G flag.
395
404
396 Options:
405 Options:
397
406
398 -n: __name__ is NOT set to '__main__', but to the running file's name
407 -n
399 without extension (as python does under import). This allows running
408 __name__ is NOT set to '__main__', but to the running file's name
400 scripts and reloading the definitions in them without calling code
409 without extension (as python does under import). This allows running
401 protected by an ' if __name__ == "__main__" ' clause.
410 scripts and reloading the definitions in them without calling code
402
411 protected by an ``if __name__ == "__main__"`` clause.
403 -i: run the file in IPython's namespace instead of an empty one. This
412
404 is useful if you are experimenting with code written in a text editor
413 -i
405 which depends on variables defined interactively.
414 run the file in IPython's namespace instead of an empty one. This
406
415 is useful if you are experimenting with code written in a text editor
407 -e: ignore sys.exit() calls or SystemExit exceptions in the script
416 which depends on variables defined interactively.
408 being run. This is particularly useful if IPython is being used to
417
409 run unittests, which always exit with a sys.exit() call. In such
418 -e
410 cases you are interested in the output of the test results, not in
419 ignore sys.exit() calls or SystemExit exceptions in the script
411 seeing a traceback of the unittest module.
420 being run. This is particularly useful if IPython is being used to
412
421 run unittests, which always exit with a sys.exit() call. In such
413 -t: print timing information at the end of the run. IPython will give
422 cases you are interested in the output of the test results, not in
414 you an estimated CPU time consumption for your script, which under
423 seeing a traceback of the unittest module.
415 Unix uses the resource module to avoid the wraparound problems of
424
416 time.clock(). Under Unix, an estimate of time spent on system tasks
425 -t
417 is also given (for Windows platforms this is reported as 0.0).
426 print timing information at the end of the run. IPython will give
418
427 you an estimated CPU time consumption for your script, which under
419 If -t is given, an additional -N<N> option can be given, where <N>
428 Unix uses the resource module to avoid the wraparound problems of
429 time.clock(). Under Unix, an estimate of time spent on system tasks
430 is also given (for Windows platforms this is reported as 0.0).
431
432 If -t is given, an additional ``-N<N>`` option can be given, where <N>
420 must be an integer indicating how many times you want the script to
433 must be an integer indicating how many times you want the script to
421 run. The final timing report will include total and per run results.
434 run. The final timing report will include total and per run results.
422
435
@@ -424,74 +437,78 python-profiler package from non-free.""")
424
437
425 In [1]: run -t uniq_stable
438 In [1]: run -t uniq_stable
426
439
427 IPython CPU timings (estimated):\\
440 IPython CPU timings (estimated):
428 User : 0.19597 s.\\
441 User : 0.19597 s.
429 System: 0.0 s.\\
442 System: 0.0 s.
430
443
431 In [2]: run -t -N5 uniq_stable
444 In [2]: run -t -N5 uniq_stable
432
445
433 IPython CPU timings (estimated):\\
446 IPython CPU timings (estimated):
434 Total runs performed: 5\\
447 Total runs performed: 5
435 Times : Total Per run\\
448 Times : Total Per run
436 User : 0.910862 s, 0.1821724 s.\\
449 User : 0.910862 s, 0.1821724 s.
437 System: 0.0 s, 0.0 s.
450 System: 0.0 s, 0.0 s.
438
451
439 -d: run your program under the control of pdb, the Python debugger.
452 -d
440 This allows you to execute your program step by step, watch variables,
453 run your program under the control of pdb, the Python debugger.
441 etc. Internally, what IPython does is similar to calling:
454 This allows you to execute your program step by step, watch variables,
455 etc. Internally, what IPython does is similar to calling::
442
456
443 pdb.run('execfile("YOURFILENAME")')
457 pdb.run('execfile("YOURFILENAME")')
444
458
445 with a breakpoint set on line 1 of your file. You can change the line
459 with a breakpoint set on line 1 of your file. You can change the line
446 number for this automatic breakpoint to be <N> by using the -bN option
460 number for this automatic breakpoint to be <N> by using the -bN option
447 (where N must be an integer). For example::
461 (where N must be an integer). For example::
448
462
449 %run -d -b40 myscript
463 %run -d -b40 myscript
450
464
451 will set the first breakpoint at line 40 in myscript.py. Note that
465 will set the first breakpoint at line 40 in myscript.py. Note that
452 the first breakpoint must be set on a line which actually does
466 the first breakpoint must be set on a line which actually does
453 something (not a comment or docstring) for it to stop execution.
467 something (not a comment or docstring) for it to stop execution.
454
468
455 Or you can specify a breakpoint in a different file::
469 Or you can specify a breakpoint in a different file::
456
470
457 %run -d -b myotherfile.py:20 myscript
471 %run -d -b myotherfile.py:20 myscript
458
472
459 When the pdb debugger starts, you will see a (Pdb) prompt. You must
473 When the pdb debugger starts, you will see a (Pdb) prompt. You must
460 first enter 'c' (without quotes) to start execution up to the first
474 first enter 'c' (without quotes) to start execution up to the first
461 breakpoint.
475 breakpoint.
462
476
463 Entering 'help' gives information about the use of the debugger. You
477 Entering 'help' gives information about the use of the debugger. You
464 can easily see pdb's full documentation with "import pdb;pdb.help()"
478 can easily see pdb's full documentation with "import pdb;pdb.help()"
465 at a prompt.
479 at a prompt.
466
480
467 -p: run program under the control of the Python profiler module (which
481 -p
468 prints a detailed report of execution times, function calls, etc).
482 run program under the control of the Python profiler module (which
483 prints a detailed report of execution times, function calls, etc).
469
484
470 You can pass other options after -p which affect the behavior of the
485 You can pass other options after -p which affect the behavior of the
471 profiler itself. See the docs for %prun for details.
486 profiler itself. See the docs for %prun for details.
472
487
473 In this mode, the program's variables do NOT propagate back to the
488 In this mode, the program's variables do NOT propagate back to the
474 IPython interactive namespace (because they remain in the namespace
489 IPython interactive namespace (because they remain in the namespace
475 where the profiler executes them).
490 where the profiler executes them).
476
491
477 Internally this triggers a call to %prun, see its documentation for
492 Internally this triggers a call to %prun, see its documentation for
478 details on the options available specifically for profiling.
493 details on the options available specifically for profiling.
479
494
480 There is one special usage for which the text above doesn't apply:
495 There is one special usage for which the text above doesn't apply:
481 if the filename ends with .ipy, the file is run as ipython script,
496 if the filename ends with .ipy, the file is run as ipython script,
482 just as if the commands were written on IPython prompt.
497 just as if the commands were written on IPython prompt.
483
498
484 -m: specify module name to load instead of script path. Similar to
499 -m
485 the -m option for the python interpreter. Use this option last if you
500 specify module name to load instead of script path. Similar to
486 want to combine with other %run options. Unlike the python interpreter
501 the -m option for the python interpreter. Use this option last if you
487 only source modules are allowed no .pyc or .pyo files.
502 want to combine with other %run options. Unlike the python interpreter
488 For example::
503 only source modules are allowed no .pyc or .pyo files.
504 For example::
489
505
490 %run -m example
506 %run -m example
491
507
492 will run the example module.
508 will run the example module.
493
509
494 -G: disable shell-like glob expansion of arguments.
510 -G
511 disable shell-like glob expansion of arguments.
495
512
496 """
513 """
497
514
@@ -42,34 +42,48 class LoggingMagics(Magics):
42 history up to that point and then continues logging.
42 history up to that point and then continues logging.
43
43
44 %logstart takes a second optional parameter: logging mode. This can be one
44 %logstart takes a second optional parameter: logging mode. This can be one
45 of (note that the modes are given unquoted):\\
45 of (note that the modes are given unquoted):
46 append: well, that says it.\\
46
47 backup: rename (if exists) to name~ and start name.\\
47 append
48 global: single logfile in your home dir, appended to.\\
48 Keep logging at the end of any existing file.
49 over : overwrite existing log.\\
49
50 rotate: create rotating logs name.1~, name.2~, etc.
50 backup
51 Rename any existing file to name~ and start name.
52
53 global
54 Append to a single logfile in your home directory.
55
56 over
57 Overwrite any existing log.
58
59 rotate
60 Create rotating logs: name.1~, name.2~, etc.
51
61
52 Options:
62 Options:
53
63
54 -o: log also IPython's output. In this mode, all commands which
64 -o
55 generate an Out[NN] prompt are recorded to the logfile, right after
65 log also IPython's output. In this mode, all commands which
56 their corresponding input line. The output lines are always
66 generate an Out[NN] prompt are recorded to the logfile, right after
57 prepended with a '#[Out]# ' marker, so that the log remains valid
67 their corresponding input line. The output lines are always
58 Python code.
68 prepended with a '#[Out]# ' marker, so that the log remains valid
69 Python code.
59
70
60 Since this marker is always the same, filtering only the output from
71 Since this marker is always the same, filtering only the output from
61 a log is very easy, using for example a simple awk call::
72 a log is very easy, using for example a simple awk call::
62
73
63 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
74 awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py
64
75
65 -r: log 'raw' input. Normally, IPython's logs contain the processed
76 -r
66 input, so that user lines are logged in their final form, converted
77 log 'raw' input. Normally, IPython's logs contain the processed
67 into valid Python. For example, %Exit is logged as
78 input, so that user lines are logged in their final form, converted
68 _ip.magic("Exit"). If the -r flag is given, all input is logged
79 into valid Python. For example, %Exit is logged as
69 exactly as typed, with no transformations applied.
80 _ip.magic("Exit"). If the -r flag is given, all input is logged
70
81 exactly as typed, with no transformations applied.
71 -t: put timestamps before each input line logged (these are put in
82
72 comments)."""
83 -t
84 put timestamps before each input line logged (these are put in
85 comments).
86 """
73
87
74 opts,par = self.parse_options(parameter_s,'ort')
88 opts,par = self.parse_options(parameter_s,'ort')
75 log_output = 'o' in opts
89 log_output = 'o' in opts
@@ -354,10 +354,10 class NamespaceMagics(Magics):
354 - For {},[],(): their length.
354 - For {},[],(): their length.
355
355
356 - For numpy arrays, a summary with shape, number of
356 - For numpy arrays, a summary with shape, number of
357 elements, typecode and size in memory.
357 elements, typecode and size in memory.
358
358
359 - Everything else: a string representation, snipping their middle if
359 - Everything else: a string representation, snipping their middle if
360 too long.
360 too long.
361
361
362 Examples
362 Examples
363 --------
363 --------
@@ -156,8 +156,8 def getsource(obj,is_binary=False):
156 Optional inputs:
156 Optional inputs:
157
157
158 - is_binary: whether the object is known to come from a binary source.
158 - is_binary: whether the object is known to come from a binary source.
159 This implementation will skip returning any output for binary objects, but
159 This implementation will skip returning any output for binary objects, but
160 custom extractors may know how to meaningfully process them."""
160 custom extractors may know how to meaningfully process them."""
161
161
162 if is_binary:
162 if is_binary:
163 return None
163 return None
@@ -545,7 +545,7 class Inspector:
545 - formatter: special formatter for docstrings (see pdoc)
545 - formatter: special formatter for docstrings (see pdoc)
546
546
547 - info: a structure with some information fields which may have been
547 - info: a structure with some information fields which may have been
548 precomputed already.
548 precomputed already.
549
549
550 - detail_level: if set to 1, more information is given.
550 - detail_level: if set to 1, more information is given.
551 """
551 """
@@ -609,7 +609,7 class Inspector:
609 - formatter: special formatter for docstrings (see pdoc)
609 - formatter: special formatter for docstrings (see pdoc)
610
610
611 - info: a structure with some information fields which may have been
611 - info: a structure with some information fields which may have been
612 precomputed already.
612 precomputed already.
613
613
614 - detail_level: if set to 1, more information is given.
614 - detail_level: if set to 1, more information is given.
615 """
615 """
@@ -829,8 +829,8 class Inspector:
829 Arguments:
829 Arguments:
830
830
831 - pattern: string containing shell-like wildcards to use in namespace
831 - pattern: string containing shell-like wildcards to use in namespace
832 searches and optionally a type specification to narrow the search to
832 searches and optionally a type specification to narrow the search to
833 objects of that type.
833 objects of that type.
834
834
835 - ns_table: dict of name->namespaces for search.
835 - ns_table: dict of name->namespaces for search.
836
836
@@ -841,7 +841,7 class Inspector:
841 - ignore_case(False): make the search case-insensitive.
841 - ignore_case(False): make the search case-insensitive.
842
842
843 - show_all(False): show all names, including those starting with
843 - show_all(False): show all names, including those starting with
844 underscores.
844 underscores.
845 """
845 """
846 #print 'ps pattern:<%r>' % pattern # dbg
846 #print 'ps pattern:<%r>' % pattern # dbg
847
847
@@ -325,9 +325,11 def snip_print(str,width = 75,print_full = 0,header = ''):
325 """Print a string snipping the midsection to fit in width.
325 """Print a string snipping the midsection to fit in width.
326
326
327 print_full: mode control:
327 print_full: mode control:
328
328 - 0: only snip long strings
329 - 0: only snip long strings
329 - 1: send to page() directly.
330 - 1: send to page() directly.
330 - 2: snip long strings and ask for full length viewing with page()
331 - 2: snip long strings and ask for full length viewing with page()
332
331 Return 1 if snipping was necessary, 0 otherwise."""
333 Return 1 if snipping was necessary, 0 otherwise."""
332
334
333 if print_full == 1:
335 if print_full == 1:
@@ -8,7 +8,8 ColorTB class is a solution to that problem. It colors the different parts of a
8 traceback in a manner similar to what you would expect from a syntax-highlighting
8 traceback in a manner similar to what you would expect from a syntax-highlighting
9 text editor.
9 text editor.
10
10
11 Installation instructions for ColorTB:
11 Installation instructions for ColorTB::
12
12 import sys,ultratb
13 import sys,ultratb
13 sys.excepthook = ultratb.ColorTB()
14 sys.excepthook = ultratb.ColorTB()
14
15
@@ -21,7 +22,7 but kind of neat, and maybe useful for long-running programs that you believe
21 are bug-free. If a crash *does* occur in that type of program you want details.
22 are bug-free. If a crash *does* occur in that type of program you want details.
22 Give it a shot--you'll love it or you'll hate it.
23 Give it a shot--you'll love it or you'll hate it.
23
24
24 Note:
25 .. note::
25
26
26 The Verbose mode prints the variables currently visible where the exception
27 The Verbose mode prints the variables currently visible where the exception
27 happened (shortening their strings if too long). This can potentially be
28 happened (shortening their strings if too long). This can potentially be
@@ -36,25 +37,28 Note:
36 Verbose).
37 Verbose).
37
38
38
39
39 Installation instructions for ColorTB:
40 Installation instructions for ColorTB::
41
40 import sys,ultratb
42 import sys,ultratb
41 sys.excepthook = ultratb.VerboseTB()
43 sys.excepthook = ultratb.VerboseTB()
42
44
43 Note: Much of the code in this module was lifted verbatim from the standard
45 Note: Much of the code in this module was lifted verbatim from the standard
44 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
46 library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'.
45
47
46 * Color schemes
48 Color schemes
49 -------------
50
47 The colors are defined in the class TBTools through the use of the
51 The colors are defined in the class TBTools through the use of the
48 ColorSchemeTable class. Currently the following exist:
52 ColorSchemeTable class. Currently the following exist:
49
53
50 - NoColor: allows all of this module to be used in any terminal (the color
54 - NoColor: allows all of this module to be used in any terminal (the color
51 escapes are just dummy blank strings).
55 escapes are just dummy blank strings).
52
56
53 - Linux: is meant to look good in a terminal like the Linux console (black
57 - Linux: is meant to look good in a terminal like the Linux console (black
54 or very dark background).
58 or very dark background).
55
59
56 - LightBG: similar to Linux but swaps dark/light colors to be more readable
60 - LightBG: similar to Linux but swaps dark/light colors to be more readable
57 in light background terminals.
61 in light background terminals.
58
62
59 You can implement other color schemes easily, the syntax is fairly
63 You can implement other color schemes easily, the syntax is fairly
60 self-explanatory. Please send back new schemes you develop to the author for
64 self-explanatory. Please send back new schemes you develop to the author for
@@ -359,8 +363,8 class TBTools(object):
359 Valid values are:
363 Valid values are:
360
364
361 - None: the default, which means that IPython will dynamically resolve
365 - None: the default, which means that IPython will dynamically resolve
362 to io.stdout. This ensures compatibility with most tools, including
366 to io.stdout. This ensures compatibility with most tools, including
363 Windows (where plain stdout doesn't recognize ANSI escapes).
367 Windows (where plain stdout doesn't recognize ANSI escapes).
364
368
365 - Any object with 'write' and 'flush' attributes.
369 - Any object with 'write' and 'flush' attributes.
366 """
370 """
@@ -974,9 +978,9 class VerboseTB(TBTools):
974 Keywords:
978 Keywords:
975
979
976 - force(False): by default, this routine checks the instance call_pdb
980 - force(False): by default, this routine checks the instance call_pdb
977 flag and does not actually invoke the debugger if the flag is false.
981 flag and does not actually invoke the debugger if the flag is false.
978 The 'force' option forces the debugger to activate even if the flag
982 The 'force' option forces the debugger to activate even if the flag
979 is false.
983 is false.
980
984
981 If the call_pdb flag is set, the pdb interactive debugger is
985 If the call_pdb flag is set, the pdb interactive debugger is
982 invoked. In all cases, the self.tb reference to the current traceback
986 invoked. In all cases, the self.tb reference to the current traceback
@@ -14,14 +14,14 The classes are (see their docstrings for further details):
14 - Demo: pure python demos
14 - Demo: pure python demos
15
15
16 - IPythonDemo: demos with input to be processed by IPython as if it had been
16 - IPythonDemo: demos with input to be processed by IPython as if it had been
17 typed interactively (so magics work, as well as any other special syntax you
17 typed interactively (so magics work, as well as any other special syntax you
18 may have added via input prefilters).
18 may have added via input prefilters).
19
19
20 - LineDemo: single-line version of the Demo class. These demos are executed
20 - LineDemo: single-line version of the Demo class. These demos are executed
21 one line at a time, and require no markup.
21 one line at a time, and require no markup.
22
22
23 - IPythonLineDemo: IPython version of the LineDemo class (the demo is
23 - IPythonLineDemo: IPython version of the LineDemo class (the demo is
24 executed a line at a time, but processed via IPython).
24 executed a line at a time, but processed via IPython).
25
25
26 - ClearMixin: mixin to make Demo classes with less visual clutter. It
26 - ClearMixin: mixin to make Demo classes with less visual clutter. It
27 declares an empty marquee and a pre_cmd that clears the screen before each
27 declares an empty marquee and a pre_cmd that clears the screen before each
@@ -214,18 +214,18 class Demo(object):
214 Optional inputs:
214 Optional inputs:
215
215
216 - title: a string to use as the demo name. Of most use when the demo
216 - title: a string to use as the demo name. Of most use when the demo
217 you are making comes from an object that has no filename, or if you
217 you are making comes from an object that has no filename, or if you
218 want an alternate denotation distinct from the filename.
218 want an alternate denotation distinct from the filename.
219
219
220 - arg_str(''): a string of arguments, internally converted to a list
220 - arg_str(''): a string of arguments, internally converted to a list
221 just like sys.argv, so the demo script can see a similar
221 just like sys.argv, so the demo script can see a similar
222 environment.
222 environment.
223
223
224 - auto_all(None): global flag to run all blocks automatically without
224 - auto_all(None): global flag to run all blocks automatically without
225 confirmation. This attribute overrides the block-level tags and
225 confirmation. This attribute overrides the block-level tags and
226 applies to the whole demo. It is an attribute of the object, and
226 applies to the whole demo. It is an attribute of the object, and
227 can be changed at runtime simply by reassigning it to a boolean
227 can be changed at runtime simply by reassigning it to a boolean
228 value.
228 value.
229 """
229 """
230 if hasattr(src, "read"):
230 if hasattr(src, "read"):
231 # It seems to be a file or a file-like object
231 # It seems to be a file or a file-like object
@@ -93,9 +93,9 class InteractiveRunner(object):
93 - program: command to execute the given program.
93 - program: command to execute the given program.
94
94
95 - prompts: a list of patterns to match as valid prompts, in the
95 - prompts: a list of patterns to match as valid prompts, in the
96 format used by pexpect. This basically means that it can be either
96 format used by pexpect. This basically means that it can be either
97 a string (to be compiled as a regular expression) or a list of such
97 a string (to be compiled as a regular expression) or a list of such
98 (it must be a true list, as pexpect does type checks).
98 (it must be a true list, as pexpect does type checks).
99
99
100 If more than one prompt is given, the first is treated as the main
100 If more than one prompt is given, the first is treated as the main
101 program prompt and the others as 'continuation' prompts, like
101 program prompt and the others as 'continuation' prompts, like
@@ -107,19 +107,19 class InteractiveRunner(object):
107 Optional inputs:
107 Optional inputs:
108
108
109 - args(None): optional list of strings to pass as arguments to the
109 - args(None): optional list of strings to pass as arguments to the
110 child program.
110 child program.
111
111
112 - out(sys.stdout): if given, an output stream to be used when writing
112 - out(sys.stdout): if given, an output stream to be used when writing
113 output. The only requirement is that it must have a .write() method.
113 output. The only requirement is that it must have a .write() method.
114
114
115 Public members not parameterized in the constructor:
115 Public members not parameterized in the constructor:
116
116
117 - delaybeforesend(0): Newer versions of pexpect have a delay before
117 - delaybeforesend(0): Newer versions of pexpect have a delay before
118 sending each new input. For our purposes here, it's typically best
118 sending each new input. For our purposes here, it's typically best
119 to just set this to zero, but if you encounter reliability problems
119 to just set this to zero, but if you encounter reliability problems
120 or want an interactive run to pause briefly at each prompt, just
120 or want an interactive run to pause briefly at each prompt, just
121 increase this value (it is measured in seconds). Note that this
121 increase this value (it is measured in seconds). Note that this
122 variable is not honored at all by older versions of pexpect.
122 variable is not honored at all by older versions of pexpect.
123 """
123 """
124
124
125 self.program = program
125 self.program = program
@@ -154,7 +154,7 class InteractiveRunner(object):
154
154
155 Inputs:
155 Inputs:
156
156
157 -fname: name of the file to execute.
157 - fname: name of the file to execute.
158
158
159 See the run_source docstring for the meaning of the optional
159 See the run_source docstring for the meaning of the optional
160 arguments."""
160 arguments."""
@@ -173,15 +173,15 class InteractiveRunner(object):
173 Inputs:
173 Inputs:
174
174
175 - source: a string of code to be executed, or an open file object we
175 - source: a string of code to be executed, or an open file object we
176 can iterate over.
176 can iterate over.
177
177
178 Optional inputs:
178 Optional inputs:
179
179
180 - interact(False): if true, start to interact with the running
180 - interact(False): if true, start to interact with the running
181 program at the end of the script. Otherwise, just exit.
181 program at the end of the script. Otherwise, just exit.
182
182
183 - get_output(False): if true, capture the output of the child process
183 - get_output(False): if true, capture the output of the child process
184 (filtering the input commands out) and return it as a string.
184 (filtering the input commands out) and return it as a string.
185
185
186 Returns:
186 Returns:
187 A string containing the process output, but only if requested.
187 A string containing the process output, but only if requested.
@@ -19,7 +19,8 def cell_preprocessor(function):
19 Wrap a function to be executed on all cells of a notebook
19 Wrap a function to be executed on all cells of a notebook
20
20
21 Wrapped Parameters
21 Wrapped Parameters
22 ----------
22 ------------------
23
23 cell : NotebookNode cell
24 cell : NotebookNode cell
24 Notebook cell being processed
25 Notebook cell being processed
25 resources : dictionary
26 resources : dictionary
@@ -44,8 +44,8 class AvoidUNCPath(object):
44 change and None otherwise, so that users can apply the necessary adjustment
44 change and None otherwise, so that users can apply the necessary adjustment
45 to their system calls in the event of a change.
45 to their system calls in the event of a change.
46
46
47 Example
47 Examples
48 -------
48 --------
49 ::
49 ::
50 cmd = 'dir'
50 cmd = 'dir'
51 with AvoidUNCPath() as path:
51 with AvoidUNCPath() as path:
@@ -161,8 +161,8 class AvoidUNCPath(object):
161 change and None otherwise, so that users can apply the necessary adjustment
161 change and None otherwise, so that users can apply the necessary adjustment
162 to their system calls in the event of a change.
162 to their system calls in the event of a change.
163
163
164 Example
164 Examples
165 -------
165 --------
166 ::
166 ::
167 cmd = 'dir'
167 cmd = 'dir'
168 with AvoidUNCPath() as path:
168 with AvoidUNCPath() as path:
@@ -69,12 +69,12 class CapturedIO(object):
69
69
70 Each instance `c` has three attributes:
70 Each instance `c` has three attributes:
71
71
72 c.stdout : standard output as a string
72 - ``c.stdout`` : standard output as a string
73 c.stderr : standard error as a string
73 - ``c.stderr`` : standard error as a string
74 c.outputs: a list of rich display outputs
74 - ``c.outputs``: a list of rich display outputs
75
75
76 Additionally, there's a `c.show()` method which will print all of the
76 Additionally, there's a ``c.show()`` method which will print all of the
77 above in the same order, and can be invoked simply via `c()`.
77 above in the same order, and can be invoked simply via ``c()``.
78 """
78 """
79
79
80 def __init__(self, stdout, stderr, outputs=None):
80 def __init__(self, stdout, stderr, outputs=None):
@@ -105,8 +105,8 class CapturedIO(object):
105 def outputs(self):
105 def outputs(self):
106 """A list of the captured rich display outputs, if any.
106 """A list of the captured rich display outputs, if any.
107
107
108 If you have a CapturedIO object `c`, these can be displayed in IPython