RF+DOC: refactor log_chk into own function

* Refactor log_chk testing method into function;
* Add more helpful docstring to log_chk;
* Expand docstring for check_fix method of wrapstruct.

Author: matthew-brett

nibabel/tests/test_wrapstruct.py

@@ -43,6 +43,69 @@
 
 INTEGER_TYPES = np.sctypes['int'] + np.sctypes['uint']
 
+def log_chk(hdr, level):
+    """ Utility method to check header checking / logging
+
+    Asserts that log entry appears during ``hdr.check_fix`` for logging level
+    below `level`.
+
+    Parameters
+    ----------
+    hdr : instance
+        Instance of header class, with methods ``copy`` and check_fix``.  The
+        header has some minor error (defect) which can be detected with
+        ``check_fix``.
+    level : int
+        Level (severity) of defect present in `hdr`.  When logging threshold is
+        at or below `level`, a message appears in the default log (we test that
+        happens).
+
+    Returns
+    -------
+    hdrc : instance
+        Header, with defect corrected.
+    message : str
+        Message generated in log when defect was detected.
+    raiser : tuple
+        Tuple of error type, callable, arguments that will raise an exception
+        when then defect is detected.  Can be empty.  Check with ``if raiser !=
+        (): assert_raises(*raiser)``.
+    """
+    str_io = StringIO()
+    logger = logging.getLogger('test.logger')
+    handler = logging.StreamHandler(str_io)
+    logger.addHandler(handler)
+    str_io.truncate(0)
+    hdrc = hdr.copy()
+    if level == 0:  # Should never log or raise error
+        logger.setLevel(0)
+        hdrc.check_fix(logger=logger, error_level=0)
+        assert_equal(str_io.getvalue(), '')
+        logger.removeHandler(handler)
+        return hdrc, '', ()
+    # Non zero defect level, test above and below threshold.
+    # Set error level above defect level to prevent exception when defect
+    # detected.
+    e_lev = level + 1
+    # Logging level above threshold, no log.
+    logger.setLevel(level + 1)
+    hdrc.check_fix(logger=logger, error_level=e_lev)
+    assert_equal(str_io.getvalue(), '')
+    # Logging level below threshold, log appears, store logged message
+    logger.setLevel(level - 1)
+    hdrc = hdr.copy()
+    hdrc.check_fix(logger=logger, error_level=e_lev)
+    assert_true(str_io.getvalue() != '')
+    message = str_io.getvalue().strip()
+    logger.removeHandler(handler)
+    # When error level == level, check_fix should raise an error
+    hdrc2 = hdr.copy()
+    raiser = (HeaderDataError,
+              hdrc2.check_fix,
+              logger,
+              level)
+    return hdrc, message, raiser
+
 
 class _TestWrapStructBase(TestCase):
     ''' Class implements base tests for binary headers
@@ -161,40 +224,7 @@ def test_structarr(self):
         assert_raises(AttributeError, hdr.__setattr__, 'structarr', 0)
 
     def log_chk(self, hdr, level):
-        # utility method to check header checking / logging
-        # If level == 0, this header should always be OK
-        str_io = StringIO()
-        logger = logging.getLogger('test.logger')
-        handler = logging.StreamHandler(str_io)
-        logger.addHandler(handler)
-        str_io.truncate(0)
-        hdrc = hdr.copy()
-        if level == 0:  # Should never log or raise error
-            logger.setLevel(0)
-            hdrc.check_fix(logger=logger, error_level=0)
-            assert_equal(str_io.getvalue(), '')
-            logger.removeHandler(handler)
-            return hdrc, '', ()
-        # Non zero level, test above and below threshold
-        # Logging level above threshold, no log
-        logger.setLevel(level + 1)
-        e_lev = level + 1
-        hdrc.check_fix(logger=logger, error_level=e_lev)
-        assert_equal(str_io.getvalue(), '')
-        # Logging level below threshold, log appears
-        logger.setLevel(level + 1)
-        logger.setLevel(level - 1)
-        hdrc = hdr.copy()
-        hdrc.check_fix(logger=logger, error_level=e_lev)
-        assert_true(str_io.getvalue() != '')
-        message = str_io.getvalue().strip()
-        logger.removeHandler(handler)
-        hdrc2 = hdr.copy()
-        raiser = (HeaderDataError,
-                  hdrc2.check_fix,
-                  logger,
-                  level)
-        return hdrc, message, raiser
+        return log_chk(hdr, level)
 
     def assert_no_log_err(self, hdr):
         """ Assert that no logging or errors result from this `hdr`

nibabel/wrapstruct.py

@@ -346,7 +346,15 @@ def get(self, k, d=None):
         return (k in self.keys()) and self._structarr[k] or d
 
     def check_fix(self, logger=None, error_level=None):
-        ''' Check structured data with checks '''
+        ''' Check structured data with checks
+
+        Parameters
+        ----------
+        logger : None or logging.Logger
+        error_level : None or int
+            Level of error severity at which to raise error.  Any error of
+            severity >= `error_level` will cause an exception.
+        '''
         if logger is None:
             logger = imageglobals.logger
         if error_level is None: