From 43ed80e5b3da982e73d2f5285238e558967f78ce 2013-09-17 00:49:50 From: Thomas Kluyver Date: 2013-09-17 00:49:50 Subject: [PATCH] Improvements to docs formatting. --- diff --git a/IPython/core/completer.py b/IPython/core/completer.py index 693390a..642bdae 100644 --- a/IPython/core/completer.py +++ b/IPython/core/completer.py @@ -24,26 +24,26 @@ Tip: to use the tab key as the completion key, call Notes: - Exceptions raised by the completer function are *ignored* (and -generally cause the completion to fail). This is a feature -- since -readline sets the tty device in raw (or cbreak) mode, printing a -traceback wouldn't work well without some complicated hoopla to save, -reset and restore the tty state. + generally cause the completion to fail). This is a feature -- since + readline sets the tty device in raw (or cbreak) mode, printing a + traceback wouldn't work well without some complicated hoopla to save, + reset and restore the tty state. - The evaluation of the NAME.NAME... form may cause arbitrary -application defined code to be executed if an object with a -__getattr__ hook is found. Since it is the responsibility of the -application (or the user) to enable this feature, I consider this an -acceptable risk. More complicated expressions (e.g. function calls or -indexing operations) are *not* evaluated. + application defined code to be executed if an object with a + ``__getattr__`` hook is found. Since it is the responsibility of the + application (or the user) to enable this feature, I consider this an + acceptable risk. More complicated expressions (e.g. function calls or + indexing operations) are *not* evaluated. - GNU readline is also used by the built-in functions input() and -raw_input(), and thus these also benefit/suffer from the completer -features. Clearly an interactive application can benefit by -specifying its own completer function and using raw_input() for all -its input. + raw_input(), and thus these also benefit/suffer from the completer + features. Clearly an interactive application can benefit by + specifying its own completer function and using raw_input() for all + its input. - When the original stdin is not a tty device, GNU readline is never -used, and this module (and the readline module) are silently inactive. + used, and this module (and the readline module) are silently inactive. """ #***************************************************************************** @@ -441,17 +441,17 @@ class IPCompleter(Completer): Inputs: - shell: a pointer to the ipython shell itself. This is needed - because this completer knows about magic functions, and those can - only be accessed via the ipython instance. + because this completer knows about magic functions, and those can + only be accessed via the ipython instance. - namespace: an optional dict where completions are performed. - global_namespace: secondary optional dict for completions, to - handle cases (such as IPython embedded inside functions) where - both Python scopes are visible. + handle cases (such as IPython embedded inside functions) where + both Python scopes are visible. - If alias_table is supplied, it should be a dictionary of aliases - to complete. + to complete. use_readline : bool, optional If true, use the readline library. This completer can still function diff --git a/IPython/core/debugger.py b/IPython/core/debugger.py index e34a781..9472ec3 100644 --- a/IPython/core/debugger.py +++ b/IPython/core/debugger.py @@ -96,19 +96,24 @@ class Tracer(object): def __init__(self,colors=None): """Create a local debugger instance. - :Parameters: + Parameters + ---------- - - `colors` (None): a string containing the name of the color scheme to - use, it must be one of IPython's valid color schemes. If not given, the - function will default to the current IPython scheme when running inside - IPython, and to 'NoColor' otherwise. + colors : str, optional + The name of the color scheme to use, it must be one of IPython's + valid color schemes. If not given, the function will default to + the current IPython scheme when running inside IPython, and to + 'NoColor' otherwise. - Usage example: + Examples + -------- + :: - from IPython.core.debugger import Tracer; debug_here = Tracer() + from IPython.core.debugger import Tracer; debug_here = Tracer() - ... later in your code - debug_here() # -> will open up the debugger at that point. + Later in your code:: + + debug_here() # -> will open up the debugger at that point. Once the debugger activates, you can use all of its regular commands to step through code, set breakpoints, etc. See the pdb documentation diff --git a/IPython/core/interactiveshell.py b/IPython/core/interactiveshell.py index 9aea028..6ca2eb5 100644 --- a/IPython/core/interactiveshell.py +++ b/IPython/core/interactiveshell.py @@ -907,9 +907,9 @@ class InteractiveShell(SingletonConfigurable): Keywords: - force(False): by default, this routine checks the instance call_pdb - flag and does not actually invoke the debugger if the flag is false. - The 'force' option forces the debugger to activate even if the flag - is false. + flag and does not actually invoke the debugger if the flag is false. + The 'force' option forces the debugger to activate even if the flag + is false. """ if not (force or self.call_pdb): @@ -2978,7 +2978,7 @@ class InteractiveShell(SingletonConfigurable): Optional inputs: - data(None): if data is given, it gets written out to the temp file - immediately, and the file is closed again.""" + immediately, and the file is closed again.""" filename = tempfile.mktemp('.py', prefix) self.tempfiles.append(filename) @@ -3021,13 +3021,14 @@ class InteractiveShell(SingletonConfigurable): Optional Parameters: - raw(False): by default, the processed input is used. If this is - true, the raw input history is used instead. + true, the raw input history is used instead. Note that slices can be called with two notations: N:M -> standard python form, means including items N...(M-1). - N-M -> include items N..M (closed endpoint).""" + N-M -> include items N..M (closed endpoint). + """ lines = self.history_manager.get_range_by_str(range_str, raw=raw) return "\n".join(x for _, _, x in lines) diff --git a/IPython/core/logger.py b/IPython/core/logger.py index d6eff7a..1c21b21 100644 --- a/IPython/core/logger.py +++ b/IPython/core/logger.py @@ -171,11 +171,11 @@ which already exists. But you must first start the logging process with Inputs: - line_mod: possibly modified input, such as the transformations made - by input prefilters or input handlers of various kinds. This should - always be valid Python. + by input prefilters or input handlers of various kinds. This should + always be valid Python. - - line_ori: unmodified input line from the user. This is not - necessarily valid Python. + - line_ori: unmodified input line from the user. This is not + necessarily valid Python. """ # Write the log line, but decide which one according to the diff --git a/IPython/core/magic.py b/IPython/core/magic.py index b21a4fa..65a04fe 100644 --- a/IPython/core/magic.py +++ b/IPython/core/magic.py @@ -489,11 +489,11 @@ class Magics(object): MUST: - Use the method decorators `@line_magic` and `@cell_magic` to decorate - individual methods as magic functions, AND + individual methods as magic functions, AND - Use the class decorator `@magics_class` to ensure that the magic - methods are properly registered at the instance level upon instance - initialization. + methods are properly registered at the instance level upon instance + initialization. See :mod:`magic_functions` for examples of actual implementation classes. """ diff --git a/IPython/core/magics/execution.py b/IPython/core/magics/execution.py index e01c978..640c29f 100644 --- a/IPython/core/magics/execution.py +++ b/IPython/core/magics/execution.py @@ -102,75 +102,84 @@ python-profiler package from non-free.""") Options: - -l : you can place restrictions on what or how much of the - profile gets printed. The limit value can be: - - * A string: only information for function names containing this string - is printed. - - * An integer: only these many lines are printed. - - * A float (between 0 and 1): this fraction of the report is printed - (for example, use a limit of 0.4 to see the topmost 40% only). - - You can combine several limits with repeated use of the option. For - example, '-l __init__ -l 5' will print only the topmost 5 lines of - information about class constructors. - - -r: return the pstats.Stats object generated by the profiling. This - object has all the information about the profile in it, and you can - later use it for further analysis or in other functions. - - -s : sort profile by given key. You can provide more than one key - by using the option several times: '-s key1 -s key2 -s key3...'. The - default sorting key is 'time'. - - The following is copied verbatim from the profile documentation - referenced below: - - When more than one key is provided, additional keys are used as - secondary criteria when the there is equality in all keys selected - before them. - - Abbreviations can be used for any key names, as long as the - abbreviation is unambiguous. The following are the keys currently - defined: - - Valid Arg Meaning - "calls" call count - "cumulative" cumulative time - "file" file name - "module" file name - "pcalls" primitive call count - "line" line number - "name" function name - "nfl" name/file/line - "stdname" standard name - "time" internal time - - Note that all sorts on statistics are in descending order (placing - most time consuming items first), where as name, file, and line number - searches are in ascending order (i.e., alphabetical). The subtle - distinction between "nfl" and "stdname" is that the standard name is a - sort of the name as printed, which means that the embedded line - numbers get compared in an odd way. For example, lines 3, 20, and 40 - would (if the file names were the same) appear in the string order - "20" "3" and "40". In contrast, "nfl" does a numeric compare of the - line numbers. In fact, sort_stats("nfl") is the same as - sort_stats("name", "file", "line"). - - -T : save profile results as shown on screen to a text - file. The profile is still shown on screen. - - -D : save (via dump_stats) profile statistics to given - filename. This data is in a format understood by the pstats module, and - is generated by a call to the dump_stats() method of profile - objects. The profile is still shown on screen. - - -q: suppress output to the pager. Best used with -T and/or -D above. + -l + you can place restrictions on what or how much of the + profile gets printed. The limit value can be: + + * A string: only information for function names containing this string + is printed. + + * An integer: only these many lines are printed. + + * A float (between 0 and 1): this fraction of the report is printed + (for example, use a limit of 0.4 to see the topmost 40% only). + + You can combine several limits with repeated use of the option. For + example, ``-l __init__ -l 5`` will print only the topmost 5 lines of + information about class constructors. + + -r + return the pstats.Stats object generated by the profiling. This + object has all the information about the profile in it, and you can + later use it for further analysis or in other functions. + + -s + sort profile by given key. You can provide more than one key + by using the option several times: '-s key1 -s key2 -s key3...'. The + default sorting key is 'time'. + + The following is copied verbatim from the profile documentation + referenced below: + + When more than one key is provided, additional keys are used as + secondary criteria when the there is equality in all keys selected + before them. + + Abbreviations can be used for any key names, as long as the + abbreviation is unambiguous. The following are the keys currently + defined: + + ============ ===================== + Valid Arg Meaning + ============ ===================== + "calls" call count + "cumulative" cumulative time + "file" file name + "module" file name + "pcalls" primitive call count + "line" line number + "name" function name + "nfl" name/file/line + "stdname" standard name + "time" internal time + ============ ===================== + + Note that all sorts on statistics are in descending order (placing + most time consuming items first), where as name, file, and line number + searches are in ascending order (i.e., alphabetical). The subtle + distinction between "nfl" and "stdname" is that the standard name is a + sort of the name as printed, which means that the embedded line + numbers get compared in an odd way. For example, lines 3, 20, and 40 + would (if the file names were the same) appear in the string order + "20" "3" and "40". In contrast, "nfl" does a numeric compare of the + line numbers. In fact, sort_stats("nfl") is the same as + sort_stats("name", "file", "line"). + + -T + save profile results as shown on screen to a text + file. The profile is still shown on screen. + + -D + save (via dump_stats) profile statistics to given + filename. This data is in a format understood by the pstats module, and + is generated by a call to the dump_stats() method of profile + objects. The profile is still shown on screen. + + -q + suppress output to the pager. Best used with -T and/or -D above. If you want to run complete programs under the profiler's control, use - '%run -p [prof_opts] filename.py [args to program]' where prof_opts + ``%run -p [prof_opts] filename.py [args to program]`` where prof_opts contains profiler specific options as described here. You can read the complete documentation for the profile module with:: @@ -362,7 +371,8 @@ python-profiler package from non-free.""") file_finder=get_py_filename): """Run the named file inside IPython as a program. - Usage: + Usage:: + %run [-n -i -e -G] [( -t [-N] | -d [-b] | -p [profile options] )] ( -m mod | file ) [args] @@ -371,14 +381,13 @@ python-profiler package from non-free.""") the program (put in sys.argv). Then, control returns to IPython's prompt. - This is similar to running at a system prompt:\\ - $ python file args\\ + This is similar to running at a system prompt ``python file args``, but with the advantage of giving you IPython's tracebacks, and of loading all variables into your interactive namespace for further use (unless -p is used, see below). The file is executed in a namespace initially consisting only of - __name__=='__main__' and sys.argv constructed as indicated. It thus + ``__name__=='__main__'`` and sys.argv constructed as indicated. It thus sees its environment as if it were being run as a stand-alone program (except for sharing global objects such as previously imported modules). But after execution, the IPython interactive namespace gets @@ -390,33 +399,37 @@ python-profiler package from non-free.""") '*', '?', '[seq]' and '[!seq]' can be used. Additionally, tilde '~' will be expanded into user's home directory. Unlike real shells, quotation does not suppress expansions. Use - *two* back slashes (e.g., '\\\\*') to suppress expansions. + *two* back slashes (e.g. ``\\\\*``) to suppress expansions. To completely disable these expansions, you can use -G flag. Options: - -n: __name__ is NOT set to '__main__', but to the running file's name - without extension (as python does under import). This allows running - scripts and reloading the definitions in them without calling code - protected by an ' if __name__ == "__main__" ' clause. - - -i: run the file in IPython's namespace instead of an empty one. This - is useful if you are experimenting with code written in a text editor - which depends on variables defined interactively. - - -e: ignore sys.exit() calls or SystemExit exceptions in the script - being run. This is particularly useful if IPython is being used to - run unittests, which always exit with a sys.exit() call. In such - cases you are interested in the output of the test results, not in - seeing a traceback of the unittest module. - - -t: print timing information at the end of the run. IPython will give - you an estimated CPU time consumption for your script, which under - Unix uses the resource module to avoid the wraparound problems of - time.clock(). Under Unix, an estimate of time spent on system tasks - is also given (for Windows platforms this is reported as 0.0). - - If -t is given, an additional -N option can be given, where + -n + __name__ is NOT set to '__main__', but to the running file's name + without extension (as python does under import). This allows running + scripts and reloading the definitions in them without calling code + protected by an ``if __name__ == "__main__"`` clause. + + -i + run the file in IPython's namespace instead of an empty one. This + is useful if you are experimenting with code written in a text editor + which depends on variables defined interactively. + + -e + ignore sys.exit() calls or SystemExit exceptions in the script + being run. This is particularly useful if IPython is being used to + run unittests, which always exit with a sys.exit() call. In such + cases you are interested in the output of the test results, not in + seeing a traceback of the unittest module. + + -t + print timing information at the end of the run. IPython will give + you an estimated CPU time consumption for your script, which under + Unix uses the resource module to avoid the wraparound problems of + time.clock(). Under Unix, an estimate of time spent on system tasks + is also given (for Windows platforms this is reported as 0.0). + + If -t is given, an additional ``-N`` option can be given, where must be an integer indicating how many times you want the script to run. The final timing report will include total and per run results. @@ -424,74 +437,78 @@ python-profiler package from non-free.""") In [1]: run -t uniq_stable - IPython CPU timings (estimated):\\ - User : 0.19597 s.\\ - System: 0.0 s.\\ + IPython CPU timings (estimated): + User : 0.19597 s. + System: 0.0 s. In [2]: run -t -N5 uniq_stable - IPython CPU timings (estimated):\\ - Total runs performed: 5\\ - Times : Total Per run\\ - User : 0.910862 s, 0.1821724 s.\\ + IPython CPU timings (estimated): + Total runs performed: 5 + Times : Total Per run + User : 0.910862 s, 0.1821724 s. System: 0.0 s, 0.0 s. - -d: run your program under the control of pdb, the Python debugger. - This allows you to execute your program step by step, watch variables, - etc. Internally, what IPython does is similar to calling: + -d + run your program under the control of pdb, the Python debugger. + This allows you to execute your program step by step, watch variables, + etc. Internally, what IPython does is similar to calling:: - pdb.run('execfile("YOURFILENAME")') + pdb.run('execfile("YOURFILENAME")') - with a breakpoint set on line 1 of your file. You can change the line - number for this automatic breakpoint to be by using the -bN option - (where N must be an integer). For example:: + with a breakpoint set on line 1 of your file. You can change the line + number for this automatic breakpoint to be by using the -bN option + (where N must be an integer). For example:: - %run -d -b40 myscript + %run -d -b40 myscript - will set the first breakpoint at line 40 in myscript.py. Note that - the first breakpoint must be set on a line which actually does - something (not a comment or docstring) for it to stop execution. + will set the first breakpoint at line 40 in myscript.py. Note that + the first breakpoint must be set on a line which actually does + something (not a comment or docstring) for it to stop execution. - Or you can specify a breakpoint in a different file:: + Or you can specify a breakpoint in a different file:: - %run -d -b myotherfile.py:20 myscript + %run -d -b myotherfile.py:20 myscript - When the pdb debugger starts, you will see a (Pdb) prompt. You must - first enter 'c' (without quotes) to start execution up to the first - breakpoint. + When the pdb debugger starts, you will see a (Pdb) prompt. You must + first enter 'c' (without quotes) to start execution up to the first + breakpoint. - Entering 'help' gives information about the use of the debugger. You - can easily see pdb's full documentation with "import pdb;pdb.help()" - at a prompt. + Entering 'help' gives information about the use of the debugger. You + can easily see pdb's full documentation with "import pdb;pdb.help()" + at a prompt. - -p: run program under the control of the Python profiler module (which - prints a detailed report of execution times, function calls, etc). + -p + run program under the control of the Python profiler module (which + prints a detailed report of execution times, function calls, etc). - You can pass other options after -p which affect the behavior of the - profiler itself. See the docs for %prun for details. + You can pass other options after -p which affect the behavior of the + profiler itself. See the docs for %prun for details. - In this mode, the program's variables do NOT propagate back to the - IPython interactive namespace (because they remain in the namespace - where the profiler executes them). + In this mode, the program's variables do NOT propagate back to the + IPython interactive namespace (because they remain in the namespace + where the profiler executes them). - Internally this triggers a call to %prun, see its documentation for - details on the options available specifically for profiling. + Internally this triggers a call to %prun, see its documentation for + details on the options available specifically for profiling. There is one special usage for which the text above doesn't apply: if the filename ends with .ipy, the file is run as ipython script, just as if the commands were written on IPython prompt. - -m: specify module name to load instead of script path. Similar to - the -m option for the python interpreter. Use this option last if you - want to combine with other %run options. Unlike the python interpreter - only source modules are allowed no .pyc or .pyo files. - For example:: + -m + specify module name to load instead of script path. Similar to + the -m option for the python interpreter. Use this option last if you + want to combine with other %run options. Unlike the python interpreter + only source modules are allowed no .pyc or .pyo files. + For example:: - %run -m example + %run -m example - will run the example module. + will run the example module. - -G: disable shell-like glob expansion of arguments. + -G + disable shell-like glob expansion of arguments. """ diff --git a/IPython/core/magics/logging.py b/IPython/core/magics/logging.py index b1e7b28..3dcb8cb 100644 --- a/IPython/core/magics/logging.py +++ b/IPython/core/magics/logging.py @@ -42,34 +42,48 @@ class LoggingMagics(Magics): history up to that point and then continues logging. %logstart takes a second optional parameter: logging mode. This can be one - of (note that the modes are given unquoted):\\ - append: well, that says it.\\ - backup: rename (if exists) to name~ and start name.\\ - global: single logfile in your home dir, appended to.\\ - over : overwrite existing log.\\ - rotate: create rotating logs name.1~, name.2~, etc. + of (note that the modes are given unquoted): + + append + Keep logging at the end of any existing file. + + backup + Rename any existing file to name~ and start name. + + global + Append to a single logfile in your home directory. + + over + Overwrite any existing log. + + rotate + Create rotating logs: name.1~, name.2~, etc. Options: - -o: log also IPython's output. In this mode, all commands which - generate an Out[NN] prompt are recorded to the logfile, right after - their corresponding input line. The output lines are always - prepended with a '#[Out]# ' marker, so that the log remains valid - Python code. + -o + log also IPython's output. In this mode, all commands which + generate an Out[NN] prompt are recorded to the logfile, right after + their corresponding input line. The output lines are always + prepended with a '#[Out]# ' marker, so that the log remains valid + Python code. Since this marker is always the same, filtering only the output from a log is very easy, using for example a simple awk call:: awk -F'#\\[Out\\]# ' '{if($2) {print $2}}' ipython_log.py - -r: log 'raw' input. Normally, IPython's logs contain the processed - input, so that user lines are logged in their final form, converted - into valid Python. For example, %Exit is logged as - _ip.magic("Exit"). If the -r flag is given, all input is logged - exactly as typed, with no transformations applied. - - -t: put timestamps before each input line logged (these are put in - comments).""" + -r + log 'raw' input. Normally, IPython's logs contain the processed + input, so that user lines are logged in their final form, converted + into valid Python. For example, %Exit is logged as + _ip.magic("Exit"). If the -r flag is given, all input is logged + exactly as typed, with no transformations applied. + + -t + put timestamps before each input line logged (these are put in + comments). + """ opts,par = self.parse_options(parameter_s,'ort') log_output = 'o' in opts diff --git a/IPython/core/magics/namespace.py b/IPython/core/magics/namespace.py index a469479..1d031dc 100644 --- a/IPython/core/magics/namespace.py +++ b/IPython/core/magics/namespace.py @@ -354,10 +354,10 @@ class NamespaceMagics(Magics): - For {},[],(): their length. - For numpy arrays, a summary with shape, number of - elements, typecode and size in memory. + elements, typecode and size in memory. - Everything else: a string representation, snipping their middle if - too long. + too long. Examples -------- diff --git a/IPython/core/oinspect.py b/IPython/core/oinspect.py index 4846861..1dbe761 100644 --- a/IPython/core/oinspect.py +++ b/IPython/core/oinspect.py @@ -156,8 +156,8 @@ def getsource(obj,is_binary=False): Optional inputs: - is_binary: whether the object is known to come from a binary source. - This implementation will skip returning any output for binary objects, but - custom extractors may know how to meaningfully process them.""" + This implementation will skip returning any output for binary objects, but + custom extractors may know how to meaningfully process them.""" if is_binary: return None @@ -545,7 +545,7 @@ class Inspector: - formatter: special formatter for docstrings (see pdoc) - info: a structure with some information fields which may have been - precomputed already. + precomputed already. - detail_level: if set to 1, more information is given. """ @@ -609,7 +609,7 @@ class Inspector: - formatter: special formatter for docstrings (see pdoc) - info: a structure with some information fields which may have been - precomputed already. + precomputed already. - detail_level: if set to 1, more information is given. """ @@ -829,8 +829,8 @@ class Inspector: Arguments: - pattern: string containing shell-like wildcards to use in namespace - searches and optionally a type specification to narrow the search to - objects of that type. + searches and optionally a type specification to narrow the search to + objects of that type. - ns_table: dict of name->namespaces for search. @@ -841,7 +841,7 @@ class Inspector: - ignore_case(False): make the search case-insensitive. - show_all(False): show all names, including those starting with - underscores. + underscores. """ #print 'ps pattern:<%r>' % pattern # dbg diff --git a/IPython/core/page.py b/IPython/core/page.py index a3f7d91..67cde95 100644 --- a/IPython/core/page.py +++ b/IPython/core/page.py @@ -325,9 +325,11 @@ def snip_print(str,width = 75,print_full = 0,header = ''): """Print a string snipping the midsection to fit in width. print_full: mode control: + - 0: only snip long strings - 1: send to page() directly. - 2: snip long strings and ask for full length viewing with page() + Return 1 if snipping was necessary, 0 otherwise.""" if print_full == 1: diff --git a/IPython/core/ultratb.py b/IPython/core/ultratb.py index 4261339..543e725 100644 --- a/IPython/core/ultratb.py +++ b/IPython/core/ultratb.py @@ -8,7 +8,8 @@ ColorTB class is a solution to that problem. It colors the different parts of a traceback in a manner similar to what you would expect from a syntax-highlighting text editor. -Installation instructions for ColorTB: +Installation instructions for ColorTB:: + import sys,ultratb sys.excepthook = ultratb.ColorTB() @@ -21,7 +22,7 @@ but kind of neat, and maybe useful for long-running programs that you believe are bug-free. If a crash *does* occur in that type of program you want details. Give it a shot--you'll love it or you'll hate it. -Note: +.. note:: The Verbose mode prints the variables currently visible where the exception happened (shortening their strings if too long). This can potentially be @@ -36,25 +37,28 @@ Note: Verbose). -Installation instructions for ColorTB: +Installation instructions for ColorTB:: + import sys,ultratb sys.excepthook = ultratb.VerboseTB() Note: Much of the code in this module was lifted verbatim from the standard library module 'traceback.py' and Ka-Ping Yee's 'cgitb.py'. -* Color schemes +Color schemes +------------- + The colors are defined in the class TBTools through the use of the ColorSchemeTable class. Currently the following exist: - NoColor: allows all of this module to be used in any terminal (the color - escapes are just dummy blank strings). + escapes are just dummy blank strings). - Linux: is meant to look good in a terminal like the Linux console (black - or very dark background). + or very dark background). - LightBG: similar to Linux but swaps dark/light colors to be more readable - in light background terminals. + in light background terminals. You can implement other color schemes easily, the syntax is fairly self-explanatory. Please send back new schemes you develop to the author for @@ -359,8 +363,8 @@ class TBTools(object): Valid values are: - None: the default, which means that IPython will dynamically resolve - to io.stdout. This ensures compatibility with most tools, including - Windows (where plain stdout doesn't recognize ANSI escapes). + to io.stdout. This ensures compatibility with most tools, including + Windows (where plain stdout doesn't recognize ANSI escapes). - Any object with 'write' and 'flush' attributes. """ @@ -974,9 +978,9 @@ class VerboseTB(TBTools): Keywords: - force(False): by default, this routine checks the instance call_pdb - flag and does not actually invoke the debugger if the flag is false. - The 'force' option forces the debugger to activate even if the flag - is false. + flag and does not actually invoke the debugger if the flag is false. + The 'force' option forces the debugger to activate even if the flag + is false. If the call_pdb flag is set, the pdb interactive debugger is invoked. In all cases, the self.tb reference to the current traceback diff --git a/IPython/lib/demo.py b/IPython/lib/demo.py index 621e44a..0c1fa8e 100644 --- a/IPython/lib/demo.py +++ b/IPython/lib/demo.py @@ -14,14 +14,14 @@ The classes are (see their docstrings for further details): - Demo: pure python demos - IPythonDemo: demos with input to be processed by IPython as if it had been - typed interactively (so magics work, as well as any other special syntax you - may have added via input prefilters). + typed interactively (so magics work, as well as any other special syntax you + may have added via input prefilters). - LineDemo: single-line version of the Demo class. These demos are executed - one line at a time, and require no markup. + one line at a time, and require no markup. - IPythonLineDemo: IPython version of the LineDemo class (the demo is - executed a line at a time, but processed via IPython). + executed a line at a time, but processed via IPython). - ClearMixin: mixin to make Demo classes with less visual clutter. It declares an empty marquee and a pre_cmd that clears the screen before each @@ -214,18 +214,18 @@ class Demo(object): Optional inputs: - title: a string to use as the demo name. Of most use when the demo - you are making comes from an object that has no filename, or if you - want an alternate denotation distinct from the filename. + you are making comes from an object that has no filename, or if you + want an alternate denotation distinct from the filename. - arg_str(''): a string of arguments, internally converted to a list - just like sys.argv, so the demo script can see a similar - environment. + just like sys.argv, so the demo script can see a similar + environment. - auto_all(None): global flag to run all blocks automatically without - confirmation. This attribute overrides the block-level tags and - applies to the whole demo. It is an attribute of the object, and - can be changed at runtime simply by reassigning it to a boolean - value. + confirmation. This attribute overrides the block-level tags and + applies to the whole demo. It is an attribute of the object, and + can be changed at runtime simply by reassigning it to a boolean + value. """ if hasattr(src, "read"): # It seems to be a file or a file-like object diff --git a/IPython/lib/irunner.py b/IPython/lib/irunner.py index 623cdb4..e8c65f2 100755 --- a/IPython/lib/irunner.py +++ b/IPython/lib/irunner.py @@ -93,9 +93,9 @@ class InteractiveRunner(object): - program: command to execute the given program. - prompts: a list of patterns to match as valid prompts, in the - format used by pexpect. This basically means that it can be either - a string (to be compiled as a regular expression) or a list of such - (it must be a true list, as pexpect does type checks). + format used by pexpect. This basically means that it can be either + a string (to be compiled as a regular expression) or a list of such + (it must be a true list, as pexpect does type checks). If more than one prompt is given, the first is treated as the main program prompt and the others as 'continuation' prompts, like @@ -107,19 +107,19 @@ class InteractiveRunner(object): Optional inputs: - args(None): optional list of strings to pass as arguments to the - child program. + child program. - out(sys.stdout): if given, an output stream to be used when writing - output. The only requirement is that it must have a .write() method. + output. The only requirement is that it must have a .write() method. Public members not parameterized in the constructor: - delaybeforesend(0): Newer versions of pexpect have a delay before - sending each new input. For our purposes here, it's typically best - to just set this to zero, but if you encounter reliability problems - or want an interactive run to pause briefly at each prompt, just - increase this value (it is measured in seconds). Note that this - variable is not honored at all by older versions of pexpect. + sending each new input. For our purposes here, it's typically best + to just set this to zero, but if you encounter reliability problems + or want an interactive run to pause briefly at each prompt, just + increase this value (it is measured in seconds). Note that this + variable is not honored at all by older versions of pexpect. """ self.program = program @@ -154,7 +154,7 @@ class InteractiveRunner(object): Inputs: - -fname: name of the file to execute. + - fname: name of the file to execute. See the run_source docstring for the meaning of the optional arguments.""" @@ -173,15 +173,15 @@ class InteractiveRunner(object): Inputs: - source: a string of code to be executed, or an open file object we - can iterate over. + can iterate over. Optional inputs: - interact(False): if true, start to interact with the running - program at the end of the script. Otherwise, just exit. + program at the end of the script. Otherwise, just exit. - get_output(False): if true, capture the output of the child process - (filtering the input commands out) and return it as a string. + (filtering the input commands out) and return it as a string. Returns: A string containing the process output, but only if requested. diff --git a/IPython/nbconvert/preprocessors/coalescestreams.py b/IPython/nbconvert/preprocessors/coalescestreams.py index f00c3cf..873c559 100644 --- a/IPython/nbconvert/preprocessors/coalescestreams.py +++ b/IPython/nbconvert/preprocessors/coalescestreams.py @@ -19,7 +19,8 @@ def cell_preprocessor(function): Wrap a function to be executed on all cells of a notebook Wrapped Parameters - ---------- + ------------------ + cell : NotebookNode cell Notebook cell being processed resources : dictionary diff --git a/IPython/utils/_process_win32.py b/IPython/utils/_process_win32.py index fe99a83..702a173 100644 --- a/IPython/utils/_process_win32.py +++ b/IPython/utils/_process_win32.py @@ -44,8 +44,8 @@ class AvoidUNCPath(object): change and None otherwise, so that users can apply the necessary adjustment to their system calls in the event of a change. - Example - ------- + Examples + -------- :: cmd = 'dir' with AvoidUNCPath() as path: diff --git a/IPython/utils/_process_win32_controller.py b/IPython/utils/_process_win32_controller.py index 8bd01b3..84021e8 100644 --- a/IPython/utils/_process_win32_controller.py +++ b/IPython/utils/_process_win32_controller.py @@ -161,8 +161,8 @@ class AvoidUNCPath(object): change and None otherwise, so that users can apply the necessary adjustment to their system calls in the event of a change. - Example - ------- + Examples + -------- :: cmd = 'dir' with AvoidUNCPath() as path: diff --git a/IPython/utils/capture.py b/IPython/utils/capture.py index 2f1baf9..a663f3e 100644 --- a/IPython/utils/capture.py +++ b/IPython/utils/capture.py @@ -69,12 +69,12 @@ class CapturedIO(object): Each instance `c` has three attributes: - c.stdout : standard output as a string - c.stderr : standard error as a string - c.outputs: a list of rich display outputs + - ``c.stdout`` : standard output as a string + - ``c.stderr`` : standard error as a string + - ``c.outputs``: a list of rich display outputs - Additionally, there's a `c.show()` method which will print all of the - above in the same order, and can be invoked simply via `c()`. + Additionally, there's a ``c.show()`` method which will print all of the + above in the same order, and can be invoked simply via ``c()``. """ def __init__(self, stdout, stderr, outputs=None): @@ -105,8 +105,8 @@ class CapturedIO(object): def outputs(self): """A list of the captured rich display outputs, if any. - If you have a CapturedIO object `c`, these can be displayed in IPython - using: + If you have a CapturedIO object ``c``, these can be displayed in IPython + using:: from IPython.display import display for o in c.outputs: diff --git a/IPython/utils/contexts.py b/IPython/utils/contexts.py index b51fbfc..cb4b084 100644 --- a/IPython/utils/contexts.py +++ b/IPython/utils/contexts.py @@ -27,8 +27,8 @@ class preserve_keys(object): which did not exist when entering the context manager will be deleted. - Example - ------- + Examples + -------- >>> d = {'a': 1, 'b': 2, 'c': 3} >>> with preserve_keys(d, 'b', 'c', 'd'): diff --git a/IPython/utils/sysinfo.py b/IPython/utils/sysinfo.py index 98723df..69abde2 100644 --- a/IPython/utils/sysinfo.py +++ b/IPython/utils/sysinfo.py @@ -98,18 +98,20 @@ def pkg_info(pkg_path): def sys_info(): """Return useful information about IPython and the system, as a string. - Example - ------- - In [2]: print sys_info() - {'commit_hash': '144fdae', # random - 'commit_source': 'repository', - 'ipython_path': '/home/fperez/usr/lib/python2.6/site-packages/IPython', - 'ipython_version': '0.11.dev', - 'os_name': 'posix', - 'platform': 'Linux-2.6.35-22-generic-i686-with-Ubuntu-10.10-maverick', - 'sys_executable': '/usr/bin/python', - 'sys_platform': 'linux2', - 'sys_version': '2.6.6 (r266:84292, Sep 15 2010, 15:52:39) \\n[GCC 4.4.5]'} + Examples + -------- + :: + + In [2]: print sys_info() + {'commit_hash': '144fdae', # random + 'commit_source': 'repository', + 'ipython_path': '/home/fperez/usr/lib/python2.6/site-packages/IPython', + 'ipython_version': '0.11.dev', + 'os_name': 'posix', + 'platform': 'Linux-2.6.35-22-generic-i686-with-Ubuntu-10.10-maverick', + 'sys_executable': '/usr/bin/python', + 'sys_platform': 'linux2', + 'sys_version': '2.6.6 (r266:84292, Sep 15 2010, 15:52:39) \\n[GCC 4.4.5]'} """ p = os.path path = p.dirname(p.abspath(p.join(__file__, '..')))