Unify command-line usage information in one place.

Fixes: https://bugs.launchpad.net/ipython/+bug/505047

IPython/core/application.py

@@ -1,404 +1,422 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 An application for IPython.
 
 All top-level applications should use the classes in this module for
 handling configuration and creating componenets.
 
 The job of an :class:`Application` is to create the master configuration 
 object and then create the components, passing the config to them.
 
 Authors:
 
 * Brian Granger
 * Fernando Perez
 
 Notes
 -----
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2009  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.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 import logging
 import os
 import sys
 
 from IPython.core import release, crashhandler
 from IPython.utils.genutils import get_ipython_dir, get_ipython_package_dir
 from IPython.config.loader import (
     PyFileConfigLoader,
     ArgParseConfigLoader,
     Config,
     NoConfigDefault
 )
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
 
 class ApplicationError(Exception):
     pass
 
 
 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-<name>.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):
     """Load a config, construct components and set them running."""
 
     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.
     default_config_file_name = config_file_name
     default_log_level = logging.WARN
     # Set by --profile option
     profile_name = None
     #: User's ipython directory, typically ~/.ipython/
     ipython_dir = None
     #: A reference to the argv to be used (typically ends up being sys.argv[1:])
     argv = None
     #: Default command line arguments.  Subclasses should create a new tuple
     #: that *includes* these.
     cl_arguments = app_cl_args
 
     # Private attributes
     _exiting = False
     _initialized = False
 
     # Class choices for things that will be instantiated at runtime.
     _CrashHandler = crashhandler.CrashHandler
 
     def __init__(self, argv=None):
         self.argv = sys.argv[1:] if argv is None else argv
         self.init_logger()
 
     def init_logger(self):
         self.log = logging.getLogger(self.__class__.__name__)
         # This is used as the default until the command line arguments are read.
         self.log.setLevel(self.default_log_level)
         self._log_handler = logging.StreamHandler()
         self._log_formatter = logging.Formatter("[%(name)s] %(message)s")
         self._log_handler.setFormatter(self._log_formatter)
         self.log.addHandler(self._log_handler)
 
     def _set_log_level(self, level):
         self.log.setLevel(level)
 
     def _get_log_level(self):
         return self.log.level
 
     log_level = property(_get_log_level, _set_log_level)
 
     def initialize(self):
         """Start the application."""
         
         if self._initialized:
             return
 
         # The first part is protected with an 'attempt' wrapper, that will log
         # failures with the basic system traceback machinery.  Once our crash
         # handler is in place, we can let any subsequent exception propagate,
         # as our handler will log it with much better detail than the default.
         self.attempt(self.create_crash_handler)
         self.create_default_config()
         self.log_default_config()
         self.set_default_config_log_level()
         self.pre_load_command_line_config()
         self.load_command_line_config()
         self.set_command_line_config_log_level()
         self.post_load_command_line_config()
         self.log_command_line_config()
         self.find_ipython_dir()
         self.find_resources()
         self.find_config_file_name()
         self.find_config_file_paths()
         self.pre_load_file_config()
         self.load_file_config()
         self.set_file_config_log_level()
         self.post_load_file_config()
         self.log_file_config()
         self.merge_configs()
         self.log_master_config()
         self.pre_construct()
         self.construct()
         self.post_construct()
         self._initialized = True
 
     def start(self):
         self.initialize()
         self.start_app()
 
     #-------------------------------------------------------------------------
     # Various stages of Application creation
     #-------------------------------------------------------------------------
 
     def create_crash_handler(self):
         """Create a crash handler, typically setting sys.excepthook to it."""
         self.crash_handler = self._CrashHandler(self, self.name)
         sys.excepthook = self.crash_handler
 
     def create_default_config(self):
         """Create defaults that can't be set elsewhere.
 
         For the most part, we try to set default in the class attributes
         of Components.  But, defaults the top-level Application (which is
         not a HasTraitlets or Component) are not set in this way.  Instead
         we set them here.  The Global section is for variables like this that
         don't belong to a particular component.
         """
         c = Config()
         c.Global.ipython_dir = get_ipython_dir()
         c.Global.log_level = self.log_level
         self.default_config = c
 
     def log_default_config(self):
         self.log.debug('Default config loaded:')
         self.log.debug(repr(self.default_config))
 
     def set_default_config_log_level(self):
         try:
             self.log_level = self.default_config.Global.log_level
         except AttributeError:
             # Fallback to the default_log_level class attribute
             pass
 
     def create_command_line_config(self):
         """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."""
         pass
 
     def load_command_line_config(self):
         """Load the command line config."""
         loader = self.create_command_line_config()
         self.command_line_config = loader.load_config()
         self.extra_args = loader.get_extra_args()
 
     def set_command_line_config_log_level(self):
         try:
             self.log_level = self.command_line_config.Global.log_level
         except AttributeError:
             pass
 
     def post_load_command_line_config(self):
         """Do actions just after loading the command line config."""
         pass
 
     def log_command_line_config(self):
         self.log.debug("Command line config loaded:")
         self.log.debug(repr(self.command_line_config))
 
     def find_ipython_dir(self):
         """Set the IPython directory.
 
         This sets ``self.ipython_dir``, but the actual value that is passed to
         the application is kept in either ``self.default_config`` or
         ``self.command_line_config``.  This also adds ``self.ipython_dir`` to
         ``sys.path`` so config files there can be referenced by other config
         files.
         """
 
         try:
             self.ipython_dir = self.command_line_config.Global.ipython_dir
         except AttributeError:
             self.ipython_dir = self.default_config.Global.ipython_dir
         sys.path.append(os.path.abspath(self.ipython_dir))
         if not os.path.isdir(self.ipython_dir):
             os.makedirs(self.ipython_dir, mode=0777)
         self.log.debug("IPYTHON_DIR set to: %s" % self.ipython_dir)
 
     def find_resources(self):
         """Find other resources that need to be in place.
 
         Things like cluster directories need to be in place to find the
         config file.  These happen right after the IPython directory has
         been set.
         """
         pass
 
     def find_config_file_name(self):
         """Find the config file name for this application.
 
         This must set ``self.config_file_name`` to the filename of the
         config file to use (just the filename). The search paths for the
         config file are set in :meth:`find_config_file_paths` and then passed
         to the config file loader where they are resolved to an absolute path.
 
         If a profile has been set at the command line, this will resolve it.
         """
 
         try:
             self.config_file_name = self.command_line_config.Global.config_file
         except AttributeError:
             pass
 
         try:
             self.profile_name = self.command_line_config.Global.profile
         except AttributeError:
             pass
         else:
             name_parts = self.config_file_name.split('.')
             name_parts.insert(1, u'_' + self.profile_name + u'.')
             self.config_file_name = ''.join(name_parts)
 
     def find_config_file_paths(self):
         """Set the search paths for resolving the config file.
 
         This must set ``self.config_file_paths`` to a sequence of search
         paths to pass to the config file loader.
         """
         # Include our own profiles directory last, so that users can still find
         # our shipped copies of builtin profiles even if they don't have them
         # in their local ipython directory.
         prof_dir = os.path.join(get_ipython_package_dir(), 'config', 'profile')
         self.config_file_paths = (os.getcwd(), self.ipython_dir, prof_dir)
 
     def pre_load_file_config(self):
         """Do actions before the config file is loaded."""
         pass
 
     def load_file_config(self):
         """Load the config file.
         
         This tries to load the config file from disk.  If successful, the
         ``CONFIG_FILE`` config variable is set to the resolved config file
         location.  If not successful, an empty config is used.
         """
         self.log.debug("Attempting to load config file: %s" %
                        self.config_file_name)
         loader = PyFileConfigLoader(self.config_file_name,
                                     path=self.config_file_paths)
         try:
             self.file_config = loader.load_config()
             self.file_config.Global.config_file = loader.full_filename
         except IOError:
             # Only warn if the default config file was NOT being used.
             if not self.config_file_name==self.default_config_file_name:
                 self.log.warn("Config file not found, skipping: %s" %
                                self.config_file_name, exc_info=True)
             self.file_config = Config()
         except:
             self.log.warn("Error loading config file: %s" %
                           self.config_file_name, exc_info=True)
             self.file_config = Config()
 
     def set_file_config_log_level(self):
         # We need to keeep self.log_level updated.  But we only use the value
         # of the file_config if a value was not specified at the command
         # line, because the command line overrides everything.
         if not hasattr(self.command_line_config.Global, 'log_level'):
             try:
                 self.log_level = self.file_config.Global.log_level
             except AttributeError:
                 pass # Use existing value
 
     def post_load_file_config(self):
         """Do actions after the config file is loaded."""
         pass
 
     def log_file_config(self):
         if hasattr(self.file_config.Global, 'config_file'):
             self.log.debug("Config file loaded: %s" %
                            self.file_config.Global.config_file)
             self.log.debug(repr(self.file_config))
 
     def merge_configs(self):
         """Merge the default, command line and file config objects."""
         config = Config()
         config._merge(self.default_config)
         config._merge(self.file_config)
         config._merge(self.command_line_config)
         self.master_config = config
 
     def log_master_config(self):
         self.log.debug("Master config created:")
         self.log.debug(repr(self.master_config))
 
     def pre_construct(self):
         """Do actions after the config has been built, but before construct."""
         pass
 
     def construct(self):
         """Construct the main components that make up this app."""
         self.log.debug("Constructing components for application")
 
     def post_construct(self):
         """Do actions after construct, but before starting the app."""
         pass
 
     def start_app(self):
         """Actually start the app."""
         self.log.debug("Starting application")
 
     #-------------------------------------------------------------------------
     # Utility methods
     #-------------------------------------------------------------------------
 
     def abort(self):
         """Abort the starting of the application."""
         if self._exiting:
             pass
         else:
             self.log.critical("Aborting application: %s" % self.name, exc_info=True)
             self._exiting = True
             sys.exit(1)
 
     def exit(self, exit_status=0):
         if self._exiting:
             pass
         else:
             self.log.debug("Exiting application: %s" % self.name)
             self._exiting = True
             sys.exit(exit_status)
 
     def attempt(self, func, action='abort'):
         try:
             func()
         except SystemExit:
             raise
         except:
             if action == 'abort':
                 self.log.critical("Aborting application: %s" % self.name,
                                   exc_info=True)
                 self.abort()
                 raise
             elif action == 'exit':
                 self.exit(0)
 

