Better tests and documentation for the logging.

Author: alexjc

docs/guide_intermediate.rst

@@ -4,9 +4,7 @@ Misc. Additions
 Verbose Mode
 ------------
 
-To see the output of the neural network's training, you need to configure two things: first setting up the Python logger (mandatory), and secondly to specify a verbose mode if you want more information during training (optional).
-
-The first step is to configure either the ``sknn`` logger specifically, or do so globally (easier) as follows:
+To see the output of the neural network's training, configure the Python logger called ``sknn`` or the default root logger.  This is possible using the standard ``logging`` module which you can setup as follows:
 
 .. code:: python
 
@@ -18,20 +16,9 @@ The first step is to configure either the ``sknn`` logger specifically, or do so
                 level=logging.DEBUG,
                 stream=sys.stdout)
 
-Then you can optionally create your neural networks using an additional ``verbose`` parameter to show the output during training:
-
-.. code:: python
-    
-    from sknn.mlp import Regressor, Layer
-
-    nn = Regressor(
-        layers=[Layer("Linear")],
-        n_iter=20,
-        verbose=True,
-        valid_size=0.25)
-    nn.fit(X, y)
+Change the log level to ``logging.INFO`` for less information about each epoch, or ``logging.WARNING`` only to receive messages about problems or failures.
 
-This code will output a table containing validation scores at each of the twenty epochs.  The ``valid_size`` parameter is a ratio of the data to be used internally for validation; in short, the ``fit()`` function is automatically splitting the data into ``X_train`` and ``y_train`` as well as ``X_valid`` and ``y_valid``.
+Using the flag ``verbose=True`` on either :class:`sknn.mlp.Classifier` and :class:`sknn.mlp.Regressor` will setup a default logger at ``DEBUG`` level if it does not exist, and ``verbose=False`` will setup a default logger at level ``WARNING`` if no logging has been configured.
 
 
 Saving & Loading

sknn/nn.py

@@ -336,9 +336,10 @@ class NeuralNetwork(object):
 
             * ``False`` — Setup new logger that shows only warnings and errors.
             * ``True`` — Setup a new logger that displays all debug messages.
+            * ``None`` — Don't setup a new logger under any condition (default). 
 
         Using the built-in python ``logging`` module, you can control the detail and style of
-        output by customising the logger level and formatter for ``sknn`` logger.
+        output by customising the verbosity level and formatter for ``sknn`` logger.
     """
 
     def __init__(
@@ -359,7 +360,7 @@ def __init__(
             valid_size=0.0,
             loss_type='mse',
             debug=False,
-            verbose=False,
+            verbose=None,
             **params):
 
         self.layers = []
@@ -445,7 +446,7 @@ def is_convolution(self):
 
     def _create_logger(self):
         # If users have configured logging already, assume they know best.
-        if len(log.handlers) > 0 or len(log.parent.handlers) > 0:
+        if len(log.handlers) > 0 or len(log.parent.handlers) > 0 or self.verbose is None:
             return
 
         # Otherwise setup a default handler and formatter based on verbosity.
@@ -454,8 +455,8 @@ def _create_logger(self):
         hnd = logging.StreamHandler(stream=sys.stdout)
 
         hnd.setFormatter(fmt)
+        hnd.setLevel(lvl)
         log.addHandler(hnd)
-        log.setLevel(lvl)
 
     def _create_matrix_input(self, X, y=None):
         if self.is_convolution:

sknn/tests/test_training.py

@@ -1,5 +1,5 @@
 import unittest
-from nose.tools import (assert_in, assert_raises)
+from nose.tools import (assert_in, assert_raises, assert_equals)
 
 import io
 import logging
@@ -34,6 +34,31 @@ def test_FitAutomaticValidation(self):
         self.nn._fit(a_in, a_out)
 
 
+class TestCustomLogging(unittest.TestCase):
+
+    def setUp(self):
+        self.log = logging.getLogger('sknn')
+        self.log.handlers = []
+        self.backup, self.log.parent.handlers = self.log.parent.handlers, []
+
+    def tearDown(self):
+        self.log.parent.handlers = self.backup
+
+    def test_DefaultLogVerbose(self):
+        nn = MLPR(layers=[L("Linear")], verbose=True)
+        assert_equals(1, len(self.log.handlers))
+        assert_equals(logging.DEBUG, self.log.handlers[0].level)
+
+    def test_DefaultLogQuiet(self):
+        nn = MLPR(layers=[L("Linear")], verbose=False)
+        assert_equals(1, len(self.log.handlers))
+        assert_equals(logging.WARNING, self.log.handlers[0].level)
+
+    def test_VerboseNoneNoLog(self):
+        nn = MLPR(layers=[L("Linear")], verbose=None)
+        assert_equals(0, len(self.log.handlers))
+
+
 class TestTrainingOutput(unittest.TestCase):
 
     def setUp(self):