IPython/core/application.py

# 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.path import get_ipython_dir, get_ipython_package_dir
from IPython.config.loader import (
    PyFileConfigLoader,
    ArgParseConfigLoader,
    Config,
)

#-----------------------------------------------------------------------------
# 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 the IPython directory
        IPYTHON_DIR, stored as Global.ipython_dir.  This can also be specified
        through the environment variable IPYTHON_DIR.""",
        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.""",
        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.',
        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).""",
        metavar='Global.config_file')),
    )

class Application(object):
    """Load a config, construct components and set them running.

    The configuration of an application can be done via four different Config
    objects, which are loaded and ultimately merged into a single one used from
    that point on by the app.  These are:

    1. default_config: internal defaults, implemented in code.
    2. file_config: read from the filesystem.
    3. command_line_config: read from the system's command line flags.
    4. constructor_config: passed parametrically to the constructor.

    During initialization, 3 is actually read before 2, since at the
    command-line one may override the location of the file to be read.  But the
    above is the order in which the merge is made.

    There is a final config object can be created and passed to the
    constructor: override_config.  If it exists, this completely overrides the
    configs 2-4 above (the default is still used to ensure that all needed
    fields at least are created).  This makes it easier to create
    parametrically (e.g. in testing or sphinx plugins) objects with a known
    configuration, that are unaffected by whatever arguments may be present in
    sys.argv or files in the user's various directories.
    """

    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
    #: internal defaults, implemented in code.
    default_config = None
    #: read from the filesystem
    file_config = None
    #: read from the system's command line flags
    command_line_config = None
    #: passed parametrically to the constructor.
    constructor_config = None
    #: final override, if given supercedes file/command/constructor configs
    override_config = 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

    #: extra arguments computed by the command-line loader
    extra_args = None

    # Private attributes
    _exiting = False
    _initialized = False

    # Class choices for things that will be instantiated at runtime.
    _CrashHandler = crashhandler.CrashHandler

    def __init__(self, argv=None, constructor_config=None, override_config=None):
        self.argv = sys.argv[1:] if argv is None else argv
        self.constructor_config = constructor_config
        self.override_config = override_config
        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):
        """Initialize the application.

        Loads all configuration information and sets all application state, but
        does not start any relevant processing (typically some kind of event
        loop).

        Once this method has been called, the application is flagged as
        initialized and the method becomes a no-op."""
        
        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)

        # Configuration phase
        # Default config (internally hardwired in application code)
        self.create_default_config()
        self.log_default_config()
        self.set_default_config_log_level()

        if self.override_config is None:
            # Command-line config
            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()

        # Find resources needed for filesystem access, using information from
        # the above two
        self.find_ipython_dir()
        self.find_resources()
        self.find_config_file_name()
        self.find_config_file_paths()

        if self.override_config is None:
            # File-based config
            self.pre_load_file_config()
            self.load_file_config()
            self.set_file_config_log_level()
            self.post_load_file_config()
            self.log_file_config()

        # Merge all config objects into a single one the app can then use
        self.merge_configs()
        self.log_master_config()

        # Construction phase
        self.pre_construct()
        self.construct()
        self.post_construct()

        # Done, flag as such and
        self._initialized = True

    def start(self):
        """Start the application."""
        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,
                                    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)
        if self.override_config is None:
            config._merge(self.file_config)
            config._merge(self.command_line_config)
            if self.constructor_config is not None:
                config._merge(self.constructor_config)
        else:
            config._merge(self.override_config)
        # XXX fperez - propose to Brian we rename master_config to simply
        # config, I think this is going to be heavily used in examples and
        # application code and the name is shorter/easier to find/remember.
        # For now, just alias it...
        self.master_config = config
        self.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)