More work on adding examples to help strings.

IPython/core/profileapp.py

@@ -1,231 +1,237 b''
 # encoding: utf-8
 """
 An application for managing IPython profiles.
 
 To be invoked as the `ipython profile` subcommand.
 
 Authors:
 
 * Min RK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  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
 
 from IPython.config.application import Application, boolean_flag
 from IPython.core.application import (
     BaseIPythonApplication, base_flags, base_aliases
 )
 from IPython.core.profiledir import ProfileDir
 from IPython.utils.path import get_ipython_dir
 from IPython.utils.traitlets import Unicode, Bool, Dict
 
 #-----------------------------------------------------------------------------
 # Constants
 #-----------------------------------------------------------------------------
 
 create_help = """Create an IPython profile by name
 
 Create an ipython profile directory by its name or
 profile directory path. Profile directories contain
 configuration, log and security related files and are named
 using the convention 'profile_<name>'. By default they are
 located in your ipython directory. Once created, you will
 can edit the configuration files in the profile
 directory to configure IPython. Most users will create a
 profile directory by name,
 `ipython profile create myprofile`, which will put the directory
 in `<ipython_dir>/profile_myprofile`.
 """
 list_help = """List available IPython profiles
 
 List all available profiles, by profile location, that can
 be found in the current working directly or in the ipython
 directory. Profile directories are named using the convention
 'profile_<profile>'.
 """
 profile_help = """Manage IPython profiles
 
 Profile directories contain
 configuration, log and security related files and are named
 using the convention 'profile_<name>'. By default they are
 located in your ipython directory.  You can create profiles
 with `ipython profile create <name>`, or see the profiles you
 already have with `ipython profile list`
 
 To get started configuring IPython, simply do:
 
 $> ipython profile create
 
 and IPython will create the default profile in <ipython_dir>/profile_default,
 where you can edit ipython_config.py to start configuring IPython.
 
 """
 
+_list_examples = "ipython profile list  # list all profiles"
+
+_create_examples = """
+ipython profile create foo        # create profile foo
+ipython profile create foo --init # create with default config files
+"""
+
+_main_examples = """
+ipython profile create -h  # show the help string for the create subcommand
+ipython profile list -h    # show the help string for the list subcommand
+"""
+
 #-----------------------------------------------------------------------------
 # Profile Application Class (for `ipython profile` subcommand)
 #-----------------------------------------------------------------------------
 
 
 class ProfileList(Application):
     name = u'ipython-profile'
     description = list_help
+    examples = _list_examples
     
     aliases = Dict({
         'ipython-dir' : 'ProfileList.ipython_dir',
         'log-level' : 'Application.log_level',
     })
     flags = Dict(dict(
         debug = ({'Application' : {'log_level' : 0}},
             "Set Application.log_level to 0, maximizing log output."
         )
     ))
+
     ipython_dir = Unicode(get_ipython_dir(), config=True, 
         help="""
         The name of the IPython directory. This directory is used for logging
         configuration (through profiles), history storage, etc. The default
         is usually $HOME/.ipython. This options can also be specified through
         the environment variable IPYTHON_DIR.
         """
     )
     
     def list_profile_dirs(self):
         # Find the search paths
         paths = [os.getcwdu(), self.ipython_dir]
 
         self.log.warn('Searching for IPython profiles in paths: %r' % paths)
         for path in paths:
             files = os.listdir(path)
             for f in files:
                 full_path = os.path.join(path, f)
                 if os.path.isdir(full_path) and f.startswith('profile_'):
                     profile = f.split('_',1)[-1]
                     start_cmd = 'ipython profile=%s' % profile
                     print start_cmd + " ==> " + full_path
     
     def start(self):
         self.list_profile_dirs()
 
 
 create_flags = {}
 create_flags.update(base_flags)
 create_flags.update(boolean_flag('reset', 'ProfileCreate.overwrite', 
                 "reset config files to defaults", "leave existing config files"))
 create_flags.update(boolean_flag('parallel', 'ProfileCreate.parallel', 
                 "Include parallel computing config files", 
                 "Don't include parallel computing config files"))
 
-create_examples = """
-ipython profile create foo        # create profile foo
-ipython profile create foo --init # create with default config files
-"""
 
 class ProfileCreate(BaseIPythonApplication):
     name = u'ipython-profile'
     description = create_help
-    examples = create_examples
+    examples = _create_examples
     auto_create = Bool(True, config=False)
     
     def _copy_config_files_default(self):
         return True
     
     parallel = Bool(False, config=True,
         help="whether to include parallel computing config files")
     def _parallel_changed(self, name, old, new):
         parallel_files = [   'ipcontroller_config.py', 
                             'ipengine_config.py', 
                             'ipcluster_config.py'
                         ]
         if new:
             for cf in parallel_files:
                 self.config_files.append(cf)
         else:
             for cf in parallel_files:
                 if cf in self.config_files:
                     self.config_files.remove(cf)
     
     def parse_command_line(self, argv):
         super(ProfileCreate, self).parse_command_line(argv)
         # accept positional arg as profile name
         if self.extra_args:
             self.profile = self.extra_args[0]
     
     flags = Dict(create_flags)
     
     classes = [ProfileDir]
     
     def init_config_files(self):
         super(ProfileCreate, self).init_config_files()
         # use local imports, since these classes may import from here
         from IPython.frontend.terminal.ipapp import TerminalIPythonApp
         apps = [TerminalIPythonApp]
         try:
             from IPython.frontend.qt.console.qtconsoleapp import IPythonQtConsoleApp
         except Exception:
             # this should be ImportError, but under weird circumstances
             # this might be an AttributeError, or possibly others
             # in any case, nothing should cause the profile creation to crash.
             pass
         else:
             apps.append(IPythonQtConsoleApp)
         if self.parallel:
             from IPython.parallel.apps.ipcontrollerapp import IPControllerApp
             from IPython.parallel.apps.ipengineapp import IPEngineApp
             from IPython.parallel.apps.ipclusterapp import IPClusterStart
             from IPython.parallel.apps.iploggerapp import IPLoggerApp
             apps.extend([
                 IPControllerApp,
                 IPEngineApp,
                 IPClusterStart,
                 IPLoggerApp,
             ])
         for App in apps:
             app = App()
             app.config.update(self.config)
             app.log = self.log
             app.overwrite = self.overwrite
             app.copy_config_files=True
             app.profile = self.profile
             app.init_profile_dir()
             app.init_config_files()
     
     def stage_default_config_file(self):
         pass
 
-main_examples = """
-ipython profile create -h  # show the help string for the create subcommand
-ipython profile list -h    # show the help string for the list subcommand
-"""
 
 class ProfileApp(Application):
     name = u'ipython-profile'
     description = profile_help
-    examples = main_examples
+    examples = _main_examples
 
     subcommands = Dict(dict(
         create = (ProfileCreate, "Create a new profile dir with default config files"),
         list = (ProfileList, "List existing profiles")
     ))
     
     def start(self):
         if self.subapp is None:
             print "No subcommand specified. Must specify one of: %s"%(self.subcommands.keys())
             print
             self.print_description()
             self.print_subcommands()
             self.exit(1)
         else:
             return self.subapp.start()
 

IPython/frontend/qt/console/qtconsoleapp.py

@@ -1,429 +1,434 b''
 """ A minimal application using the Qt console-style IPython frontend.
 
 This is not a complete console app, as subprocess will not be able to receive
 input, there is no real readline support, among other limitations.
 
 Authors:
 
 * Evan Patterson
 * Min RK
 * Erik Tollerud
 * Fernando Perez
 
 """
 
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
 
 # stdlib imports
 import os
 import signal
 import sys
 
 # System library imports
 from IPython.external.qt import QtGui
 from pygments.styles import get_all_styles
 
 # Local imports
 from IPython.config.application import boolean_flag
 from IPython.core.application import BaseIPythonApplication
 from IPython.core.profiledir import ProfileDir
 from IPython.frontend.qt.console.frontend_widget import FrontendWidget
 from IPython.frontend.qt.console.ipython_widget import IPythonWidget
 from IPython.frontend.qt.console.rich_ipython_widget import RichIPythonWidget
 from IPython.frontend.qt.console import styles
 from IPython.frontend.qt.kernelmanager import QtKernelManager
 from IPython.utils.traitlets import (
     Dict, List, Unicode, Int, CaselessStrEnum, CBool, Any
 )
 from IPython.zmq.ipkernel import (
     flags as ipkernel_flags,
     aliases as ipkernel_aliases,
     IPKernelApp
 )
 from IPython.zmq.session import Session
 from IPython.zmq.zmqshell import ZMQInteractiveShell
 
 
 #-----------------------------------------------------------------------------
 # Network Constants
 #-----------------------------------------------------------------------------
 
 from IPython.utils.localinterfaces import LOCALHOST, LOCAL_IPS
 
 #-----------------------------------------------------------------------------
+# Globals
+#-----------------------------------------------------------------------------
+
+_examples = """
+ipython qtconsole                 # start the qtconsole
+ipython qtconsole --pylab=inline  # start with pylab in inline plotting mode
+"""
+
+#-----------------------------------------------------------------------------
 # Classes
 #-----------------------------------------------------------------------------
 
 class MainWindow(QtGui.QMainWindow):
 
     #---------------------------------------------------------------------------
     # 'object' interface
     #---------------------------------------------------------------------------
     
     def __init__(self, app, frontend, existing=False, may_close=True,
                     confirm_exit=True):
         """ Create a MainWindow for the specified FrontendWidget.
         
         The app is passed as an argument to allow for different
         closing behavior depending on whether we are the Kernel's parent.
         
         If existing is True, then this Console does not own the Kernel.
         
         If may_close is True, then this Console is permitted to close the kernel
         """
         super(MainWindow, self).__init__()
         self._app = app
         self._frontend = frontend
         self._existing = existing
         if existing:
             self._may_close = may_close
         else:
             self._may_close = True
         self._frontend.exit_requested.connect(self.close)
         self._confirm_exit = confirm_exit
         self.setCentralWidget(frontend)
     
     #---------------------------------------------------------------------------
     # QWidget interface
     #---------------------------------------------------------------------------
     
     def closeEvent(self, event):
         """ Close the window and the kernel (if necessary).
         
         This will prompt the user if they are finished with the kernel, and if
         so, closes the kernel cleanly. Alternatively, if the exit magic is used,
         it closes without prompt.
         """
         keepkernel = None #Use the prompt by default
         if hasattr(self._frontend,'_keep_kernel_on_exit'): #set by exit magic
             keepkernel = self._frontend._keep_kernel_on_exit
         
         kernel_manager = self._frontend.kernel_manager
         
         if keepkernel is None and not self._confirm_exit:
             # don't prompt, just terminate the kernel if we own it
             # or leave it alone if we don't
             keepkernel = not self._existing
         
         if keepkernel is None: #show prompt
             if kernel_manager and kernel_manager.channels_running:
                 title = self.window().windowTitle()
                 cancel = QtGui.QMessageBox.Cancel
                 okay = QtGui.QMessageBox.Ok
                 if self._may_close:
                     msg = "You are closing this Console window."
                     info = "Would you like to quit the Kernel and all attached Consoles as well?"
                     justthis = QtGui.QPushButton("&No, just this Console", self)
                     justthis.setShortcut('N')
                     closeall = QtGui.QPushButton("&Yes, quit everything", self)
                     closeall.setShortcut('Y')
                     box = QtGui.QMessageBox(QtGui.QMessageBox.Question,
                                             title, msg)
                     box.setInformativeText(info)
                     box.addButton(cancel)
                     box.addButton(justthis, QtGui.QMessageBox.NoRole)
                     box.addButton(closeall, QtGui.QMessageBox.YesRole)
                     box.setDefaultButton(closeall)
                     box.setEscapeButton(cancel)
                     reply = box.exec_()
                     if reply == 1: # close All
                         kernel_manager.shutdown_kernel()
                         #kernel_manager.stop_channels()
                         event.accept()
                     elif reply == 0: # close Console
                         if not self._existing:
                             # Have kernel: don't quit, just close the window
                             self._app.setQuitOnLastWindowClosed(False)
                             self.deleteLater()
                         event.accept()
                     else:
                         event.ignore()
                 else:
                     reply = QtGui.QMessageBox.question(self, title,
                         "Are you sure you want to close this Console?"+
                         "\nThe Kernel and other Consoles will remain active.",
                         okay|cancel,
                         defaultButton=okay
                         )
                     if reply == okay:
                         event.accept()
                     else:
                         event.ignore()
         elif keepkernel: #close console but leave kernel running (no prompt)
             if kernel_manager and kernel_manager.channels_running:
                 if not self._existing:
                     # I have the kernel: don't quit, just close the window
                     self._app.setQuitOnLastWindowClosed(False)
                 event.accept()
         else: #close console and kernel (no prompt)
             if kernel_manager and kernel_manager.channels_running:
                 kernel_manager.shutdown_kernel()
                 event.accept()
 
 #-----------------------------------------------------------------------------
 # Aliases and Flags
 #-----------------------------------------------------------------------------
 
 flags = dict(ipkernel_flags)
 
 flags.update({
     'existing' : ({'IPythonQtConsoleApp' : {'existing' : True}},
             "Connect to an existing kernel."),
     'pure' : ({'IPythonQtConsoleApp' : {'pure' : True}},
             "Use a pure Python kernel instead of an IPython kernel."),
     'plain' : ({'ConsoleWidget' : {'kind' : 'plain'}},
             "Disable rich text support."),
 })
 flags.update(boolean_flag(
     'gui-completion', 'ConsoleWidget.gui_completion',
     "use a GUI widget for tab completion",
     "use plaintext output for completion"
 ))
 flags.update(boolean_flag(
     'confirm-exit', 'IPythonQtConsoleApp.confirm_exit',
     """Set to display confirmation dialog on exit. You can always use 'exit' or 'quit',
        to force a direct exit without any confirmation.
     """,
     """Don't prompt the user when exiting. This will terminate the kernel
        if it is owned by the frontend, and leave it alive if it is external.
     """
 ))
 # the flags that are specific to the frontend
 # these must be scrubbed before being passed to the kernel,
 # or it will raise an error on unrecognized flags
 qt_flags = ['existing', 'pure', 'plain', 'gui-completion', 'no-gui-completion',
             'confirm-exit', 'no-confirm-exit']
 
 aliases = dict(ipkernel_aliases)
 
 aliases.update(dict(
     hb = 'IPythonQtConsoleApp.hb_port',
     shell = 'IPythonQtConsoleApp.shell_port',
     iopub = 'IPythonQtConsoleApp.iopub_port',
     stdin = 'IPythonQtConsoleApp.stdin_port',
     ip = 'IPythonQtConsoleApp.ip',
 
     plain = 'IPythonQtConsoleApp.plain',
     pure = 'IPythonQtConsoleApp.pure',
     gui_completion = 'ConsoleWidget.gui_completion',
     style = 'IPythonWidget.syntax_style',
     stylesheet = 'IPythonQtConsoleApp.stylesheet',
     colors = 'ZMQInteractiveShell.colors',
 
     editor = 'IPythonWidget.editor',
 ))
 
 #-----------------------------------------------------------------------------
 # IPythonQtConsole
 #-----------------------------------------------------------------------------
 
-qt_examples = """
-ipython qtconsole                 # start the qtconsole
-ipython qtconsole --pylab=inline  # start with pylab in inline plotting mode
-"""
 
 class IPythonQtConsoleApp(BaseIPythonApplication):
     name = 'ipython-qtconsole'
     default_config_file_name='ipython_config.py'
     
     description = """
         The IPython QtConsole.
         
         This launches a Console-style application using Qt.  It is not a full
         console, in that launched terminal subprocesses will not.
         
         The QtConsole supports various extra features beyond the
         
     """
-    examples = qt_examples
+    examples = _examples
 
     classes = [IPKernelApp, IPythonWidget, ZMQInteractiveShell, ProfileDir, Session]
     flags = Dict(flags)
     aliases = Dict(aliases)
 
     kernel_argv = List(Unicode)
 
     # connection info:
     ip = Unicode(LOCALHOST, config=True,
         help="""Set the kernel\'s IP address [default localhost].
         If the IP address is something other than localhost, then
         Consoles on other machines will be able to connect
         to the Kernel, so be careful!"""
     )
     hb_port = Int(0, config=True,
         help="set the heartbeat port [default: random]")
     shell_port = Int(0, config=True,
         help="set the shell (XREP) port [default: random]")
     iopub_port = Int(0, config=True,
         help="set the iopub (PUB) port [default: random]")
     stdin_port = Int(0, config=True,
         help="set the stdin (XREQ) port [default: random]")
 
     existing = CBool(False, config=True,
         help="Whether to connect to an already running Kernel.")
 
     stylesheet = Unicode('', config=True,
         help="path to a custom CSS stylesheet")
 
     pure = CBool(False, config=True,
         help="Use a pure Python kernel instead of an IPython kernel.")
     plain = CBool(False, config=True,
         help="Use a plaintext widget instead of rich text (plain can't print/save).")
 
     def _pure_changed(self, name, old, new):
         kind = 'plain' if self.plain else 'rich'
         self.config.ConsoleWidget.kind = kind
         if self.pure:
             self.widget_factory = FrontendWidget
         elif self.plain:
             self.widget_factory = IPythonWidget
         else:
             self.widget_factory = RichIPythonWidget
 
     _plain_changed = _pure_changed
 
     confirm_exit = CBool(True, config=True,
         help="""
         Set to display confirmation dialog on exit. You can always use 'exit' or 'quit',
         to force a direct exit without any confirmation.""",
     )
     
     # the factory for creating a widget
     widget_factory = Any(RichIPythonWidget)
 
     def parse_command_line(self, argv=None):
         super(IPythonQtConsoleApp, self).parse_command_line(argv)
         if argv is None:
             argv = sys.argv[1:]
 
         self.kernel_argv = list(argv) # copy
         # kernel should inherit default config file from frontend
         self.kernel_argv.append("--KernelApp.parent_appname='%s'"%self.name)
         # scrub frontend-specific flags
         for a in argv:
             if a.startswith('-') and a.lstrip('-') in qt_flags:
                 self.kernel_argv.remove(a)
 
     def init_kernel_manager(self):
         # Don't let Qt or ZMQ swallow KeyboardInterupts.
         signal.signal(signal.SIGINT, signal.SIG_DFL)
 
         # Create a KernelManager and start a kernel.
         self.kernel_manager = QtKernelManager(
                                 shell_address=(self.ip, self.shell_port),
                                 sub_address=(self.ip, self.iopub_port),
                                 stdin_address=(self.ip, self.stdin_port),
                                 hb_address=(self.ip, self.hb_port),
                                 config=self.config
         )
         # start the kernel
         if not self.existing:
             kwargs = dict(ip=self.ip, ipython=not self.pure)
             kwargs['extra_arguments'] = self.kernel_argv
             self.kernel_manager.start_kernel(**kwargs)
         self.kernel_manager.start_channels()
 
 
     def init_qt_elements(self):
         # Create the widget.
         self.app = QtGui.QApplication([])
         local_kernel = (not self.existing) or self.ip in LOCAL_IPS
         self.widget = self.widget_factory(config=self.config,
                                         local_kernel=local_kernel)
         self.widget.kernel_manager = self.kernel_manager
         self.window = MainWindow(self.app, self.widget, self.existing,
                                 may_close=local_kernel,
                                 confirm_exit=self.confirm_exit)
         self.window.setWindowTitle('Python' if self.pure else 'IPython')
 
     def init_colors(self):
         """Configure the coloring of the widget"""
         # Note: This will be dramatically simplified when colors
         # are removed from the backend.
 
         if self.pure:
             # only IPythonWidget supports styling
             return
 
         # parse the colors arg down to current known labels
         try:
             colors = self.config.ZMQInteractiveShell.colors
         except AttributeError:
             colors = None
         try:
             style = self.config.IPythonWidget.colors
         except AttributeError:
             style = None
 
         # find the value for colors:
         if colors:
             colors=colors.lower()
             if colors in ('lightbg', 'light'):
                 colors='lightbg'
             elif colors in ('dark', 'linux'):
                 colors='linux'
             else:
                 colors='nocolor'
         elif style:
             if style=='bw':
                 colors='nocolor'
             elif styles.dark_style(style):
                 colors='linux'
             else:
                 colors='lightbg'
         else:
             colors=None
 
         # Configure the style.
         widget = self.widget
         if style:
             widget.style_sheet = styles.sheet_from_template(style, colors)
             widget.syntax_style = style
             widget._syntax_style_changed()
             widget._style_sheet_changed()
         elif colors:
             # use a default style
             widget.set_default_style(colors=colors)
         else:
             # this is redundant for now, but allows the widget's
             # defaults to change
             widget.set_default_style()
 
         if self.stylesheet:
             # we got an expicit stylesheet
             if os.path.isfile(self.stylesheet):
                 with open(self.stylesheet) as f:
                     sheet = f.read()
                 widget.style_sheet = sheet
                 widget._style_sheet_changed()
             else:
                 raise IOError("Stylesheet %r not found."%self.stylesheet)
 
     def initialize(self, argv=None):
         super(IPythonQtConsoleApp, self).initialize(argv)
         self.init_kernel_manager()
         self.init_qt_elements()
         self.init_colors()
 
     def start(self):
 
         # draw the window
         self.window.show()
 
         # Start the application main loop.
         self.app.exec_()
 
 #-----------------------------------------------------------------------------
 # Main entry point
 #-----------------------------------------------------------------------------
 
 def main():
     app = IPythonQtConsoleApp()
     app.initialize()
     app.start()
 
 
 if __name__ == '__main__':
     main()

IPython/frontend/terminal/ipapp.py

@@ -1,375 +1,375 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The :class:`~IPython.core.application.Application` object for the command
 line :command:`ipython` program.
 
 Authors
 -------
 
 * Brian Granger
 * Fernando Perez
 * Min Ragan-Kelley
 """
 
 #-----------------------------------------------------------------------------
 #  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.config.loader import (
     Config, PyFileConfigLoader
 )
 from IPython.config.application import boolean_flag
 from IPython.core import release
 from IPython.core import usage
 from IPython.core.crashhandler import CrashHandler
 from IPython.core.formatters import PlainTextFormatter
 from IPython.core.application import (
     ProfileDir, BaseIPythonApplication, base_flags, base_aliases
 )
 from IPython.core.shellapp import (
     InteractiveShellApp, shell_flags, shell_aliases
 )
 from IPython.frontend.terminal.interactiveshell import TerminalInteractiveShell
 from IPython.lib import inputhook
 from IPython.utils import warn
 from IPython.utils.path import get_ipython_dir, check_for_old_config
 from IPython.utils.traitlets import (
     Bool, Dict, CaselessStrEnum
 )
 
 #-----------------------------------------------------------------------------
 # Globals, utilities and helpers
 #-----------------------------------------------------------------------------
 
 #: The default config file name for this application.
 default_config_file_name = u'ipython_config.py'
 
