From d81b8d54d2b8913efddd00222972cda3f58e3277 2010-01-10 16:46:08 From: Fernando Perez Date: 2010-01-10 16:46:08 Subject: [PATCH] Unify command-line usage information in one place. Fixes: https://bugs.launchpad.net/ipython/+bug/505047 --- diff --git a/IPython/core/application.py b/IPython/core/application.py index 017366c..465c2c4 100755 --- a/IPython/core/application.py +++ b/IPython/core/application.py @@ -51,26 +51,41 @@ class ApplicationError(Exception): app_cl_args = ( - (('--ipython-dir', ), dict( - dest='Global.ipython_dir',type=unicode, - help='Set to override default location of Global.ipython_dir.', - default=NoConfigDefault, - metavar='Global.ipython_dir') ), - (('-p', '--profile',), dict( - dest='Global.profile',type=unicode, - help='The string name of the ipython profile to be used.', - default=NoConfigDefault, - metavar='Global.profile') ), - (('--log-level',), dict( - dest="Global.log_level",type=int, - help='Set the log level (0,10,20,30,40,50). Default is 30.', - default=NoConfigDefault, - metavar='Global.log_level')), - (('--config-file',), dict( - dest='Global.config_file',type=unicode, - help='Set the config file name to override default.', - default=NoConfigDefault, - metavar='Global.config_file')), + (('--ipython-dir', ), dict( + dest='Global.ipython_dir',type=unicode, + help= + """Set to override default location of the IPython directory + IPYTHON_DIR, stored as Global.ipython_dir. This can also be specified + through the environment variable IPYTHON_DIR.""", + default=NoConfigDefault, + metavar='Global.ipython_dir') ), + (('-p', '--profile',), dict( + dest='Global.profile',type=unicode, + help= + """The string name of the ipython profile to be used. Assume that your + config file is ipython_config-.py (looks in current dir first, + then in IPYTHON_DIR). This is a quick way to keep and load multiple + config files for different tasks, especially if include your basic one + in your more specialized ones. You can keep a basic + IPYTHON_DIR/ipython_config.py file and then have other 'profiles' which + include this one and load extra things for particular tasks.""", + default=NoConfigDefault, + metavar='Global.profile') ), + (('--log-level',), dict( + dest="Global.log_level",type=int, + help='Set the log level (0,10,20,30,40,50). Default is 30.', + default=NoConfigDefault, + metavar='Global.log_level')), + (('--config-file',), dict( + dest='Global.config_file',type=unicode, + help= + """Set the config file name to override default. Normally IPython + loads ipython_config.py (from current directory) or + IPYTHON_DIR/ipython_config.py. If the loading of your config file + fails, IPython starts with a bare bones configuration (no modules + loaded at all).""", + default=NoConfigDefault, + metavar='Global.config_file')), ) class Application(object): @@ -78,7 +93,8 @@ class Application(object): name = u'ipython' description = 'IPython: an enhanced interactive Python shell.' - + #: usage message printed by argparse. If None, auto-generate + usage = None config_file_name = u'ipython_config.py' # Track the default and actual separately because some messages are # only printed if we aren't using the default. @@ -199,7 +215,9 @@ class Application(object): """Create and return a command line config loader.""" return ArgParseConfigLoader(self.argv, self.cl_arguments, description=self.description, - version=release.version) + version=release.version, + usage=self.usage, + ) def pre_load_command_line_config(self): """Do actions just before loading the command line config.""" diff --git a/IPython/core/ipapp.py b/IPython/core/ipapp.py index ca8606d..71ef0fe 100755 --- a/IPython/core/ipapp.py +++ b/IPython/core/ipapp.py @@ -4,17 +4,15 @@ The :class:`~IPython.core.application.Application` object for the command line :command:`ipython` program. -Authors: +Authors +------- * Brian Granger * Fernando Perez - -Notes ------ """ #----------------------------------------------------------------------------- -# Copyright (C) 2008-2009 The IPython Development Team +# Copyright (C) 2008-2010 The IPython Development Team # # Distributed under the terms of the BSD License. The full license is in # the file COPYING, distributed as part of this software. @@ -23,6 +21,7 @@ Notes #----------------------------------------------------------------------------- # Imports #----------------------------------------------------------------------------- +from __future__ import absolute_import import logging import os @@ -41,62 +40,78 @@ from IPython.config.loader import ( ) from IPython.lib import inputhook from IPython.utils.genutils import filefind, get_ipython_dir +from . import usage #----------------------------------------------------------------------------- -# Utilities and helpers +# Globals, utilities and helpers #----------------------------------------------------------------------------- -ipython_desc = """ -A Python shell with automatic history (input and output), dynamic object -introspection, easier configuration, command completion, access to the system -shell and more. -""" - -#----------------------------------------------------------------------------- -# Main classes and functions -#----------------------------------------------------------------------------- +default_config_file_name = u'ipython_config.py' cl_args = ( (('--autocall',), dict( type=int, dest='InteractiveShell.autocall', default=NoConfigDefault, - help='Set the autocall value (0,1,2).', + help= + """Make IPython automatically call any callable object even if you + didn't type explicit parentheses. For example, 'str 43' becomes + 'str(43)' automatically. The value can be '0' to disable the feature, + '1' for 'smart' autocall, where it is not applied if there are no more + arguments on the line, and '2' for 'full' autocall, where all callable + objects are automatically called (even if no arguments are present). + The default is '1'.""", metavar='InteractiveShell.autocall') ), (('--autoindent',), dict( - action='store_true', dest='InteractiveShell.autoindent', default=NoConfigDefault, + action='store_true', dest='InteractiveShell.autoindent', + default=NoConfigDefault, help='Turn on autoindenting.') ), (('--no-autoindent',), dict( - action='store_false', dest='InteractiveShell.autoindent', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.autoindent', + default=NoConfigDefault, help='Turn off autoindenting.') ), (('--automagic',), dict( - action='store_true', dest='InteractiveShell.automagic', default=NoConfigDefault, - help='Turn on the auto calling of magic commands.') - ), + action='store_true', dest='InteractiveShell.automagic', + default=NoConfigDefault, + help='Turn on the auto calling of magic commands.' + 'Type %%magic at the IPython prompt for more information.') + ), (('--no-automagic',), dict( - action='store_false', dest='InteractiveShell.automagic', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.automagic', + default=NoConfigDefault, help='Turn off the auto calling of magic commands.') ), (('--autoedit-syntax',), dict( - action='store_true', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault, + action='store_true', dest='InteractiveShell.autoedit_syntax', + default=NoConfigDefault, help='Turn on auto editing of files with syntax errors.') ), (('--no-autoedit-syntax',), dict( - action='store_false', dest='InteractiveShell.autoedit_syntax', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.autoedit_syntax', + default=NoConfigDefault, help='Turn off auto editing of files with syntax errors.') ), (('--banner',), dict( - action='store_true', dest='Global.display_banner', default=NoConfigDefault, + action='store_true', dest='Global.display_banner', + default=NoConfigDefault, help='Display a banner upon starting IPython.') ), (('--no-banner',), dict( - action='store_false', dest='Global.display_banner', default=NoConfigDefault, + action='store_false', dest='Global.display_banner', + default=NoConfigDefault, help="Don't display a banner upon starting IPython.") ), (('--cache-size',), dict( type=int, dest='InteractiveShell.cache_size', default=NoConfigDefault, - help="Set the size of the output cache.", + help= + """Set the size of the output cache. The default is 1000, you can + change it permanently in your config file. Setting it to 0 completely + disables the caching system, and the minimum value accepted is 20 (if + you provide a value less than 20, it is reset to 0 and a warning is + issued). This limit is defined because otherwise you'll spend more + time re-flushing a too small cache than working. + """, metavar='InteractiveShell.cache_size') ), (('--classic',), dict( @@ -109,27 +124,57 @@ cl_args = ( metavar='InteractiveShell.colors') ), (('--color-info',), dict( - action='store_true', dest='InteractiveShell.color_info', default=NoConfigDefault, - help="Enable using colors for info related things.") + action='store_true', dest='InteractiveShell.color_info', + default=NoConfigDefault, + help= + """IPython can display information about objects via a set of func- + tions, and optionally can use colors for this, syntax highlighting + source code and various other elements. However, because this + information is passed through a pager (like 'less') and many pagers get + confused with color codes, this option is off by default. You can test + it and turn it on permanently in your ipython_config.py file if it + works for you. Test it and turn it on permanently if it works with + your system. The magic function %%color_info allows you to toggle this + inter- actively for testing.""" + ) ), (('--no-color-info',), dict( - action='store_false', dest='InteractiveShell.color_info', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.color_info', + default=NoConfigDefault, help="Disable using colors for info related things.") ), (('--confirm-exit',), dict( - action='store_true', dest='InteractiveShell.confirm_exit', default=NoConfigDefault, - help="Prompt the user when existing.") + action='store_true', dest='InteractiveShell.confirm_exit', + default=NoConfigDefault, + help= + """Set to confirm when you try to exit IPython with an EOF (Control-D + in Unix, Control-Z/Enter in Windows). By typing 'exit', 'quit' or + '%%Exit', you can force a direct exit without any confirmation. + """ + ) ), (('--no-confirm-exit',), dict( - action='store_false', dest='InteractiveShell.confirm_exit', default=NoConfigDefault, - help="Don't prompt the user when existing.") + action='store_false', dest='InteractiveShell.confirm_exit', + default=NoConfigDefault, + help="Don't prompt the user when exiting.") ), (('--deep-reload',), dict( - action='store_true', dest='InteractiveShell.deep_reload', default=NoConfigDefault, - help="Enable deep (recursive) reloading by default.") + action='store_true', dest='InteractiveShell.deep_reload', + default=NoConfigDefault, + help= + """Enable deep (recursive) reloading by default. IPython can use the + deep_reload module which reloads changes in modules recursively (it + replaces the reload() function, so you don't need to change anything to + use it). deep_reload() forces a full reload of modules whose code may + have changed, which the default reload() function does not. When + deep_reload is off, IPython will use the normal reload(), but + deep_reload will still be available as dreload(). This fea- ture is off + by default [which means that you have both normal reload() and + dreload()].""") ), (('--no-deep-reload',), dict( - action='store_false', dest='InteractiveShell.deep_reload', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.deep_reload', + default=NoConfigDefault, help="Disable deep (recursive) reloading by default.") ), (('--editor',), dict( @@ -138,43 +183,62 @@ cl_args = ( metavar='InteractiveShell.editor') ), (('--log','-l'), dict( - action='store_true', dest='InteractiveShell.logstart', default=NoConfigDefault, - help="Start logging to the default file (./ipython_log.py).") + action='store_true', dest='InteractiveShell.logstart', + default=NoConfigDefault, + help="Start logging to the default log file (./ipython_log.py).") ), (('--logfile','-lf'), dict( type=unicode, dest='InteractiveShell.logfile', default=NoConfigDefault, - help="Start logging to logfile.", + help="Start logging to logfile with this name.", metavar='InteractiveShell.logfile') ), (('--log-append','-la'), dict( - type=unicode, dest='InteractiveShell.logappend', default=NoConfigDefault, - help="Start logging to the give file in append mode.", + type=unicode, dest='InteractiveShell.logappend', + default=NoConfigDefault, + help="Start logging to the given file in append mode.", metavar='InteractiveShell.logfile') ), (('--pdb',), dict( - action='store_true', dest='InteractiveShell.pdb', default=NoConfigDefault, + action='store_true', dest='InteractiveShell.pdb', + default=NoConfigDefault, help="Enable auto calling the pdb debugger after every exception.") ), (('--no-pdb',), dict( - action='store_false', dest='InteractiveShell.pdb', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.pdb', + default=NoConfigDefault, help="Disable auto calling the pdb debugger after every exception.") ), (('--pprint',), dict( - action='store_true', dest='InteractiveShell.pprint', default=NoConfigDefault, + action='store_true', dest='InteractiveShell.pprint', + default=NoConfigDefault, help="Enable auto pretty printing of results.") ), (('--no-pprint',), dict( - action='store_false', dest='InteractiveShell.pprint', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.pprint', + default=NoConfigDefault, help="Disable auto auto pretty printing of results.") ), (('--prompt-in1','-pi1'), dict( type=str, dest='InteractiveShell.prompt_in1', default=NoConfigDefault, - help="Set the main input prompt ('In [\#]: ')", + help= + """Set the main input prompt ('In [\#]: '). Note that if you are using + numbered prompts, the number is represented with a '\#' in the string. + Don't forget to quote strings with spaces embedded in them. Most + bash-like escapes can be used to customize IPython's prompts, as well + as a few additional ones which are IPython-spe- cific. All valid + prompt escapes are described in detail in the Customization section of + the IPython manual.""", metavar='InteractiveShell.prompt_in1') ), (('--prompt-in2','-pi2'), dict( type=str, dest='InteractiveShell.prompt_in2', default=NoConfigDefault, - help="Set the secondary input prompt (' .\D.: ')", + help= + """Set the secondary input prompt (' .\D.: '). Similar to the previous + option, but used for the continuation prompts. The special sequence + '\D' is similar to '\#', but with all digits replaced by dots (so you + can have your continuation prompt aligned with your input prompt). + Default: ' .\D.: ' (note three spaces at the start for alignment with + 'In [\#]')""", metavar='InteractiveShell.prompt_in2') ), (('--prompt-out','-po'), dict( @@ -187,30 +251,44 @@ cl_args = ( help="Enable quick startup with no config files.") ), (('--readline',), dict( - action='store_true', dest='InteractiveShell.readline_use', default=NoConfigDefault, + action='store_true', dest='InteractiveShell.readline_use', + default=NoConfigDefault, help="Enable readline for command line usage.") ), (('--no-readline',), dict( - action='store_false', dest='InteractiveShell.readline_use', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.readline_use', + default=NoConfigDefault, help="Disable readline for command line usage.") ), (('--screen-length','-sl'), dict( - type=int, dest='InteractiveShell.screen_length', default=NoConfigDefault, - help='Number of lines on screen, used to control printing of long strings.', + type=int, dest='InteractiveShell.screen_length', + default=NoConfigDefault, + help= + """Number of lines of your screen, used to control printing of very + long strings. Strings longer than this number of lines will be sent + through a pager instead of directly printed. The default value for + this is 0, which means IPython will auto-detect your screen size every + time it needs to print certain potentially long strings (this doesn't + change the behavior of the 'print' keyword, it's only triggered + internally). If for some reason this isn't working well (it needs + curses support), specify it yourself. Otherwise don't change the + default.""", metavar='InteractiveShell.screen_length') ), (('--separate-in','-si'), dict( type=str, dest='InteractiveShell.separate_in', default=NoConfigDefault, - help="Separator before input prompts. Default '\n'.", + help="Separator before input prompts. Default '\\n'.", metavar='InteractiveShell.separate_in') ), (('--separate-out','-so'), dict( - type=str, dest='InteractiveShell.separate_out', default=NoConfigDefault, + type=str, dest='InteractiveShell.separate_out', + default=NoConfigDefault, help="Separator before output prompts. Default 0 (nothing).", metavar='InteractiveShell.separate_out') ), (('--separate-out2','-so2'), dict( - type=str, dest='InteractiveShell.separate_out2', default=NoConfigDefault, + type=str, dest='InteractiveShell.separate_out2', + default=NoConfigDefault, help="Separator after output prompts. Default 0 (nonight).", metavar='InteractiveShell.separate_out2') ), @@ -219,16 +297,29 @@ cl_args = ( help="Eliminate all spacing between prompts.") ), (('--term-title',), dict( - action='store_true', dest='InteractiveShell.term_title', default=NoConfigDefault, + action='store_true', dest='InteractiveShell.term_title', + default=NoConfigDefault, help="Enable auto setting the terminal title.") ), (('--no-term-title',), dict( - action='store_false', dest='InteractiveShell.term_title', default=NoConfigDefault, + action='store_false', dest='InteractiveShell.term_title', + default=NoConfigDefault, help="Disable auto setting the terminal title.") ), (('--xmode',), dict( type=str, dest='InteractiveShell.xmode', default=NoConfigDefault, - help="Exception mode ('Plain','Context','Verbose')", + help= + """Exception reporting mode ('Plain','Context','Verbose'). Plain: + similar to python's normal traceback printing. Context: prints 5 lines + of context source code around each line in the traceback. Verbose: + similar to Context, but additionally prints the variables currently + visible where the exception happened (shortening their strings if too + long). This can potentially be very slow, if you happen to have a huge + data structure whose string representation is complex to compute. + Your computer may appear to freeze for a while with cpu usage at 100%%. + If this occurs, you can cancel the traceback with Ctrl-C (maybe hitting + it more than once). + """, metavar='InteractiveShell.xmode') ), (('--ext',), dict( @@ -242,8 +333,11 @@ cl_args = ( metavar='Global.code_to_run') ), (('-i',), dict( - action='store_true', dest='Global.force_interact', default=NoConfigDefault, - help="If running code from the command line, become interactive afterwards.") + action='store_true', dest='Global.force_interact', + default=NoConfigDefault, + help= + "If running code from the command line, become interactive afterwards." + ) ), # Options to start with GUI control enabled from the beginning @@ -280,12 +374,17 @@ cl_args = ( ), ) - -default_config_file_name = u'ipython_config.py' +#----------------------------------------------------------------------------- +# Main classes and functions +#----------------------------------------------------------------------------- class IPythonApp(Application): name = u'ipython' - description = 'IPython: an enhanced interactive Python shell.' + #: argparse formats better the 'usage' than the 'description' field + description = None + #: usage message printed by argparse. If None, auto-generate + usage = usage.cl_usage + config_file_name = default_config_file_name cl_arguments = Application.cl_arguments + cl_args @@ -309,7 +408,6 @@ class IPythonApp(Application): super(IPythonApp, self).__init__(argv) self.shell_params = shell_params - def create_default_config(self): super(IPythonApp, self).create_default_config() # Eliminate multiple lookups diff --git a/IPython/core/usage.py b/IPython/core/usage.py index 1fdd8c9..78bdee6 100644 --- a/IPython/core/usage.py +++ b/IPython/core/usage.py @@ -1,338 +1,47 @@ # -*- coding: utf-8 -*- -#***************************************************************************** -# Copyright (C) 2001-2004 Fernando Perez. +"""Usage information for the main IPython applications. +""" +#----------------------------------------------------------------------------- +# Copyright (C) 2008-2010 The IPython Development Team +# Copyright (C) 2001-2007 Fernando Perez. # # Distributed under the terms of the BSD License. The full license is in # the file COPYING, distributed as part of this software. -#***************************************************************************** +#----------------------------------------------------------------------------- import sys from IPython.core import release -__doc__ = """ -IPython -- An enhanced Interactive Python -========================================= +cl_usage = """\ +ipython [options] [files] -A Python shell with automatic history (input and output), dynamic object -introspection, easier configuration, command completion, access to the system -shell and more. - -IPython can also be embedded in running programs. See EMBEDDING below. - - -USAGE - ipython [options] files - - If invoked with no options, it executes all the files listed in - sequence and drops you into the interpreter while still acknowledging - any options you may have set in your ipythonrc file. This behavior is - different from standard Python, which when called as python -i will - only execute one file and will ignore your configuration setup. - - Please note that some of the configuration options are not available at - the command line, simply because they are not practical here. Look into - your ipythonrc configuration file for details on those. This file - typically installed in the $HOME/.ipython directory. - - For Windows users, $HOME resolves to C:\\Documents and - Settings\\YourUserName in most instances, and _ipython is used instead - of .ipython, since some Win32 programs have problems with dotted names - in directories. - - In the rest of this text, we will refer to this directory as - IPYTHON_DIR. - -REGULAR OPTIONS - After the above threading options have been given, regular options can - follow in any order. All options can be abbreviated to their shortest - non-ambiguous form and are case-sensitive. One or two dashes can be - used. Some options have an alternate short form, indicated after a |. - - Most options can also be set from your ipythonrc configuration file. - See the provided examples for assistance. Options given on the comman- - dline override the values set in the ipythonrc file. - - All options with a [no] prepended can be specified in negated form - (using -nooption instead of -option) to turn the feature off. - - -h, --help - Show summary of options. - - -autocall - Make IPython automatically call any callable object even if you - didn't type explicit parentheses. For example, 'str 43' becomes - 'str(43)' automatically. The value can be '0' to disable the - feature, '1' for 'smart' autocall, where it is not applied if - there are no more arguments on the line, and '2' for 'full' - autocall, where all callable objects are automatically called - (even if no arguments are present). The default is '1'. - - -[no]autoindent - Turn automatic indentation on/off. - - -[no]automagic - Make magic commands automatic (without needing their first char- - acter to be %). Type %magic at the IPython prompt for more - information. - - -[no]autoedit_syntax - When a syntax error occurs after editing a file, automatically - open the file to the trouble causing line for convenient fixing. - - -[no]banner - Print the intial information banner (default on). - - -c - Execute the given command string, and set sys.argv to ['c']. - This is similar to the -c option in the normal Python inter- - preter. - - -cache_size|cs - Size of the output cache (maximum number of entries to hold in - memory). The default is 1000, you can change it permanently in - your config file. Setting it to 0 completely disables the - caching system, and the minimum value accepted is 20 (if you - provide a value less than 20, it is reset to 0 and a warning is - issued). This limit is defined because otherwise you'll spend - more time re-flushing a too small cache than working. - - -classic|cl - Gives IPython a similar feel to the classic Python prompt. - - -colors - Color scheme for prompts and exception reporting. Currently - implemented: NoColor, Linux, and LightBG. - - -[no]color_info - IPython can display information about objects via a set of func- - tions, and optionally can use colors for this, syntax highlight- - ing source code and various other elements. However, because - this information is passed through a pager (like 'less') and - many pagers get confused with color codes, this option is off by - default. You can test it and turn it on permanently in your - ipythonrc file if it works for you. As a reference, the 'less' - pager supplied with Mandrake 8.2 works ok, but that in RedHat - 7.2 doesn't. - - Test it and turn it on permanently if it works with your system. - The magic function @color_info allows you to toggle this inter- - actively for testing. - - -[no]confirm_exit - Set to confirm when you try to exit IPython with an EOF (Con- - trol-D in Unix, Control-Z/Enter in Windows). Note that using the - magic functions @Exit or @Quit you can force a direct exit, - bypassing any confirmation. - - -[no]debug - Show information about the loading process. Very useful to pin - down problems with your configuration files or to get details - about session restores. - - -[no]deep_reload - IPython can use the deep_reload module which reloads changes in - modules recursively (it replaces the reload() function, so you - don't need to change anything to use it). deep_reload() forces a - full reload of modules whose code may have changed, which the - default reload() function does not. - - When deep_reload is off, IPython will use the normal reload(), - but deep_reload will still be available as dreload(). This fea- - ture is off by default [which means that you have both normal - reload() and dreload()]. - - -editor - Which editor to use with the @edit command. By default, IPython - will honor your EDITOR environment variable (if not set, vi is - the Unix default and notepad the Windows one). Since this editor - is invoked on the fly by IPython and is meant for editing small - code snippets, you may want to use a small, lightweight editor - here (in case your default EDITOR is something like Emacs). - - -ipythondir - The name of your IPython configuration directory IPYTHON_DIR. - This can also be specified through the environment variable - IPYTHON_DIR. - - -log|l Generate a log file of all input. The file is named - ipython_log.py in your current directory (which prevents logs - from multiple IPython sessions from trampling each other). You - can use this to later restore a session by loading your logfile - as a file to be executed with option -logplay (see below). - - -logfile|lf - Specify the name of your logfile. - - -logplay|lp - Replay a previous log. For restoring a session as close as pos- - sible to the state you left it in, use this option (don't just - run the logfile). With -logplay, IPython will try to reconstruct - the previous working environment in full, not just execute the - commands in the logfile. - When a session is restored, logging is automatically turned on - again with the name of the logfile it was invoked with (it is - read from the log header). So once you've turned logging on for - a session, you can quit IPython and reload it as many times as - you want and it will continue to log its history and restore - from the beginning every time. - - Caveats: there are limitations in this option. The history vari- - ables _i*,_* and _dh don't get restored properly. In the future - we will try to implement full session saving by writing and - retrieving a failed because of inherent limitations of Python's - Pickle module, so this may have to wait. - - -[no]messages - Print messages which IPython collects about its startup process - (default on). - - -[no]pdb - Automatically call the pdb debugger after every uncaught excep- - tion. If you are used to debugging using pdb, this puts you - automatically inside of it after any call (either in IPython or - in code called by it) which triggers an exception which goes - uncaught. - - -[no]pprint - IPython can optionally use the pprint (pretty printer) module - for displaying results. pprint tends to give a nicer display of - nested data structures. If you like it, you can turn it on per- - manently in your config file (default off). - - -profile|p - Assume that your config file is ipythonrc- (looks in cur- - rent dir first, then in IPYTHON_DIR). This is a quick way to keep - and load multiple config files for different tasks, especially - if you use the include option of config files. You can keep a - basic IPYTHON_DIR/ipythonrc file and then have other 'profiles' - which include this one and load extra things for particular - tasks. For example: - - 1) $HOME/.ipython/ipythonrc : load basic things you always want. - 2) $HOME/.ipython/ipythonrc-math : load (1) and basic math- - related modules. - 3) $HOME/.ipython/ipythonrc-numeric : load (1) and Numeric and - plotting modules. - - Since it is possible to create an endless loop by having circu- - lar file inclusions, IPython will stop if it reaches 15 recur- - sive inclusions. - - -prompt_in1|pi1 - Specify the string used for input prompts. Note that if you are - using numbered prompts, the number is represented with a '\#' in - the string. Don't forget to quote strings with spaces embedded - in them. Default: 'In [\#]: '. - - Most bash-like escapes can be used to customize IPython's - prompts, as well as a few additional ones which are IPython-spe- - cific. All valid prompt escapes are described in detail in the - Customization section of the IPython HTML/PDF manual. - - -prompt_in2|pi2 - Similar to the previous option, but used for the continuation - prompts. The special sequence '\D' is similar to '\#', but with - all digits replaced dots (so you can have your continuation - prompt aligned with your input prompt). Default: ' .\D.: ' - (note three spaces at the start for alignment with 'In [\#]'). - - -prompt_out|po - String used for output prompts, also uses numbers like - prompt_in1. Default: 'Out[\#]:'. - - -quick Start in bare bones mode (no config file loaded). - - -rcfile - Name of your IPython resource configuration file. normally - IPython loads ipythonrc (from current directory) or - IPYTHON_DIR/ipythonrc. If the loading of your config file fails, - IPython starts with a bare bones configuration (no modules - loaded at all). - - -[no]readline - Use the readline library, which is needed to support name com- - pletion and command history, among other things. It is enabled - by default, but may cause problems for users of X/Emacs in - Python comint or shell buffers. - - Note that emacs 'eterm' buffers (opened with M-x term) support - IPython's readline and syntax coloring fine, only 'emacs' (M-x - shell and C-c !) buffers do not. - - -screen_length|sl - Number of lines of your screen. This is used to control print- - ing of very long strings. Strings longer than this number of - lines will be sent through a pager instead of directly printed. - - The default value for this is 0, which means IPython will auto- - detect your screen size every time it needs to print certain - potentially long strings (this doesn't change the behavior of - the 'print' keyword, it's only triggered internally). If for - some reason this isn't working well (it needs curses support), - specify it yourself. Otherwise don't change the default. - - -separate_in|si - Separator before input prompts. Default '0. - - -separate_out|so - Separator before output prompts. Default: 0 (nothing). - - -separate_out2|so2 - Separator after output prompts. Default: 0 (nothing). - - -nosep Shorthand for '-separate_in 0 -separate_out 0 -separate_out2 0'. - Simply removes all input/output separators. - - -upgrade - Allows you to upgrade your IPYTHON_DIR configuration when you - install a new version of IPython. Since new versions may - include new command lines options or example files, this copies - updated ipythonrc-type files. However, it backs up (with a .old - extension) all files which it overwrites so that you can merge - back any custimizations you might have in your personal files. - - -Version - Print version information and exit. - - -wxversion - Select a specific version of wxPython (used in conjunction with - -wthread). Requires the wxversion module, part of recent - wxPython distributions. - - -xmode - Mode for exception reporting. The valid modes are Plain, Con- - text, and Verbose. - - - Plain: similar to python's normal traceback printing. - - - Context: prints 5 lines of context source code around each - line in the traceback. - - - Verbose: similar to Context, but additionally prints the vari- - ables currently visible where the exception happened (shortening - their strings if too long). This can potentially be very slow, - if you happen to have a huge data structure whose string repre- - sentation is complex to compute. Your computer may appear to - freeze for a while with cpu usage at 100%. If this occurs, you - can cancel the traceback with Ctrl-C (maybe hitting it more than - once). - - -EMBEDDING - It is possible to start an IPython instance inside your own Python pro- - grams. In the documentation example files there are some illustrations - on how to do this. - - This feature allows you to evalutate dynamically the state of your - code, operate with your variables, analyze them, etc. Note however - that any changes you make to values while in the shell do NOT propagate - back to the running code, so it is safe to modify your values because - you won't break your code in bizarre ways by doing so. -""" +IPython: an enhanced interactive Python shell. + + A Python shell with automatic history (input and output), dynamic object + introspection, easier configuration, command completion, access to the + system shell and more. IPython can also be embedded in running programs. -cmd_line_usage = __doc__ + If invoked with no options, it executes all the files listed in sequence + and exits, use -i to enter interactive mode after running the files. Files + ending in .py will be treated as normal Python, but files ending in .ipy + can contain special IPython syntax (magic commands, shell expansions, etc.) + + Please note that some of the configuration options are not available at the + command line, simply because they are not practical here. Look into your + ipython_config.py configuration file for details on those. + + This file typically installed in the $HOME/.ipython directory. For Windows + users, $HOME resolves to C:\\Documents and Settings\\YourUserName in most + instances. + + In IPython's documentation, we will refer to this directory as IPYTHON_DIR, + you can change its default location by setting any path you want in this + environment variable. + + For more information, see the manual available in HTML and PDF in your + installation, or online at http://ipython.scipy.org. +""" -#--------------------------------------------------------------------------- interactive_usage = """ IPython -- An enhanced Interactive Python =========================================