Adding log module, contains functions for setting up logging.

Also fix potential KeyError in interactive.py.

docs/acquisition.rst

@@ -42,14 +42,7 @@ We will now perform a basic two stage acquisition using the default parameters u
 .. ipython::
 
   @suppress
-  In [2]: import logging, sys
-
-  @suppress
-  In [3]: logging.basicConfig(
-     ...:   level=logging.DEBUG,
-     ...:   stream=sys.stdout,
-     ...:   format="[%(levelname)s] %(name)s: %(message)s"
-     ...: )
+  In [2]: import peregrine.log; peregrine.log.docs_logging_config()
 
   In [2]: res = acq.acquisition(show_progress=False); res
 

docs/index.rst

@@ -19,6 +19,7 @@ User Documentation
 
    installation
    interactive
+   logging
    samples
    acquisition
 

docs/logging.rst

@@ -0,0 +1,22 @@
+==============================
+Logging (:mod:`peregrine.log`)
+==============================
+
+.. currentmodule:: peregrine
+
+Reference / API
+===============
+
+:mod:`peregrine.log` Module
+---------------------------
+
+.. automodule:: peregrine.log
+
+  .. rubric:: Functions
+
+  .. autosummary::
+    :toctree: api
+
+    default_logging_config
+    docs_logging_config
+

peregrine/interactive.py

@@ -17,38 +17,20 @@
 
   from peregrine.interactive import *
 
-:mod:`peregrine.interactive` Functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-:mod:`peregrine.interactive` defines the following functions:
-
-.. currentmodule:: peregrine.interactive
-
-.. autosummary:: configure_logging
-
-Included Functions
-^^^^^^^^^^^^^^^^^^
-
 The following classes, functions and attributes from other modules are
 available in the interactive namespace:
 
 """
 
-def configure_logging():
-  """ Configure python :mod:`logging` for use in an interactive session."""
-  import logging
-  logging.basicConfig(
-    level=logging.DEBUG,
-    format="\033[2K\r%(asctime)s [%(levelname)s] %(name)s: %(message)s"
-  )
-configure_logging()
-
 from peregrine.acquisition import *
 from peregrine.samples import *
 from peregrine.include.generateCAcode import caCodes
 from peregrine.analysis.acquisition import *
 from peregrine.analysis.samples import *
 
+import peregrine.log
+peregrine.log.default_logging_config()
+
 # Some may find this to be in very bad taste but we are going to alter our own
 # docstring to automatically provide a summary of the functions and classes
 # available in the interactive namespace.
@@ -65,7 +47,8 @@ def configure_logging():
       peregrine_items[v.__module__] += [k]
 # Remove items defined here in interactive, we will document them explicitly in
 # the docstring.
-del peregrine_items['peregrine.interactive']
+if 'peregrine.interactive' in peregrine_items:
+  del peregrine_items['peregrine.interactive']
 # Now add autosummaries to our docstring grouping items from the same module
 # together.
 for mod in sorted(peregrine_items.iterkeys()):

peregrine/log.py

@@ -0,0 +1,73 @@
+# Copyright (C) 2012 Swift Navigation Inc.
+#
+# This source is subject to the license found in the file 'LICENSE' which must
+# be be distributed together with this source. All other rights reserved.
+#
+# THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
+# EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
+
+"""
+Peregrine makes extensive use of the python :mod:`logging` module. This module
+contains convenience functions for configuring the :mod:`logging` module for
+various common use scenarios.
+
+"""
+
+import sys
+import logging
+
+def default_logging_config():
+  """
+  Setup default :mod:`logging` configuration.
+
+  A verbose setup outputting all messages including the ``logging.DEBUG`` level
+  to ``stdout``.
+
+  """
+  # Configure logging.
+  # Note: An ANSI escape sequence is used to clear the line in case a
+  # progressbar is running but this won't work in Windows.
+  logging.basicConfig(
+    level=logging.DEBUG,
+    stream=sys.stdout,
+    format="\033[2K\r %(asctime)s [%(levelname)s] %(name)s: %(message)s"
+  )
+
+def docs_logging_config():
+  """
+  Setup :mod:`logging` configuration for use in the documentation.
+
+  For use from within IPython examples in the Sphinx doccumentation. Outputs to
+  ``stdout`` with a simpler format string that doesn't include the time or
+  date.
+
+  This function removes all the existing root handlers before adding its own.
+
+  .. note::
+    Sphinx IPython mode redirects ``sys.stdout`` at some point after modules
+    are loaded. You should call this function after the redirection has
+    occurred otherwise logging output will still end up in the console, not the
+    documentation.
+
+  This function can be called from within a documentation IPython example as
+  follows::
+
+    .. ipython::
+
+      @suppress
+      In [22]: import peregrine.log; peregrine.log.docs_logging_config()
+
+  """
+  # Remove any existing handlers.
+  if len(logging.root.handlers) != 0:
+    for handler in logging.root.handlers:
+      logging.root.removeHandler(handler)
+
+  # Setup our new configuration.
+  logging.basicConfig(
+    level=logging.DEBUG,
+    stream=sys.stdout,
+    format="[%(levelname)s] %(name)s: %(message)s"
+  )
+

peregrine/run.py

@@ -19,17 +19,12 @@
 from peregrine.acquisition import Acquisition, load_acq_results, save_acq_results
 from peregrine.navigation import navigation
 from peregrine.tracking import track
+from peregrine.log import default_logging_config
 
 from initSettings import initSettings
 
 def main():
-  # Configure logging
-  # Note: An ANSI escape sequence is used to clear the line in case a
-  # progressbar is running but this won't work in Windows.
-  logging.basicConfig(
-    level=logging.DEBUG,
-    format="\033[2K\r%(asctime)s [%(levelname)s] %(name)s: %(message)s"
-  )
+  default_logging_config()
 
   # Initialize constants, settings
   settings = initSettings()