+_examples = """
+ipython --pylab            # start in pylab mode
+ipython --pylab=qt         # start in pylab mode with the qt4 backend
+ipython --log_level=DEBUG  # set logging to DEBUG
+ipython --profile=foo      # start with profile foo
+ipython qtconsole          # start the qtconsole GUI application
+ipython profile -h         # show the help string for the profile subcmd
+ipython qtconsole -h       # show the help string for the qtconsole subcmd
+"""
 
 #-----------------------------------------------------------------------------
 # Crash handler for this application
 #-----------------------------------------------------------------------------
 
 class IPAppCrashHandler(CrashHandler):
     """sys.excepthook for IPython itself, leaves a detailed report on disk."""
 
     def __init__(self, app):
         contact_name = release.authors['Fernando'][0]
         contact_email = release.authors['Fernando'][1]
         bug_tracker = 'http://github.com/ipython/ipython/issues'
         super(IPAppCrashHandler,self).__init__(
             app, contact_name, contact_email, bug_tracker
         )
 
     def make_report(self,traceback):
         """Return a string containing a crash report."""
 
         sec_sep = self.section_sep
         # Start with parent report
         report = [super(IPAppCrashHandler, self).make_report(traceback)]
         # Add interactive-specific info we may have
         rpt_add = report.append
         try:
             rpt_add(sec_sep+"History of session input:")
             for line in self.app.shell.user_ns['_ih']:
                 rpt_add(line)
             rpt_add('\n*** Last line of input (may not be in above history):\n')
             rpt_add(self.app.shell._last_input_line+'\n')
         except:
             pass
 
         return ''.join(report)
 
 #-----------------------------------------------------------------------------
 # Aliases and Flags
 #-----------------------------------------------------------------------------
 flags = dict(base_flags)
 flags.update(shell_flags)
 addflag = lambda *args: flags.update(boolean_flag(*args))
 addflag('autoedit-syntax', 'TerminalInteractiveShell.autoedit_syntax',
         'Turn on auto editing of files with syntax errors.',
         'Turn off auto editing of files with syntax errors.'
 )
 addflag('banner', 'TerminalIPythonApp.display_banner',
         "Display a banner upon starting IPython.",
         "Don't display a banner upon starting IPython."
 )
 addflag('confirm-exit', 'TerminalInteractiveShell.confirm_exit',
     """Set to confirm when you try to exit IPython with an EOF (Control-D
     in Unix, Control-Z/Enter in Windows). By typing 'exit' or 'quit',
     you can force a direct exit without any confirmation.""",
     "Don't prompt the user when exiting."
 )
 addflag('term-title', 'TerminalInteractiveShell.term_title',
     "Enable auto setting the terminal title.",
     "Disable auto setting the terminal title."
 )
 classic_config = Config()
 classic_config.InteractiveShell.cache_size = 0
 classic_config.PlainTextFormatter.pprint = False
 classic_config.InteractiveShell.prompt_in1 = '>>> '
 classic_config.InteractiveShell.prompt_in2 = '... '
 classic_config.InteractiveShell.prompt_out = ''
 classic_config.InteractiveShell.separate_in = ''
 classic_config.InteractiveShell.separate_out = ''
 classic_config.InteractiveShell.separate_out2 = ''
 classic_config.InteractiveShell.colors = 'NoColor'
 classic_config.InteractiveShell.xmode = 'Plain'
 
 flags['classic']=(
     classic_config,
     "Gives IPython a similar feel to the classic Python prompt."
 )
 # # log doesn't make so much sense this way anymore
 # paa('--log','-l',
 #     action='store_true', dest='InteractiveShell.logstart',
 #     help="Start logging to the default log file (./ipython_log.py).")
 #
 # # quick is harder to implement
 flags['quick']=(
     {'TerminalIPythonApp' : {'quick' : True}},
     "Enable quick startup with no config files."
 )
 
 flags['i'] = (
     {'TerminalIPythonApp' : {'force_interact' : True}},
     """also works as '-i'
     If running code from the command line, become interactive afterwards."""
 )
 flags['pylab'] = (
     {'TerminalIPythonApp' : {'pylab' : 'auto'}},
     """Pre-load matplotlib and numpy for interactive use with
     the default matplotlib backend."""
 )
 
 aliases = dict(base_aliases)
 aliases.update(shell_aliases)
 
 # it's possible we don't want short aliases for *all* of these:
 aliases.update(dict(
     gui='TerminalIPythonApp.gui',
     pylab='TerminalIPythonApp.pylab',
 ))
 
 #-----------------------------------------------------------------------------
 # Main classes and functions
 #-----------------------------------------------------------------------------
 
