nilearn/nilearn — pull request #84 by pgervais (2013-06-25 16:39:31+00:00)
Title: New logging function

The current state of logging in NiLearn is not satisfactory. To attempts at organizing something have been attempted so far: LogMixin in nifti_region.py and enclosing_scope_name() in _utils/class_inspect.py, used in BaseMasker. They go in different directions.

The present pull request is an additional attempt to get to something usable. I completely abandoned the idea of a class Mixin, because it couldn't be used in a function. Thus, emitting a user message is performed with a function: log(). I added this function in _utils/logger.py. It can be used from anywhere (function, method, or top-level).

Typical usage in a method:

logger.log("message to the user", verbose=self.verbose)

The `verbose=self.verbose` is required so far, because the function cannot get access to self.verbose directly. The main advantage is that logger.log() prepends the name of the method that the user has most likely used in her script, whatever the location of the call to log(). More precisely, if the user calls the fit() method on an estimator object, and a call to log("message") is performed deeper in the call stack, the user will see in the message something like "[EstimatorClass.fit] message".

This behaviour is achieved in log() by walking up the call stack, finding the topmost object that inherits from BaseEstimator, and reading the class and function names therein. This is much smarter than the stack_level trick used by `enclosing_scope_name`. stack_level is still supported though, but is used as a fallback is no object has been found.

I only adapted `nifti_region.py` to the new system. Launch `plot_adhd_covariance.py` to see it in action.

I would like to have feedback before proceeding.