Add logging configuration for the library

Useful in general but inspired by PR #20.

cloudbridge/__init__.py

@@ -1,5 +1,5 @@
+"""Library setup."""
 import logging
-import sys
 
 # Current version of the library
 __version__ = '0.1.1'
@@ -7,15 +7,76 @@ __version__ = '0.1.1'
 
 def get_version():
     """
-    Return a string with the current version of the library (e.g., "0.1.0").
+    Return a string with the current version of the library.
+
+    :rtype: ``string``
+    :return:  Library version (e.g., "0.1.0").
     """
     return __version__
 
 
 def init_logging():
     """
+    Initialize logging for testing.
+
     Temporary workaround for build timeouts by enabling logging to
-    stdout so that travis doesn't think the build has hung.
+    stdout so that Travis doesn't think the build has hung.
     """
-    logging.basicConfig(stream=sys.stdout)
-    logging.getLogger(__name__).setLevel(logging.DEBUG)
+    set_stream_logger(__name__, level=logging.DEBUG)
+
+
+class NullHandler(logging.Handler):
+    """A null handler for the logger."""
+
+    def emit(self, record):
+        """Don't emit a log."""
+        pass
+
+# By default, do not force any logging by the library. If you want to see the
+# log messages in your scripts, add the following to the top of your script:
+#   import cloudbridge
+#   cloudbridge.set_stream_logger(__name__)
+#   OR
+#   cloudbridge.set_file_logger(__name__, '/tmp/cb.log')
+
+default_format_string = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+log = logging.getLogger('cloudbridge')
+log.addHandler(NullHandler())
+
+# Convenience functions to set logging to a particular file or stream
+# To enable either of these by default within CloudBridge, add the following
+# at the top of a CloudBridge module:
+#   import cloudbridge
+#   cloudbridge.set_stream_logger(__name__)
+#   OR
+#   cloudbridge.set_file_logger(__name__, '/tmp/cb.log')
+
+
+def set_stream_logger(name, level=logging.DEBUG, format_string=None):
+    """A convenience method to set the global logger to stream."""
+    global log
+    if not format_string:
+        format_string = default_format_string
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    fh = logging.StreamHandler()
+    fh.setLevel(level)
+    formatter = logging.Formatter(format_string)
+    fh.setFormatter(formatter)
+    logger.addHandler(fh)
+    log = logger
+
+
+def set_file_logger(name, filepath, level=logging.INFO, format_string=None):
+    """A convenience method to set the global logger to a file."""
+    global log
+    if not format_string:
+        format_string = default_format_string
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    fh = logging.FileHandler(filepath)
+    fh.setLevel(level)
+    formatter = logging.Formatter(format_string)
+    fh.setFormatter(formatter)
+    logger.addHandler(fh)
+    log = logger

cloudbridge/cloud/providers/aws/services.py

@@ -1,6 +1,4 @@
-"""
-Services implemented by the AWS provider.
-"""
+"""Services implemented by the AWS provider."""
 import time
 import string
 
@@ -52,6 +50,9 @@ from .resources import AWSSnapshot
 from .resources import AWSSubnet
 from .resources import AWSVolume
 
+import cloudbridge as cb
+# Uncomment to enable logging by default for this module
+# cb.set_stream_logger(__name__)
 
 class AWSSecurityService(BaseSecurityService):
 
@@ -106,6 +107,7 @@ class AWSKeyPairService(BaseKeyPairService):
         :rtype: ``list`` of :class:`.KeyPair`
         :return:  list of KeyPair objects
         """
+        cb.log.debug("Listing AWS key pairs.")
         key_pairs = [AWSKeyPair(self.provider, kp)
                      for kp in self.provider.ec2_conn.get_all_key_pairs()]
         return ClientPagedResultList(self.provider, key_pairs,