-examples = """
-ipython --pylab            # start in pylab mode
-ipython --pylab=qt         # start in pylab mode with the qt4 backend
-ipython --log_level=DEBUG  # set logging to DEBUG
-ipython --profile=foo      # start with profile foo
-ipython qtconsole          # start the qtconsole GUI application
-ipython profile -h         # show the help string for the profile subcmd
-ipython qtconsole -h       # show the help string for the qtconsole subcmd
-"""
 
 class TerminalIPythonApp(BaseIPythonApplication, InteractiveShellApp):
     name = u'ipython'
     description = usage.cl_usage
     default_config_file_name = default_config_file_name
     crash_handler_class = IPAppCrashHandler
-    examples = examples
+    examples = _examples
 
     flags = Dict(flags)
     aliases = Dict(aliases)
     classes = [InteractiveShellApp, TerminalInteractiveShell, ProfileDir, PlainTextFormatter]
     subcommands = Dict(dict(
         qtconsole=('IPython.frontend.qt.console.qtconsoleapp.IPythonQtConsoleApp',
             """Launch the IPython Qt Console."""
         ),
         profile = ("IPython.core.profileapp.ProfileApp",
             "Create and manage IPython profiles.")
     ))
     
     # *do* autocreate requested profile, but don't create the config file.
     auto_create=Bool(True)
     # configurables
     ignore_old_config=Bool(False, config=True,
         help="Suppress warning messages about legacy config files"
     )
     quick = Bool(False, config=True,
         help="""Start IPython quickly by skipping the loading of config files."""
     )
     def _quick_changed(self, name, old, new):
         if new:
             self.load_config_file = lambda *a, **kw: None
             self.ignore_old_config=True
 
     gui = CaselessStrEnum(('qt','wx','gtk'), config=True,
         help="Enable GUI event loop integration ('qt', 'wx', 'gtk')."
     )
     pylab = CaselessStrEnum(['tk', 'qt', 'wx', 'gtk', 'osx', 'auto'],
         config=True,
         help="""Pre-load matplotlib and numpy for interactive use,
         selecting a particular matplotlib backend and loop integration.
         """
     )
     display_banner = Bool(True, config=True,
         help="Whether to display a banner upon starting IPython."
     )
 
     # if there is code of files to run from the cmd line, don't interact
     # unless the --i flag (App.force_interact) is true.
     force_interact = Bool(False, config=True,
         help="""If a command or file is given via the command-line,
         e.g. 'ipython foo.py"""
     )
     def _force_interact_changed(self, name, old, new):
         if new:
             self.interact = True
     
     def _file_to_run_changed(self, name, old, new):
         if new and not self.force_interact:
                 self.interact = False
     _code_to_run_changed = _file_to_run_changed
 
     # internal, not-configurable
     interact=Bool(True)
 
 
     def parse_command_line(self, argv=None):
         """override to allow old '-pylab' flag with deprecation warning"""
         argv = sys.argv[1:] if argv is None else argv
         
         try:
             idx = argv.index('-pylab')
         except ValueError:
             # `-pylab` not given, proceed as normal
             pass
         else:
             # deprecated `-pylab` given,
             # warn and transform into current syntax
             argv = list(argv) # copy, don't clobber
             warn.warn("`-pylab` flag has been deprecated.\n"
             "    Use `--pylab` instead, or `--pylab=foo` to specify a backend.")
             sub = '--pylab'
             if len(argv) > idx+1:
                 # check for gui arg, as in '-pylab qt'
                 gui = argv[idx+1]
                 if gui in ('wx', 'qt', 'qt4', 'gtk', 'auto'):
                     sub = '--pylab='+gui
                     argv.pop(idx+1)
             argv[idx] = sub
         
         return super(TerminalIPythonApp, self).parse_command_line(argv)
 
     def initialize(self, argv=None):
         """Do actions after construct, but before starting the app."""
         super(TerminalIPythonApp, self).initialize(argv)
         if self.subapp is not None:
             # don't bother initializing further, starting subapp
             return
         if not self.ignore_old_config:
             check_for_old_config(self.ipython_dir)
         # print self.extra_args
         if self.extra_args:
             self.file_to_run = self.extra_args[0]
         # create the shell
         self.init_shell()
         # and draw the banner
         self.init_banner()
         # Now a variety of things that happen after the banner is printed.
         self.init_gui_pylab()
         self.init_extensions()
         self.init_code()
 
     def init_shell(self):
         """initialize the InteractiveShell instance"""
         # 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.
         # 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 = TerminalInteractiveShell.instance(config=self.config,
                         display_banner=False, profile_dir=self.profile_dir,
                         ipython_dir=self.ipython_dir)
 
     def init_banner(self):
         """optionally display the banner"""
         if self.display_banner and self.interact:
             self.shell.show_banner()
         # Make sure there is a space below the banner.
         if self.log_level <= logging.INFO: print
 
 
     def init_gui_pylab(self):
         """Enable GUI event loop integration, taking pylab into account."""
         gui = self.gui
 
         # Using `pylab` will also require gui activation, though which toolkit
         # to use may be chosen automatically based on mpl configuration.
         if self.pylab:
             activate = self.shell.enable_pylab
             if self.pylab == 'auto':
                 gui = None
             else:
                 gui = self.pylab
         else:
             # Enable only GUI integration, no pylab
             activate = inputhook.enable_gui
 
         if gui or self.pylab:
             try:
                 self.log.info("Enabling GUI event loop integration, "
                               "toolkit=%s, pylab=%s" % (gui, self.pylab) )
                 activate(gui)
             except:
                 self.log.warn("Error in enabling GUI event loop integration:")
                 self.shell.showtraceback()
 
     def start(self):
         if self.subapp is not None:
             return self.subapp.start()
         # perform any prexec steps:
         if self.interact:
             self.log.debug("Starting IPython's mainloop...")
             self.shell.mainloop()
         else:
             self.log.debug("IPython not interactive...")
 
 
 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()
     profile_dir = os.path.join(ipython_dir, 'profile_default')
     cl = PyFileConfigLoader(default_config_file_name, profile_dir)
     try:
         config = cl.load_config()
     except IOError:
         # no config found
         config = Config()
     return config
 
 
 def launch_new_instance():
     """Create and run a full blown IPython instance"""
     app = TerminalIPythonApp.instance()
     app.initialize()
     app.start()
 
 
 if __name__ == '__main__':
     launch_new_instance()
 