IPython/core/ipapp.py

@@ -1,576 +1,674 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 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.
 #-----------------------------------------------------------------------------
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
+from __future__ import absolute_import
 
 import logging
 import os
 import sys
 
 from IPython.core import crashhandler
 from IPython.core import release
 from IPython.core.application import Application
 from IPython.core.error import UsageError
 from IPython.core.iplib import InteractiveShell
 from IPython.core.pylabtools import pylab_activate
 from IPython.config.loader import (
     NoConfigDefault, 
     Config,
     PyFileConfigLoader
 )
 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(
         action='store_true', dest='Global.classic', default=NoConfigDefault,
         help="Gives IPython a similar feel to the classic Python prompt.")
     ),
     (('--colors',), dict(
         type=str, dest='InteractiveShell.colors', default=NoConfigDefault,
         help="Set the color scheme (NoColor, Linux, and LightBG).",
         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(
         type=str, dest='InteractiveShell.editor', default=NoConfigDefault,
         help="Set the editor used by IPython (default to $EDITOR/vi/notepad).",
         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(
         type=str, dest='InteractiveShell.prompt_out', default=NoConfigDefault,
         help="Set the output prompt ('Out[\#]:')",
         metavar='InteractiveShell.prompt_out')
     ),
     (('--quick',), dict(
         action='store_true', dest='Global.quick', default=NoConfigDefault,
         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')
     ),
     (('-no-sep',), dict(
         action='store_true', dest='Global.nosep', default=NoConfigDefault,
         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(
         type=str, dest='Global.extra_extension', default=NoConfigDefault,
         help="The dotted module name of an IPython extension to load.",
         metavar='Global.extra_extension')
     ),
     (('-c',), dict(
         type=str, dest='Global.code_to_run', default=NoConfigDefault,
         help="Execute the given command string.",
         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
     (('--gui',), dict(
         type=str, dest='Global.gui', default=NoConfigDefault,
         help="Enable GUI event loop integration ('qt', 'wx', 'gtk').",
         metavar='gui-mode')
     ),
 
     (('--pylab','-pylab'), dict(
         type=str, dest='Global.pylab', default=NoConfigDefault,
         nargs='?', const='auto', metavar='gui-mode',
         help="Pre-load matplotlib and numpy for interactive use. "+
         "If no value is given, the gui backend is matplotlib's, else use "+
         "one of:  ['tk', 'qt', 'wx', 'gtk'].")
     ),
     
     # Legacy GUI options.  Leave them in for backwards compatibility, but the
     # 'thread' names are really a misnomer now.
     (('--wthread','-wthread'), dict(
         action='store_true', dest='Global.wthread', default=NoConfigDefault,
         help="Enable wxPython event loop integration "+
              "(DEPRECATED, use --gui wx)")
     ),
     (('--q4thread','--qthread','-q4thread','-qthread'), dict(
         action='store_true', dest='Global.q4thread', default=NoConfigDefault,
         help="Enable Qt4 event loop integration. Qt3 is no longer supported. "+
              "(DEPRECATED, use --gui qt)")
     ),
     (('--gthread','-gthread'), dict(
         action='store_true', dest='Global.gthread', default=NoConfigDefault,
         help="Enable GTK event loop integration. "+
              "(DEPRECATED, use --gui gtk)")
     ),
 )
 
-
-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
 
     # Private and configuration attributes
     _CrashHandler = crashhandler.IPythonCrashHandler
     
     def __init__(self, argv=None, **shell_params):
         """Create a new IPythonApp.
 
         Parameters
         ----------
         argv : optional, list
           If given, used as the command-line argv environment to read arguments
           from.
 
         shell_params : optional, dict
           All other keywords are passed to the :class:`iplib.InteractiveShell`
           constructor. 
         """
         super(IPythonApp, self).__init__(argv)
         self.shell_params = shell_params
 
-
     def create_default_config(self):
         super(IPythonApp, self).create_default_config()
         # Eliminate multiple lookups
         Global = self.default_config.Global
 
         # Set all default values
         Global.display_banner = True
         
         # If the -c flag is given or a file is given to run at the cmd line
         # like "ipython foo.py", normally we exit without starting the main
         # loop.  The force_interact config variable allows a user to override
         # this and interact.  It is also set by the -i cmd line flag, just
         # like Python.
         Global.force_interact = False
 
         # By default always interact by starting the IPython mainloop.
         Global.interact = True
 
         # No GUI integration by default
         Global.gui = False
         # Pylab off by default
         Global.pylab = False
 
         # Deprecated versions of gui support that used threading, we support
         # them just for bacwards compatibility as an alternate spelling for
         # '--gui X'
         Global.qthread = False
         Global.q4thread = False
         Global.wthread = False
         Global.gthread = False
 
     def load_file_config(self):
         if hasattr(self.command_line_config.Global, 'quick'):
             if self.command_line_config.Global.quick:
                 self.file_config = Config()
                 return
         super(IPythonApp, self).load_file_config()
 
     def post_load_file_config(self):
         if hasattr(self.command_line_config.Global, 'extra_extension'):
             if not hasattr(self.file_config.Global, 'extensions'):
                 self.file_config.Global.extensions = []
             self.file_config.Global.extensions.append(
                 self.command_line_config.Global.extra_extension)
             del self.command_line_config.Global.extra_extension
 
     def pre_construct(self):
         config = self.master_config
 
         if hasattr(config.Global, 'classic'):
             if config.Global.classic:
                 config.InteractiveShell.cache_size = 0
                 config.InteractiveShell.pprint = 0
                 config.InteractiveShell.prompt_in1 = '>>> '
                 config.InteractiveShell.prompt_in2 = '... '
                 config.InteractiveShell.prompt_out = ''
                 config.InteractiveShell.separate_in = \
                     config.InteractiveShell.separate_out = \
                     config.InteractiveShell.separate_out2 = ''
                 config.InteractiveShell.colors = 'NoColor'
                 config.InteractiveShell.xmode = 'Plain'
 
         if hasattr(config.Global, 'nosep'):
             if config.Global.nosep:
                 config.InteractiveShell.separate_in = \
                 config.InteractiveShell.separate_out = \
                 config.InteractiveShell.separate_out2 = ''
 
         # if there is code of files to run from the cmd line, don't interact
         # unless the -i flag (Global.force_interact) is true.
         code_to_run = config.Global.get('code_to_run','')
         file_to_run = False
         if len(self.extra_args)>=1:
             if self.extra_args[0]:
                 file_to_run = True
         if file_to_run or code_to_run:
             if not config.Global.force_interact:
                 config.Global.interact = False
 
     def construct(self):
         # I am a little hesitant to put these into InteractiveShell itself.
         # But that might be the place for them
         sys.path.insert(0, '')
 
         # Create an InteractiveShell instance
         self.shell = InteractiveShell(None, self.master_config,
                                       **self.shell_params )
 
     def post_construct(self):
         """Do actions after construct, but before starting the app."""
         config = self.master_config
         
         # shell.display_banner should always be False for the terminal 
         # based app, because we call shell.show_banner() by hand below
         # so the banner shows *before* all extension loading stuff.
         self.shell.display_banner = False
 
         if config.Global.display_banner and \
             config.Global.interact:
             self.shell.show_banner()
 
         # Make sure there is a space below the banner.
         if self.log_level <= logging.INFO: print
 
         # Now a variety of things that happen after the banner is printed.
         self._enable_gui_pylab()
         self._load_extensions()
         self._run_exec_lines()
         self._run_exec_files()
         self._run_cmd_line_code()
         self._configure_xmode()
 
     def _enable_gui_pylab(self):
         """Enable GUI event loop integration, taking pylab into account."""
         Global = self.master_config.Global
 
         # Select which gui to use
         if Global.gui:
             gui = Global.gui
         # The following are deprecated, but there's likely to be a lot of use
         # of this form out there, so we might as well support it for now.  But
         # the --gui option above takes precedence.
         elif Global.wthread:
             gui = inputhook.GUI_WX
         elif Global.qthread:
             gui = inputhook.GUI_QT
         elif Global.gthread:
             gui = inputhook.GUI_GTK
         else:
             gui = None
 
         # Using --pylab will also require gui activation, though which toolkit
         # to use may be chosen automatically based on mpl configuration.
         if Global.pylab:
             activate = self.shell.enable_pylab
             if Global.pylab == 'auto':
                 gui = None
             else:
                 gui = Global.pylab
         else:
             # Enable only GUI integration, no pylab
             activate = inputhook.enable_gui
 
         if gui or Global.pylab:
             try:
                 self.log.info("Enabling GUI event loop integration, "
                               "toolkit=%s, pylab=%s" % (gui, Global.pylab) )
                 activate(gui)
             except:
                 self.log.warn("Error in enabling GUI event loop integration:")
                 self.shell.showtraceback()
 
     def _load_extensions(self):
         """Load all IPython extensions in Global.extensions.
 
         This uses the :meth:`InteractiveShell.load_extensions` to load all
         the extensions listed in ``self.master_config.Global.extensions``.
         """
         try:
             if hasattr(self.master_config.Global, 'extensions'):
                 self.log.debug("Loading IPython extensions...")
                 extensions = self.master_config.Global.extensions
                 for ext in extensions:
                     try:
                         self.log.info("Loading IPython extension: %s" % ext)                        
                         self.shell.load_extension(ext)
                     except:
                         self.log.warn("Error in loading extension: %s" % ext)
                         self.shell.showtraceback()
         except:
             self.log.warn("Unknown error in loading extensions:")
             self.shell.showtraceback()
 
     def _run_exec_lines(self):
         """Run lines of code in Global.exec_lines in the user's namespace."""
         try:
             if hasattr(self.master_config.Global, 'exec_lines'):
                 self.log.debug("Running code from Global.exec_lines...")
                 exec_lines = self.master_config.Global.exec_lines
                 for line in exec_lines:
                     try:
                         self.log.info("Running code in user namespace: %s" % line)
                         self.shell.runlines(line)
                     except:
                         self.log.warn("Error in executing line in user namespace: %s" % line)
                         self.shell.showtraceback()
         except:
             self.log.warn("Unknown error in handling Global.exec_lines:")
             self.shell.showtraceback()
 
     def _exec_file(self, fname):
         full_filename = filefind(fname, [u'.', self.ipython_dir])
         if os.path.isfile(full_filename):
             if full_filename.endswith(u'.py'):
                 self.log.info("Running file in user namespace: %s" % full_filename)
                 self.shell.safe_execfile(full_filename, self.shell.user_ns)
             elif full_filename.endswith('.ipy'):
                 self.log.info("Running file in user namespace: %s" % full_filename)
                 self.shell.safe_execfile_ipy(full_filename)
             else:
                 self.log.warn("File does not have a .py or .ipy extension: <%s>" % full_filename)
 
     def _run_exec_files(self):
         try:
             if hasattr(self.master_config.Global, 'exec_files'):
                 self.log.debug("Running files in Global.exec_files...")
                 exec_files = self.master_config.Global.exec_files
                 for fname in exec_files:
                     self._exec_file(fname)
         except:
             self.log.warn("Unknown error in handling Global.exec_files:")
             self.shell.showtraceback()
 
     def _run_cmd_line_code(self):
         if hasattr(self.master_config.Global, 'code_to_run'):
             line = self.master_config.Global.code_to_run
             try:
                 self.log.info("Running code given at command line (-c): %s" % line)
                 self.shell.runlines(line)
             except:
                 self.log.warn("Error in executing line in user namespace: %s" % line)
                 self.shell.showtraceback()
             return
         # Like Python itself, ignore the second if the first of these is present
         try:
             fname = self.extra_args[0]
         except:
             pass
         else:
             try:
                 self._exec_file(fname)
             except:
                 self.log.warn("Error in executing file in user namespace: %s" % fname)
                 self.shell.showtraceback()
 
     def _configure_xmode(self):
         # XXX - shouldn't this be read from the config?  I'm still a little
         # lost with all the details of handling the new config guys...
         self.shell.InteractiveTB.set_mode(mode=self.shell.xmode)
         
     def start_app(self):
         if self.master_config.Global.interact:
             self.log.debug("Starting IPython's mainloop...")
             self.shell.mainloop()
         else:
             self.log.debug("IPython not interactive, start_app is no-op...")
 
 
 def load_default_config(ipython_dir=None):
     """Load the default config file from the default ipython_dir.
 
     This is useful for embedded shells.
     """
     if ipython_dir is None:
         ipython_dir = get_ipython_dir()
     cl = PyFileConfigLoader(default_config_file_name, ipython_dir)
     config = cl.load_config()
     return config
 
 
 def launch_new_instance():
     """Create and run a full blown IPython instance"""
     app = IPythonApp()
     app.start()

IPython/core/usage.py

@@ -1,588 +1,297 b''
 # -*- coding: utf-8 -*-
-#*****************************************************************************
-#       Copyright (C) 2001-2004 Fernando Perez. <[e-mail]>
+"""Usage information for the main IPython applications.
+"""
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2008-2010  The IPython Development Team
+#  Copyright (C) 2001-2007 Fernando Perez. <[e-mail]>
 #
 #  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 <val>
-              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 <command>
-              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 <n>
-              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 <scheme>
-              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 <name>
-              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 <name>
-              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 <name>
-              Assume that your config file is ipythonrc-<name> (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 <string>
-              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 <string>
-              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>
-              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>
-              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 <n>
-              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 <string>
-              Separator before input prompts.  Default '0.
-
-       -separate_out|so <string>
-              Separator before output prompts.  Default: 0 (nothing).
-
-       -separate_out2|so2 <string>
-              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 <string>
-              Select a specific version of wxPython (used in conjunction with
-              -wthread). Requires the wxversion module, part of recent
-              wxPython distributions.
-
-       -xmode <modename>
-              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
 =========================================
 
 IPython offers a combination of convenient shell features, special commands
 and a history mechanism for both input (command history) and output (results
 caching, similar to Mathematica). It is intended to be a fully compatible
 replacement for the standard Python interpreter, while offering vastly
 improved functionality and flexibility.
 
 At your system command line, type 'ipython -help' to see the command line
 options available. This document only describes interactive features.
 
 Warning: IPython relies on the existence of a global variable called __IP which
 controls the shell itself. If you redefine __IP to anything, bizarre behavior
 will quickly occur.
 
 MAIN FEATURES
 
 * Access to the standard Python help. As of Python 2.1, a help system is
   available with access to object docstrings and the Python manuals. Simply
   type 'help' (no quotes) to access it.
 
 * Magic commands: type %magic for information on the magic subsystem.
 
 * System command aliases, via the %alias command or the ipythonrc config file.
 
 * Dynamic object information:
 
   Typing ?word or word? prints detailed information about an object.  If
   certain strings in the object are too long (docstrings, code, etc.) they get
   snipped in the center for brevity.
 
   Typing ??word or word?? gives access to the full information without
   snipping long strings. Long strings are sent to the screen through the less
   pager if longer than the screen, printed otherwise.
 
   The ?/?? system gives access to the full source code for any object (if
   available), shows function prototypes and other useful information.
 
   If you just want to see an object's docstring, type '%pdoc object' (without
   quotes, and without % if you have automagic on).
 
   Both %pdoc and ?/?? give you access to documentation even on things which are
   not explicitely defined. Try for example typing {}.get? or after import os,
   type os.path.abspath??. The magic functions %pdef, %source and %file operate
   similarly.
 
 * Completion in the local namespace, by typing TAB at the prompt.
 
   At any time, hitting tab will complete any available python commands or
   variable names, and show you a list of the possible completions if there's
   no unambiguous one. It will also complete filenames in the current directory.
 
   This feature requires the readline and rlcomplete modules, so it won't work
   if your Python lacks readline support (such as under Windows).
 
 * Search previous command history in two ways (also requires readline):
 
   - Start typing, and then use Ctrl-p (previous,up) and Ctrl-n (next,down) to
   search through only the history items that match what you've typed so
   far. If you use Ctrl-p/Ctrl-n at a blank prompt, they just behave like
   normal arrow keys.
 
   - Hit Ctrl-r: opens a search prompt. Begin typing and the system searches
   your history for lines that match what you've typed so far, completing as
   much as it can.
 
 * Persistent command history across sessions (readline required).
 
 * Logging of input with the ability to save and restore a working session.
   
 * System escape with !. Typing !ls will run 'ls' in the current directory.
 
 * The reload command does a 'deep' reload of a module: changes made to the
   module since you imported will actually be available without having to exit.
 
 * Verbose and colored exception traceback printouts. See the magic xmode and
   xcolor functions for details (just type %magic).
 
 * Input caching system:
 
   IPython offers numbered prompts (In/Out) with input and output caching. All
   input is saved and can be retrieved as variables (besides the usual arrow
   key recall).
 
   The following GLOBAL variables always exist (so don't overwrite them!):
   _i: stores previous input.
   _ii: next previous.
   _iii: next-next previous.
   _ih : a list of all input _ih[n] is the input from line n.
 
   Additionally, global variables named _i<n> are dynamically created (<n>
   being the prompt counter), such that _i<n> == _ih[<n>]
 
   For example, what you typed at prompt 14 is available as _i14 and _ih[14].
 
   You can create macros which contain multiple input lines from this history,
   for later re-execution, with the %macro function.
 
   The history function %hist allows you to see any part of your input history
   by printing a range of the _i variables. Note that inputs which contain
   magic functions (%) appear in the history with a prepended comment. This is
   because they aren't really valid Python code, so you can't exec them.
 
 * Output caching system:
 
   For output that is returned from actions, a system similar to the input
   cache exists but using _ instead of _i. Only actions that produce a result
   (NOT assignments, for example) are cached. If you are familiar with
   Mathematica, IPython's _ variables behave exactly like Mathematica's %
   variables.
 
   The following GLOBAL variables always exist (so don't overwrite them!):
   _ (one underscore): previous output.
   __ (two underscores): next previous.
   ___ (three underscores): next-next previous.
 
   Global variables named _<n> are dynamically created (<n> being the prompt
   counter), such that the result of output <n> is always available as _<n>.
 
   Finally, a global dictionary named _oh exists with entries for all lines
   which generated output.
 
 * Directory history:
 
   Your history of visited directories is kept in the global list _dh, and the
   magic %cd command can be used to go to any entry in that list.
 
 * Auto-parentheses and auto-quotes (adapted from Nathan Gray's LazyPython)
 
     1. Auto-parentheses
         Callable objects (i.e. functions, methods, etc) can be invoked like
         this (notice the commas between the arguments):
             >>> callable_ob arg1, arg2, arg3
         and the input will be translated to this:
             --> callable_ob(arg1, arg2, arg3)
         You can force auto-parentheses by using '/' as the first character
         of a line.  For example:
             >>> /globals             # becomes 'globals()'
         Note that the '/' MUST be the first character on the line!  This
         won't work:
             >>> print /globals    # syntax error
             
         In most cases the automatic algorithm should work, so you should
         rarely need to explicitly invoke /. One notable exception is if you
         are trying to call a function with a list of tuples as arguments (the
         parenthesis will confuse IPython):
             In [1]: zip (1,2,3),(4,5,6)  # won't work
         but this will work:
             In [2]: /zip (1,2,3),(4,5,6)
             ------> zip ((1,2,3),(4,5,6))
             Out[2]= [(1, 4), (2, 5), (3, 6)]        
 
         IPython tells you that it has altered your command line by
         displaying the new command line preceded by -->.  e.g.:
             In [18]: callable list
             -------> callable (list) 
 
     2. Auto-Quoting
         You can force auto-quoting of a function's arguments by using ',' as
         the first character of a line.  For example:
             >>> ,my_function /home/me   # becomes my_function("/home/me")
 
         If you use ';' instead, the whole argument is quoted as a single
         string (while ',' splits on whitespace):
             >>> ,my_function a b c   # becomes my_function("a","b","c")
             >>> ;my_function a b c   # becomes my_function("a b c")
 
         Note that the ',' MUST be the first character on the line!  This
         won't work:
             >>> x = ,my_function /home/me    # syntax error
 """
 
 interactive_usage_min =  """\
 An enhanced console for Python.
 Some of its features are:
 - Readline support if the readline library is present.
 - Tab completion in the local namespace.
 - Logging of input, see command-line options.
 - System shell escape via ! , eg !ls.
 - Magic commands, starting with a % (like %ls, %pwd, %cd, etc.)
 - Keeps track of locally defined variables via %who, %whos.
 - Show object information with a ? eg ?x or x? (use ?? for more info).
 """
 
 quick_reference = r"""
 IPython -- An enhanced Interactive Python - Quick Reference Card
 ================================================================
 
 obj?, obj??      : Get help, or more help for object (also works as
                    ?obj, ??obj).
 ?foo.*abc*       : List names in 'foo' containing 'abc' in them.
 %magic           : Information about IPython's 'magic' % functions.
 
 Magic functions are prefixed by %, and typically take their arguments without
 parentheses, quotes or even commas for convenience.
  
 Example magic function calls:
 
 %alias d ls -F   : 'd' is now an alias for 'ls -F'
 alias d ls -F    : Works if 'alias' not a python name
 alist = %alias   : Get list of aliases to 'alist'
 cd /usr/share    : Obvious. cd -<tab> to choose from visited dirs.
 %cd??            : See help AND source for magic %cd
 
 System commands:
     
 !cp a.txt b/     : System command escape, calls os.system()
 cp a.txt b/      : after %rehashx, most system commands work without !
 cp ${f}.txt $bar : Variable expansion in magics and system commands
 files = !ls /usr : Capture sytem command output
 files.s, files.l, files.n: "a b c", ['a','b','c'], 'a\nb\nc'
 
 History:
 
 _i, _ii, _iii    : Previous, next previous, next next previous input
 _i4, _ih[2:5]    : Input history line 4, lines 2-4
 exec _i81        : Execute input history line #81 again
 %rep 81          : Edit input history line #81        
 _, __, ___       : previous, next previous, next next previous output
 _dh              : Directory history
 _oh              : Output history
 %hist            : Command history. '%hist -g foo' search history for 'foo'
 
 Autocall:
 
 f 1,2            : f(1,2)
 /f 1,2           : f(1,2) (forced autoparen)
 ,f 1 2           : f("1","2")
 ;f 1 2           : f("1 2")
 
 Remember: TAB completion works in many contexts, not just file names
 or python names.
 
 The following magic functions are currently available:
 
 """
 
 quick_guide = """\
 ?         -> Introduction and overview of IPython's features.
 %quickref -> Quick reference.
 help      -> Python's own help system.
 object?   -> Details about 'object'. ?object also works, ?? prints more."""
 
 default_banner_parts = [
     'Python %s' % (sys.version.split('\n')[0],),
     'Type "copyright", "credits" or "license" for more information.\n',
     'IPython %s -- An enhanced Interactive Python.' % (release.version,),
     quick_guide
 ]
 
 default_banner = '\n'.join(default_banner_parts)