IPython/parallel/apps/ipclusterapp.py

@@ -1,459 +1,482 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The ipcluster application.
 
 Authors:
 
 * Brian Granger
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  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 errno
 import logging
 import os
 import re
 import signal
 
 from subprocess import check_call, CalledProcessError, PIPE
 import zmq
 from zmq.eventloop import ioloop
 
 from IPython.config.application import Application, boolean_flag
 from IPython.config.loader import Config
 from IPython.core.application import BaseIPythonApplication
 from IPython.core.profiledir import ProfileDir
 from IPython.utils.daemonize import daemonize
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import (Int, Unicode, Bool, CFloat, Dict, List, 
                                         DottedObjectName)
 
 from IPython.parallel.apps.baseapp import (
     BaseParallelApplication,
     PIDFileError,
     base_flags, base_aliases
 )
 
 
 #-----------------------------------------------------------------------------
 # Module level variables
 #-----------------------------------------------------------------------------
 
 
 default_config_file_name = u'ipcluster_config.py'
 
 
 _description = """Start an IPython cluster for parallel computing.
 
 An IPython cluster consists of 1 controller and 1 or more engines.
 This command automates the startup of these processes using a wide
 range of startup methods (SSH, local processes, PBS, mpiexec,
 Windows HPC Server 2008). To start a cluster with 4 engines on your
-local host simply do 'ipcluster start n=4'. For more complex usage
-you will typically do 'ipcluster create profile=mycluster', then edit
-configuration files, followed by 'ipcluster start profile=mycluster n=4'.
+local host simply do 'ipcluster start --n=4'. For more complex usage
+you will typically do 'ipython create mycluster --parallel', then edit
+configuration files, followed by 'ipcluster start --profile=mycluster --n=4'.
+"""
+
+_main_examples = """
+ipcluster start -h    # show the help string for the start subcmd
+ipcluster stop -h     # show the help string for the stop subcmd
+ipcluster engines -h  # show the help string for the engines subcmd
+"""
+
+_start_examples = """
+ipython profile create mycluster --parallel # create mycluster profile
+ipcluster start --profile=mycluster --n=4   # start mycluster with 4 nodes
+"""
+
+_stop_examples = """
+ipcluster stop --profile=mycluster  # stop a running cluster by profile name
+"""
+
+_engines_examples = """
+ipcluster engines --profile=mycluster --n=4  # start 4 engines only
 """
 
 
 # Exit codes for ipcluster
 
 # This will be the exit code if the ipcluster appears to be running because
 # a .pid file exists
 ALREADY_STARTED = 10
 
 
 # This will be the exit code if ipcluster stop is run, but there is not .pid
 # file to be found.
 ALREADY_STOPPED = 11
 
 # This will be the exit code if ipcluster engines is run, but there is not .pid
 # file to be found.
 NO_CLUSTER = 12
 
 
 #-----------------------------------------------------------------------------
 # Main application
 #-----------------------------------------------------------------------------
 start_help = """Start an IPython cluster for parallel computing
 
 Start an ipython cluster by its profile name or cluster
 directory. Cluster directories contain configuration, log and
 security related files and are named using the convention
 'profile_<name>' and should be creating using the 'start'
 subcommand of 'ipcluster'. If your cluster directory is in 
 the cwd or the ipython directory, you can simply refer to it
 using its profile name, 'ipcluster start n=4 profile=<profile>`,
 otherwise use the 'profile_dir' option.
 """
 stop_help = """Stop a running IPython cluster
 
 Stop a running ipython cluster by its profile name or cluster
 directory. Cluster directories are named using the convention
 'profile_<name>'. If your cluster directory is in 
 the cwd or the ipython directory, you can simply refer to it
 using its profile name, 'ipcluster stop profile=<profile>`, otherwise
 use the 'profile_dir' option.
 """
 engines_help = """Start engines connected to an existing IPython cluster
 
 Start one or more engines to connect to an existing Cluster
 by profile name or cluster directory.
 Cluster directories contain configuration, log and
 security related files and are named using the convention
 'profile_<name>' and should be creating using the 'start'
 subcommand of 'ipcluster'. If your cluster directory is in 
 the cwd or the ipython directory, you can simply refer to it
 using its profile name, 'ipcluster engines n=4 profile=<profile>`,
 otherwise use the 'profile_dir' option.
 """
 stop_aliases = dict(
     signal='IPClusterStop.signal',
 )
 stop_aliases.update(base_aliases)
 
 class IPClusterStop(BaseParallelApplication):
     name = u'ipcluster'
     description = stop_help
+    examples = _stop_examples
     config_file_name = Unicode(default_config_file_name)
     
     signal = Int(signal.SIGINT, config=True,
         help="signal to use for stopping processes.")
         
     aliases = Dict(stop_aliases)
     
     def start(self):
         """Start the app for the stop subcommand."""
         try:
             pid = self.get_pid_from_file()
         except PIDFileError:
             self.log.critical(
                 'Could not read pid file, cluster is probably not running.'
             )
             # Here I exit with a unusual exit status that other processes
             # can watch for to learn how I existed.
             self.remove_pid_file()
             self.exit(ALREADY_STOPPED)
         
         if not self.check_pid(pid):
             self.log.critical(
                 'Cluster [pid=%r] is not running.' % pid
             )
             self.remove_pid_file()
             # Here I exit with a unusual exit status that other processes
             # can watch for to learn how I existed.
             self.exit(ALREADY_STOPPED)
             
         elif os.name=='posix':
             sig = self.signal
             self.log.info(
                 "Stopping cluster [pid=%r] with [signal=%r]" % (pid, sig)
             )
             try:
                 os.kill(pid, sig)
             except OSError:
                 self.log.error("Stopping cluster failed, assuming already dead.",
                     exc_info=True)
                 self.remove_pid_file()
         elif os.name=='nt':
             try:
                 # kill the whole tree
                 p = check_call(['taskkill', '-pid', str(pid), '-t', '-f'], stdout=PIPE,stderr=PIPE)
             except (CalledProcessError, OSError):
                 self.log.error("Stopping cluster failed, assuming already dead.",
                     exc_info=True)
             self.remove_pid_file()
     
 engine_aliases = {}
 engine_aliases.update(base_aliases)
 engine_aliases.update(dict(
     n='IPClusterEngines.n',
     engines = 'IPClusterEngines.engine_launcher_class',
     daemonize = 'IPClusterEngines.daemonize',
 ))
 engine_flags = {}
 engine_flags.update(base_flags)
 
 engine_flags.update(dict(
     daemonize=(
         {'IPClusterEngines' : {'daemonize' : True}},
         """run the cluster into the background (not available on Windows)""",
     )
 ))
 class IPClusterEngines(BaseParallelApplication):
 
     name = u'ipcluster'
     description = engines_help
+    examples = _engines_examples
     usage = None
     config_file_name = Unicode(default_config_file_name)
     default_log_level = logging.INFO
     classes = List()
     def _classes_default(self):
         from IPython.parallel.apps import launcher
         launchers = launcher.all_launchers
         eslaunchers = [ l for l in launchers if 'EngineSet' in l.__name__]
         return [ProfileDir]+eslaunchers
     
     n = Int(2, config=True,
         help="The number of engines to start.")
 
     engine_launcher_class = DottedObjectName('LocalEngineSetLauncher',
         config=True,
         help="The class for launching a set of Engines."
         )
     daemonize = Bool(False, config=True,
         help="""Daemonize the ipcluster program. This implies --log-to-file.
         Not available on Windows.
         """)
 
     def _daemonize_changed(self, name, old, new):
         if new:
             self.log_to_file = True
 
     aliases = Dict(engine_aliases)
     flags = Dict(engine_flags)
     _stopping = False
 
     def initialize(self, argv=None):
         super(IPClusterEngines, self).initialize(argv)
         self.init_signal()
         self.init_launchers()
     
     def init_launchers(self):
         self.engine_launcher = self.build_launcher(self.engine_launcher_class)
         self.engine_launcher.on_stop(lambda r: self.loop.stop())
     
     def init_signal(self):
         # Setup signals
         signal.signal(signal.SIGINT, self.sigint_handler)
     
     def build_launcher(self, clsname):
         """import and instantiate a Launcher based on importstring"""
         if '.' not in clsname:
             # not a module, presume it's the raw name in apps.launcher
             clsname = 'IPython.parallel.apps.launcher.'+clsname
         # print repr(clsname)
         klass = import_item(clsname)
 
         launcher = klass(
             work_dir=self.profile_dir.location, config=self.config, log=self.log
         )
         return launcher
     
     def start_engines(self):
         self.log.info("Starting %i engines"%self.n)
         self.engine_launcher.start(
             self.n,
             self.profile_dir.location
         )
 
     def stop_engines(self):
         self.log.info("Stopping Engines...")
         if self.engine_launcher.running:
             d = self.engine_launcher.stop()
             return d
         else:
             return None
 
     def stop_launchers(self, r=None):
         if not self._stopping:
             self._stopping = True
             self.log.error("IPython cluster: stopping")
             self.stop_engines()
             # Wait a few seconds to let things shut down.
             dc = ioloop.DelayedCallback(self.loop.stop, 4000, self.loop)
             dc.start()
 
     def sigint_handler(self, signum, frame):
         self.log.debug("SIGINT received, stopping launchers...")
         self.stop_launchers()
         
     def start_logging(self):
         # Remove old log files of the controller and engine
         if self.clean_logs:
             log_dir = self.profile_dir.log_dir
             for f in os.listdir(log_dir):
                 if re.match(r'ip(engine|controller)z-\d+\.(log|err|out)',f):
                     os.remove(os.path.join(log_dir, f))
         # This will remove old log files for ipcluster itself
         # super(IPBaseParallelApplication, self).start_logging()
 
     def start(self):
         """Start the app for the engines subcommand."""
         self.log.info("IPython cluster: started")
         # First see if the cluster is already running
         
         # Now log and daemonize
         self.log.info(
             'Starting engines with [daemon=%r]' % self.daemonize
         )
         # TODO: Get daemonize working on Windows or as a Windows Server.
         if self.daemonize:
             if os.name=='posix':
                 daemonize()
 
         dc = ioloop.DelayedCallback(self.start_engines, 0, self.loop)
         dc.start()
         # Now write the new pid file AFTER our new forked pid is active.
         # self.write_pid_file()
         try:
             self.loop.start()
         except KeyboardInterrupt:
             pass
         except zmq.ZMQError as e:
             if e.errno == errno.EINTR:
                 pass
             else:
                 raise
 
 start_aliases = {}
 start_aliases.update(engine_aliases)
 start_aliases.update(dict(
     delay='IPClusterStart.delay',
     controller = 'IPClusterStart.controller_launcher_class',
 ))
 start_aliases['clean-logs'] = 'IPClusterStart.clean_logs'
 
 class IPClusterStart(IPClusterEngines):
 
     name = u'ipcluster'
     description = start_help
+    examples = _start_examples
     default_log_level = logging.INFO
     auto_create = Bool(True, config=True,
         help="whether to create the profile_dir if it doesn't exist")
     classes = List()
     def _classes_default(self,):
         from IPython.parallel.apps import launcher
         return [ProfileDir] + [IPClusterEngines] + launcher.all_launchers
     
     clean_logs = Bool(True, config=True, 
         help="whether to cleanup old logs before starting")
 
     delay = CFloat(1., config=True,
         help="delay (in s) between starting the controller and the engines")
 
     controller_launcher_class = DottedObjectName('LocalControllerLauncher',
         config=True,
         help="The class for launching a Controller."
         )
     reset = Bool(False, config=True,
         help="Whether to reset config files as part of '--create'."
         )
     
     # flags = Dict(flags)
     aliases = Dict(start_aliases)
 
     def init_launchers(self):
         self.controller_launcher = self.build_launcher(self.controller_launcher_class)
         self.engine_launcher = self.build_launcher(self.engine_launcher_class)
         self.controller_launcher.on_stop(self.stop_launchers)
     
     def start_controller(self):
         self.controller_launcher.start(
             self.profile_dir.location
         )
         
     def stop_controller(self):
         # self.log.info("In stop_controller")
         if self.controller_launcher and self.controller_launcher.running:
             return self.controller_launcher.stop()
 
     def stop_launchers(self, r=None):
         if not self._stopping:
             self.stop_controller()
             super(IPClusterStart, self).stop_launchers()
 
     def start(self):
         """Start the app for the start subcommand."""
         # First see if the cluster is already running
         try:
             pid = self.get_pid_from_file()
         except PIDFileError:
             pass
         else:
             if self.check_pid(pid):
                 self.log.critical(
                     'Cluster is already running with [pid=%s]. '
                     'use "ipcluster stop" to stop the cluster.' % pid
                 )
                 # Here I exit with a unusual exit status that other processes
                 # can watch for to learn how I existed.
                 self.exit(ALREADY_STARTED)
             else:
                 self.remove_pid_file()
                 
 
         # Now log and daemonize
         self.log.info(
             'Starting ipcluster with [daemon=%r]' % self.daemonize
         )
         # TODO: Get daemonize working on Windows or as a Windows Server.
         if self.daemonize:
             if os.name=='posix':
                 daemonize()
 
         dc = ioloop.DelayedCallback(self.start_controller, 0, self.loop)
         dc.start()
         dc = ioloop.DelayedCallback(self.start_engines, 1000*self.delay, self.loop)
         dc.start()
         # Now write the new pid file AFTER our new forked pid is active.
         self.write_pid_file()
         try:
             self.loop.start()
         except KeyboardInterrupt:
             pass
         except zmq.ZMQError as e:
             if e.errno == errno.EINTR:
                 pass
             else:
                 raise
         finally:
             self.remove_pid_file()
 
 base='IPython.parallel.apps.ipclusterapp.IPCluster'
 
 class IPClusterApp(Application):
     name = u'ipcluster'
     description = _description
+    examples = _main_examples
     
     subcommands = {
                 'start' : (base+'Start', start_help),
                 'stop' : (base+'Stop', stop_help),
                 'engines' : (base+'Engines', engines_help),
     }
     
     # no aliases or flags for parent App
     aliases = Dict()
     flags = Dict()
     
     def start(self):
         if self.subapp is None:
             print "No subcommand specified. Must specify one of: %s"%(self.subcommands.keys())
             print
             self.print_description()
             self.print_subcommands()
             self.exit(1)
         else:
             return self.subapp.start()
 
 def launch_new_instance():
     """Create and run the IPython cluster."""
     app = IPClusterApp.instance()
     app.initialize()
     app.start()
 
 
 if __name__ == '__main__':
     launch_new_instance()
 

IPython/parallel/apps/ipcontrollerapp.py

@@ -1,420 +1,425 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The IPython controller application.
 
 Authors:
 
 * Brian Granger
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  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 with_statement
 
 import os
 import socket
 import stat
 import sys
 import uuid
 
 from multiprocessing import Process
 
 import zmq
 from zmq.devices import ProcessMonitoredQueue
 from zmq.log.handlers import PUBHandler
 from zmq.utils import jsonapi as json
 
 from IPython.config.application import boolean_flag
 from IPython.core.profiledir import ProfileDir
 
 from IPython.parallel.apps.baseapp import (
     BaseParallelApplication,
     base_aliases,
     base_flags,
 )
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import Instance, Unicode, Bool, List, Dict
 
 # from IPython.parallel.controller.controller import ControllerFactory
 from IPython.zmq.session import Session
 from IPython.parallel.controller.heartmonitor import HeartMonitor
 from IPython.parallel.controller.hub import HubFactory
 from IPython.parallel.controller.scheduler import TaskScheduler,launch_scheduler
 from IPython.parallel.controller.sqlitedb import SQLiteDB
 
 from IPython.parallel.util import signal_children, split_url, asbytes
 
 # conditional import of MongoDB backend class
 
 try:
     from IPython.parallel.controller.mongodb import MongoDB
 except ImportError:
     maybe_mongo = []
 else:
     maybe_mongo = [MongoDB]
 
 
 #-----------------------------------------------------------------------------
 # Module level variables
 #-----------------------------------------------------------------------------
 
 
 #: The default config file name for this application
 default_config_file_name = u'ipcontroller_config.py'
 
 
 _description = """Start the IPython controller for parallel computing.
 
 The IPython controller provides a gateway between the IPython engines and
 clients. The controller needs to be started before the engines and can be
 configured using command line options or using a cluster directory. Cluster
 directories contain config, log and security files and are usually located in
 your ipython directory and named as "profile_name". See the `profile`
 and `profile_dir` options for details.
 """
 
-
+_examples = """
+ipcontroller --ip=192.168.0.1 --port=1000  # listen on ip, port for engines
+ipcontroller --scheme=pure  # use the pure zeromq scheduler
+"""
 
 
 #-----------------------------------------------------------------------------
 # The main application
 #-----------------------------------------------------------------------------
 flags = {}
 flags.update(base_flags)
 flags.update({
     'usethreads' : ( {'IPControllerApp' : {'use_threads' : True}},
                     'Use threads instead of processes for the schedulers'),
     'sqlitedb' : ({'HubFactory' : {'db_class' : 'IPython.parallel.controller.sqlitedb.SQLiteDB'}},
                     'use the SQLiteDB backend'),
     'mongodb' : ({'HubFactory' : {'db_class' : 'IPython.parallel.controller.mongodb.MongoDB'}},
                     'use the MongoDB backend'),
     'dictdb' : ({'HubFactory' : {'db_class' : 'IPython.parallel.controller.dictdb.DictDB'}},
                     'use the in-memory DictDB backend'),
     'reuse' : ({'IPControllerApp' : {'reuse_files' : True}},
                     'reuse existing json connection files')
 })
 
 flags.update(boolean_flag('secure', 'IPControllerApp.secure',
     "Use HMAC digests for authentication of messages.",
     "Don't authenticate messages."
 ))
 aliases = dict(
     secure = 'IPControllerApp.secure',
     ssh = 'IPControllerApp.ssh_server',
     location = 'IPControllerApp.location',
 
     ident = 'Session.session',
     user = 'Session.username',
     keyfile = 'Session.keyfile',
 
     url = 'HubFactory.url',
     ip = 'HubFactory.ip',
     transport = 'HubFactory.transport',
     port = 'HubFactory.regport',
 
     ping = 'HeartMonitor.period',
 
     scheme = 'TaskScheduler.scheme_name',
     hwm = 'TaskScheduler.hwm',
 )
 aliases.update(base_aliases)
 
+
 class IPControllerApp(BaseParallelApplication):
 
     name = u'ipcontroller'
     description = _description
+    examples = _examples
     config_file_name = Unicode(default_config_file_name)
     classes = [ProfileDir, Session, HubFactory, TaskScheduler, HeartMonitor, SQLiteDB] + maybe_mongo
     
     # change default to True
     auto_create = Bool(True, config=True,
         help="""Whether to create profile dir if it doesn't exist.""")
     
     reuse_files = Bool(False, config=True,
         help='Whether to reuse existing json connection files.'
     )
     secure = Bool(True, config=True,
         help='Whether to use HMAC digests for extra message authentication.'
     )
     ssh_server = Unicode(u'', config=True,
         help="""ssh url for clients to use when connecting to the Controller
         processes. It should be of the form: [user@]server[:port]. The
         Controller's listening addresses must be accessible from the ssh server""",
     )
     location = Unicode(u'', config=True,
         help="""The external IP or domain name of the Controller, used for disambiguating
         engine and client connections.""",
     )
     import_statements = List([], config=True,
         help="import statements to be run at startup.  Necessary in some environments"
     )
 
     use_threads = Bool(False, config=True,
         help='Use threads instead of processes for the schedulers',
         )
 
     # internal
     children = List()
     mq_class = Unicode('zmq.devices.ProcessMonitoredQueue')
 
     def _use_threads_changed(self, name, old, new):
         self.mq_class = 'zmq.devices.%sMonitoredQueue'%('Thread' if new else 'Process')
 
     aliases = Dict(aliases)
     flags = Dict(flags)
     
 
     def save_connection_dict(self, fname, cdict):
         """save a connection dict to json file."""
         c = self.config
         url = cdict['url']
         location = cdict['location']
         if not location:
             try:
                 proto,ip,port = split_url(url)
             except AssertionError:
                 pass
             else:
                 location = socket.gethostbyname_ex(socket.gethostname())[2][-1]
             cdict['location'] = location
         fname = os.path.join(self.profile_dir.security_dir, fname)
         with open(fname, 'wb') as f:
             f.write(json.dumps(cdict, indent=2))
         os.chmod(fname, stat.S_IRUSR|stat.S_IWUSR)
     
     def load_config_from_json(self):
         """load config from existing json connector files."""
         c = self.config
         # load from engine config
         with open(os.path.join(self.profile_dir.security_dir, 'ipcontroller-engine.json')) as f:
             cfg = json.loads(f.read())
         key = c.Session.key = asbytes(cfg['exec_key'])
         xport,addr = cfg['url'].split('://')
         c.HubFactory.engine_transport = xport
         ip,ports = addr.split(':')
         c.HubFactory.engine_ip = ip
         c.HubFactory.regport = int(ports)
         self.location = cfg['location']
         # load client config
         with open(os.path.join(self.profile_dir.security_dir, 'ipcontroller-client.json')) as f:
             cfg = json.loads(f.read())
         assert key == cfg['exec_key'], "exec_key mismatch between engine and client keys"
         xport,addr = cfg['url'].split('://')
         c.HubFactory.client_transport = xport
         ip,ports = addr.split(':')
         c.HubFactory.client_ip = ip
         self.ssh_server = cfg['ssh']
         assert int(ports) == c.HubFactory.regport, "regport mismatch"
     
     def init_hub(self):
         c = self.config
         
         self.do_import_statements()
         reusing = self.reuse_files
         if reusing:
             try:
                 self.load_config_from_json()
             except (AssertionError,IOError):
                 reusing=False
         # check again, because reusing may have failed:
         if reusing:
             pass
         elif self.secure:
             key = str(uuid.uuid4())
             # keyfile = os.path.join(self.profile_dir.security_dir, self.exec_key)
             # with open(keyfile, 'w') as f:
             #     f.write(key)
             # os.chmod(keyfile, stat.S_IRUSR|stat.S_IWUSR)
             c.Session.key = asbytes(key)
         else:
             key = c.Session.key = b''
         
         try:
             self.factory = HubFactory(config=c, log=self.log)
             # self.start_logging()
             self.factory.init_hub()
         except:
             self.log.error("Couldn't construct the Controller", exc_info=True)
             self.exit(1)
         
         if not reusing:
             # save to new json config files
             f = self.factory
             cdict = {'exec_key' : key,
                     'ssh' : self.ssh_server,
                     'url' : "%s://%s:%s"%(f.client_transport, f.client_ip, f.regport),
                     'location' : self.location
                     }
             self.save_connection_dict('ipcontroller-client.json', cdict)
             edict = cdict
             edict['url']="%s://%s:%s"%((f.client_transport, f.client_ip, f.regport))
             self.save_connection_dict('ipcontroller-engine.json', edict)
 
     #
     def init_schedulers(self):
         children = self.children
         mq = import_item(str(self.mq_class))
         
         hub = self.factory
         # maybe_inproc = 'inproc://monitor' if self.use_threads else self.monitor_url
         # IOPub relay (in a Process)
         q = mq(zmq.PUB, zmq.SUB, zmq.PUB, b'N/A',b'iopub')
         q.bind_in(hub.client_info['iopub'])
         q.bind_out(hub.engine_info['iopub'])
         q.setsockopt_out(zmq.SUBSCRIBE, b'')
         q.connect_mon(hub.monitor_url)
         q.daemon=True
         children.append(q)
 
         # Multiplexer Queue (in a Process)
         q = mq(zmq.XREP, zmq.XREP, zmq.PUB, b'in', b'out')
         q.bind_in(hub.client_info['mux'])
         q.setsockopt_in(zmq.IDENTITY, b'mux')
         q.bind_out(hub.engine_info['mux'])
         q.connect_mon(hub.monitor_url)
         q.daemon=True
         children.append(q)
 
         # Control Queue (in a Process)
         q = mq(zmq.XREP, zmq.XREP, zmq.PUB, b'incontrol', b'outcontrol')
         q.bind_in(hub.client_info['control'])
         q.setsockopt_in(zmq.IDENTITY, b'control')
         q.bind_out(hub.engine_info['control'])
         q.connect_mon(hub.monitor_url)
         q.daemon=True
         children.append(q)
         try:
             scheme = self.config.TaskScheduler.scheme_name
         except AttributeError:
             scheme = TaskScheduler.scheme_name.get_default_value()
         # Task Queue (in a Process)
         if scheme == 'pure':
             self.log.warn("task::using pure XREQ Task scheduler")
             q = mq(zmq.XREP, zmq.XREQ, zmq.PUB, b'intask', b'outtask')
             # q.setsockopt_out(zmq.HWM, hub.hwm)
             q.bind_in(hub.client_info['task'][1])
             q.setsockopt_in(zmq.IDENTITY, b'task')
             q.bind_out(hub.engine_info['task'])
             q.connect_mon(hub.monitor_url)
             q.daemon=True
             children.append(q)
         elif scheme == 'none':
             self.log.warn("task::using no Task scheduler")
 
         else:
             self.log.info("task::using Python %s Task scheduler"%scheme)
             sargs = (hub.client_info['task'][1], hub.engine_info['task'],
                                 hub.monitor_url, hub.client_info['notification'])
             kwargs = dict(logname='scheduler', loglevel=self.log_level,
                             log_url = self.log_url, config=dict(self.config))
             if 'Process' in self.mq_class:
                 # run the Python scheduler in a Process
                 q = Process(target=launch_scheduler, args=sargs, kwargs=kwargs)
                 q.daemon=True
                 children.append(q)
             else:
                 # single-threaded Controller
                 kwargs['in_thread'] = True
                 launch_scheduler(*sargs, **kwargs)
 
     
     def save_urls(self):
         """save the registration urls to files."""
         c = self.config
         
         sec_dir = self.profile_dir.security_dir
         cf = self.factory
         
         with open(os.path.join(sec_dir, 'ipcontroller-engine.url'), 'w') as f:
             f.write("%s://%s:%s"%(cf.engine_transport, cf.engine_ip, cf.regport))
         
         with open(os.path.join(sec_dir, 'ipcontroller-client.url'), 'w') as f:
             f.write("%s://%s:%s"%(cf.client_transport, cf.client_ip, cf.regport))
         
     
     def do_import_statements(self):
         statements = self.import_statements
         for s in statements:
             try:
                 self.log.msg("Executing statement: '%s'" % s)
                 exec s in globals(), locals()
             except:
                 self.log.msg("Error running statement: %s" % s)
 
     def forward_logging(self):
         if self.log_url:
             self.log.info("Forwarding logging to %s"%self.log_url)
             context = zmq.Context.instance()
             lsock = context.socket(zmq.PUB)
             lsock.connect(self.log_url)
             handler = PUBHandler(lsock)
             self.log.removeHandler(self._log_handler)
             handler.root_topic = 'controller'
             handler.setLevel(self.log_level)
             self.log.addHandler(handler)
             self._log_handler = handler
     # #
     
     def initialize(self, argv=None):
         super(IPControllerApp, self).initialize(argv)
         self.forward_logging()
         self.init_hub()
         self.init_schedulers()
     
     def start(self):
         # Start the subprocesses:
         self.factory.start()
         child_procs = []
         for child in self.children:
             child.start()
             if isinstance(child, ProcessMonitoredQueue):
                 child_procs.append(child.launcher)
             elif isinstance(child, Process):
                 child_procs.append(child)
         if child_procs:
             signal_children(child_procs)
 
         self.write_pid_file(overwrite=True)
 
         try:
             self.factory.loop.start()
         except KeyboardInterrupt:
             self.log.critical("Interrupted, Exiting...\n")
             
 
 
 def launch_new_instance():
     """Create and run the IPython controller"""
     if sys.platform == 'win32':
         # make sure we don't get called from a multiprocessing subprocess
         # this can result in infinite Controllers being started on Windows
         # which doesn't have a proper fork, so multiprocessing is wonky
         
         # this only comes up when IPython has been installed using vanilla
         # setuptools, and *not* distribute.
         import multiprocessing
         p = multiprocessing.current_process()
         # the main process has name 'MainProcess'
         # subprocesses will have names like 'Process-1'
         if p.name != 'MainProcess':
             # we are a subprocess, don't start another Controller!
             return
     app = IPControllerApp.instance()
     app.initialize()
     app.start()
 
 
 if __name__ == '__main__':
     launch_new_instance()

IPython/parallel/apps/ipengineapp.py

@@ -1,301 +1,307 b''
 #!/usr/bin/env python
 # encoding: utf-8
 """
 The IPython engine application
 
 Authors:
 
 * Brian Granger
 * MinRK
 
 """
 
 #-----------------------------------------------------------------------------
 #  Copyright (C) 2008-2011  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 json
 import os
 import sys
 import time
 
 import zmq
 from zmq.eventloop import ioloop
 
 from IPython.core.profiledir import ProfileDir
 from IPython.parallel.apps.baseapp import (
     BaseParallelApplication,
     base_aliases,
     base_flags,
 )
 from IPython.zmq.log import EnginePUBHandler
 
 from IPython.config.configurable import Configurable
 from IPython.zmq.session import Session
 from IPython.parallel.engine.engine import EngineFactory
 from IPython.parallel.engine.streamkernel import Kernel
 from IPython.parallel.util import disambiguate_url, asbytes
 
 from IPython.utils.importstring import import_item
 from IPython.utils.traitlets import Bool, Unicode, Dict, List, Float
 
 
 #-----------------------------------------------------------------------------
 # Module level variables
 #-----------------------------------------------------------------------------
 
 #: The default config file name for this application
 default_config_file_name = u'ipengine_config.py'
 
 _description = """Start an IPython engine for parallel computing.
 
 IPython engines run in parallel and perform computations on behalf of a client
 and controller. A controller needs to be started before the engines. The
 engine can be configured using command line options or using a cluster
 directory. Cluster directories contain config, log and security files and are
 usually located in your ipython directory and named as "profile_name".
 See the `profile` and `profile_dir` options for details.
 """
 
+_examples = """
+ipengine --ip=192.168.0.1 --port=1000     # connect to hub at ip and port
+ipengine --log_to_file --log_level=DEBUG  # log to a file with DEBUG verbosity
+"""
 
 #-----------------------------------------------------------------------------
 # MPI configuration
 #-----------------------------------------------------------------------------
 
 mpi4py_init = """from mpi4py import MPI as mpi
 mpi.size = mpi.COMM_WORLD.Get_size()
 mpi.rank = mpi.COMM_WORLD.Get_rank()
 """
 
 
 pytrilinos_init = """from PyTrilinos import Epetra
 class SimpleStruct:
 pass
 mpi = SimpleStruct()
 mpi.rank = 0
 mpi.size = 0
 """
 
 class MPI(Configurable):
     """Configurable for MPI initialization"""
     use = Unicode('', config=True,
         help='How to enable MPI (mpi4py, pytrilinos, or empty string to disable).'
         )
 
     def _on_use_changed(self, old, new):
         # load default init script if it's not set
         if not self.init_script:
             self.init_script = self.default_inits.get(new, '')
 
     init_script = Unicode('', config=True,
         help="Initialization code for MPI")
 
     default_inits = Dict({'mpi4py' : mpi4py_init, 'pytrilinos':pytrilinos_init},
         config=True)
 
 
 #-----------------------------------------------------------------------------
 # Main application
 #-----------------------------------------------------------------------------
 aliases = dict(
     file = 'IPEngineApp.url_file',
     c = 'IPEngineApp.startup_command',
     s = 'IPEngineApp.startup_script',
 
     ident = 'Session.session',
     user = 'Session.username',
     keyfile = 'Session.keyfile',
 
     url = 'EngineFactory.url',
     ip = 'EngineFactory.ip',
     transport = 'EngineFactory.transport',
     port = 'EngineFactory.regport',
     location = 'EngineFactory.location',
 
     timeout = 'EngineFactory.timeout',
 
     mpi = 'MPI.use',
 
 )
 aliases.update(base_aliases)
 
+
 class IPEngineApp(BaseParallelApplication):
 
     name = Unicode(u'ipengine')
     description = Unicode(_description)
+    examples = _examples
     config_file_name = Unicode(default_config_file_name)
     classes = List([ProfileDir, Session, EngineFactory, Kernel, MPI])
 
     startup_script = Unicode(u'', config=True,
         help='specify a script to be run at startup')
     startup_command = Unicode('', config=True,
             help='specify a command to be run at startup')
 
     url_file = Unicode(u'', config=True,
         help="""The full location of the file containing the connection information for
         the controller. If this is not given, the file must be in the
         security directory of the cluster directory.  This location is
         resolved using the `profile` or `profile_dir` options.""",
         )
     wait_for_url_file = Float(5, config=True,
         help="""The maximum number of seconds to wait for url_file to exist.
         This is useful for batch-systems and shared-filesystems where the
         controller and engine are started at the same time and it
         may take a moment for the controller to write the connector files.""")
 
     url_file_name = Unicode(u'ipcontroller-engine.json')
     log_url = Unicode('', config=True,
         help="""The URL for the iploggerapp instance, for forwarding
         logging to a central location.""")
 
     aliases = Dict(aliases)
 
     # def find_key_file(self):
     #     """Set the key file.
     # 
     #     Here we don't try to actually see if it exists for is valid as that
     #     is hadled by the connection logic.
     #     """
     #     config = self.master_config
     #     # Find the actual controller key file
     #     if not config.Global.key_file:
     #         try_this = os.path.join(
     #             config.Global.profile_dir, 
     #             config.Global.security_dir,
     #             config.Global.key_file_name
     #         )
     #         config.Global.key_file = try_this
         
     def find_url_file(self):
         """Set the url file.
 
         Here we don't try to actually see if it exists for is valid as that
         is hadled by the connection logic.
         """
         config = self.config
         # Find the actual controller key file
         if not self.url_file:
             self.url_file = os.path.join(
                 self.profile_dir.security_dir,
                 self.url_file_name
             )
     def init_engine(self):
         # This is the working dir by now.
         sys.path.insert(0, '')
         config = self.config
         # print config
         self.find_url_file()
         
         # was the url manually specified?
         keys = set(self.config.EngineFactory.keys())
         keys = keys.union(set(self.config.RegistrationFactory.keys()))
         
         if keys.intersection(set(['ip', 'url', 'port'])):
             # Connection info was specified, don't wait for the file
             url_specified = True
             self.wait_for_url_file = 0
         else:
             url_specified = False
 
         if self.wait_for_url_file and not os.path.exists(self.url_file):
             self.log.warn("url_file %r not found"%self.url_file)
             self.log.warn("Waiting up to %.1f seconds for it to arrive."%self.wait_for_url_file)
             tic = time.time()
             while not os.path.exists(self.url_file) and (time.time()-tic < self.wait_for_url_file):
                 # wait for url_file to exist, for up to 10 seconds
                 time.sleep(0.1)
             
         if os.path.exists(self.url_file):
             self.log.info("Loading url_file %r"%self.url_file)
             with open(self.url_file) as f:
                 d = json.loads(f.read())
             if d['exec_key']:
                 config.Session.key = asbytes(d['exec_key'])
             d['url'] = disambiguate_url(d['url'], d['location'])
             config.EngineFactory.url = d['url']
             config.EngineFactory.location = d['location']
         elif not url_specified:
             self.log.critical("Fatal: url file never arrived: %s"%self.url_file)
             self.exit(1)
         
         
         try:
             exec_lines = config.Kernel.exec_lines
         except AttributeError:
             config.Kernel.exec_lines = []
             exec_lines = config.Kernel.exec_lines
         
         if self.startup_script:
             enc = sys.getfilesystemencoding() or 'utf8'
             cmd="execfile(%r)"%self.startup_script.encode(enc)
             exec_lines.append(cmd)
         if self.startup_command:
             exec_lines.append(self.startup_command)
 
         # Create the underlying shell class and Engine
         # shell_class = import_item(self.master_config.Global.shell_class)
         # print self.config
         try:
             self.engine = EngineFactory(config=config, log=self.log)
         except:
             self.log.error("Couldn't start the Engine", exc_info=True)
             self.exit(1)
         
     def forward_logging(self):
         if self.log_url:
             self.log.info("Forwarding logging to %s"%self.log_url)
             context = self.engine.context
             lsock = context.socket(zmq.PUB)
             lsock.connect(self.log_url)
             self.log.removeHandler(self._log_handler)
             handler = EnginePUBHandler(self.engine, lsock)
             handler.setLevel(self.log_level)
             self.log.addHandler(handler)
             self._log_handler = handler
     #
     def init_mpi(self):
         global mpi
         self.mpi = MPI(config=self.config)
 
         mpi_import_statement = self.mpi.init_script
         if mpi_import_statement:
             try:
                 self.log.info("Initializing MPI:")
                 self.log.info(mpi_import_statement)
                 exec mpi_import_statement in globals()
             except:
                 mpi = None
         else:
             mpi = None
 
     def initialize(self, argv=None):
         super(IPEngineApp, self).initialize(argv)
         self.init_mpi()
         self.init_engine()
         self.forward_logging()
     
     def start(self):
         self.engine.start()
         try:
             self.engine.loop.start()
         except KeyboardInterrupt:
             self.log.critical("Engine Interrupted, shutting down...\n")
 
 
 def launch_new_instance():
     """Create and run the IPython engine"""
     app = IPEngineApp.instance()
     app.initialize()
     app.start()
 
 
 if __name__ == '__main__':
     launch_new_instance()