Merge pull request #479 from matthew-brett/fancy-deprecations

MRG: add routine to deprecate with from/to versions

Add deprecation routine that allows you to specify at which version
deprecation began, and at which version deprecation will raise an error.

Add version comparison routine for our versions, to deal with extra `dev` etc strings at end of version.

Author: matthew-brett

nibabel/arraywriters.py

@@ -194,7 +194,9 @@ def _check_nan2zero(self, nan2zero):
             raise WriterError('Deprecated `nan2zero` argument to `to_fileobj` '
                               'must be same as class value set in __init__')
         warnings.warn('Please remove `nan2zero` from call to ' '`to_fileobj` '
-                      'and use in instance __init__ instead',
+                      'and use in instance __init__ instead.\n'
+                      '* deprecated in version: 2.0\n'
+                      '* will raise error in version: 4.0\n',
                       DeprecationWarning, stacklevel=3)
 
     def _needs_nan2zero(self):

nibabel/deprecated.py

@@ -1,8 +1,11 @@
-""" Module to help with deprecating classes and modules
+""" Module to help with deprecating objects and classes
 """
 
 import warnings
 
+from .deprecator import Deprecator
+from .info import cmp_pkg_version
+
 
 class ModuleProxy(object):
     """ Proxy for module that may not yet have been imported
@@ -63,3 +66,18 @@ def __init__(self, *args, **kwargs):
                       FutureWarning,
                       stacklevel=2)
         super(FutureWarningMixin, self).__init__(*args, **kwargs)
+
+
+class VisibleDeprecationWarning(UserWarning):
+    """ Deprecation warning that will be shown by default
+
+    Python >= 2.7 does not show standard DeprecationWarnings by default:
+
+    http://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x
+
+    Use this class for cases where we do want to show deprecations by default.
+    """
+    pass
+
+
+deprecate_with_version = Deprecator(cmp_pkg_version)

nibabel/deprecator.py

@@ -0,0 +1,168 @@
+""" Class for recording and reporting deprecations
+"""
+
+import functools
+import warnings
+import re
+
+_LEADING_WHITE = re.compile('^(\s*)')
+
+
+class ExpiredDeprecationError(RuntimeError):
+    """ Error for expired deprecation
+
+    Error raised when a called function or method has passed out of its
+    deprecation period.
+    """
+    pass
+
+
+def _ensure_cr(text):
+    """ Remove trailing whitespace and add carriage return
+
+    Ensures that `text` always ends with a carriage return
+    """
+    return text.rstrip() + '\n'
+
+
+def _add_dep_doc(old_doc, dep_doc):
+    """ Add deprecation message `dep_doc` to docstring in `old_doc`
+
+    Parameters
+    ----------
+    old_doc : str
+        Docstring from some object.
+    dep_doc : str
+        Deprecation warning to add to top of docstring, after initial line.
+
+    Returns
+    -------
+    new_doc : str
+        `old_doc` with `dep_doc` inserted after any first lines of docstring.
+    """
+    dep_doc = _ensure_cr(dep_doc)
+    if not old_doc:
+        return dep_doc
+    old_doc = _ensure_cr(old_doc)
+    old_lines = old_doc.splitlines()
+    new_lines = []
+    for line_no, line in enumerate(old_lines):
+        if line.strip():
+            new_lines.append(line)
+        else:
+            break
+    next_line = line_no + 1
+    if next_line >= len(old_lines):
+        # nothing following first paragraph, just append message
+        return old_doc + '\n' + dep_doc
+    indent = _LEADING_WHITE.match(old_lines[next_line]).group()
+    dep_lines = [indent + L for L in [''] + dep_doc.splitlines() + ['']]
+    return '\n'.join(new_lines + dep_lines + old_lines[next_line:]) + '\n'
+
+
+class Deprecator(object):
+    """ Class to make decorator marking function or method as deprecated
+
+    The decorated function / method will:
+
+    * Raise the given `warning_class` warning when the function / method gets
+      called, up to (and including) version `until` (if specified);
+    * Raise the given `error_class` error when the function / method gets
+      called, when the package version is greater than version `until` (if
+      specified).
+
+    Parameters
+    ----------
+    version_comparator : callable
+        Callable accepting string as argument, and return 1 if string
+        represents a higher version than encoded in the `version_comparator`, 0
+        if the version is equal, and -1 if the version is lower.  For example,
+        the `version_comparator` may compare the input version string to the
+        current package version string.
+    warn_class : class, optional
+        Class of warning to generate for deprecation.
+    error_class : class, optional
+        Class of error to generate when `version_comparator` returns 1 for a
+        given argument of ``until`` in the ``__call__`` method (see below).
+    """
+
+    def __init__(self,
+                 version_comparator,
+                 warn_class=DeprecationWarning,
+                 error_class=ExpiredDeprecationError):
+        self.version_comparator = version_comparator
+        self.warn_class = warn_class
+        self.error_class = error_class
+
+    def is_bad_version(self, version_str):
+        """ Return True if `version_str` is too high
+
+        Tests `version_str` with ``self.version_comparator``
+
+        Parameters
+        ----------
+        version_str : str
+            String giving version to test
+
+        Returns
+        -------
+        is_bad : bool
+            True if `version_str` is for version below that expected by
+            ``self.version_comparator``, False otherwise.
+        """
+        return self.version_comparator(version_str) == -1
+
+    def __call__(self, message, since='', until='',
+                 warn_class=None, error_class=None):
+        """ Return decorator function function for deprecation warning / error
+
+        Parameters
+        ----------
+        message : str
+            Message explaining deprecation, giving possible alternatives.
+        since : str, optional
+            Released version at which object was first deprecated.
+        until : str, optional
+            Last released version at which this function will still raise a
+            deprecation warning.  Versions higher than this will raise an
+            error.
+        warn_class : None or class, optional
+            Class of warning to generate for deprecation (overrides instance
+            default).
+        error_class : None or class, optional
+            Class of error to generate when `version_comparator` returns 1 for a
+            given argument of ``until`` (overrides class default).
+
+        Returns
+        -------
+        deprecator : func
+            Function returning a decorator.
+        """
+        warn_class = warn_class if warn_class else self.warn_class
+        error_class = error_class if error_class else self.error_class
+        messages = [message]
+        if (since, until) != ('', ''):
+            messages.append('')
+        if since:
+            messages.append('* deprecated from version: ' + since)
+        if until:
+            messages.append('* {} {} as of version: {}'.format(
+                "Raises" if self.is_bad_version(until) else "Will raise",
+                error_class,
+                until))
+        message = '\n'.join(messages)
+
+        def deprecator(func):
+
+            @functools.wraps(func)
+            def deprecated_func(*args, **kwargs):
+                if until and self.is_bad_version(until):
+                    raise error_class(message)
+                warnings.warn(message, warn_class, stacklevel=2)
+                return func(*args, **kwargs)
+
+            deprecated_func.__doc__ = _add_dep_doc(deprecated_func.__doc__,
+                                                   message)
+            return deprecated_func
+
+        return deprecator

nibabel/ecat.py

@@ -53,6 +53,7 @@
 from .arraywriters import make_array_writer
 from .wrapstruct import WrapStruct
 from .fileslice import canonical_slicers, predict_shape, slice2outax
+from .deprecated import deprecate_with_version
 
 BLOCK_SIZE = 512
 
@@ -846,6 +847,10 @@ def get_subheaders(self):
         return self._subheader
 
     @classmethod
+    @deprecate_with_version('from_filespec class method is deprecated.\n'
+                            'Please use the ``from_file_map`` class method '
+                            'instead.',
+                            '2.1', '4.0')
     def from_filespec(klass, filespec):
         return klass.from_filename(filespec)
 

nibabel/filebasedimages.py

@@ -8,13 +8,12 @@
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 ''' Common interface for any image format--volume or surface, binary or xml.'''
 
-import warnings
-
 from .externals.six import string_types
 from .fileholders import FileHolder
 from .filename_parser import (types_filenames, TypesFilenamesError,
                               splitext_addext)
 from .openers import ImageOpener
+from .deprecated import deprecate_with_version
 
 
 class ImageFileError(Exception):
@@ -212,16 +211,13 @@ def __getitem__(self):
         '''
         raise TypeError("Cannot slice image objects.")
 
+    @deprecate_with_version('get_header method is deprecated.\n'
+                            'Please use the ``img.header`` property '
+                            'instead.',
+                            '2.1', '4.0')
     def get_header(self):
         """ Get header from image
-
-        Please use the `header` property instead of `get_header`; we will
-        deprecate this method in future versions of nibabel.
         """
-        warnings.warn('``get_header`` is deprecated.\n'
-                      'Please use the ``img.header`` property '
-                      'instead',
-                      DeprecationWarning, stacklevel=2)
         return self.header
 
     def get_filename(self):
@@ -268,24 +264,16 @@ def from_filename(klass, filename):
         file_map = klass.filespec_to_file_map(filename)
         return klass.from_file_map(file_map)
 
-    @classmethod
-    def from_filespec(klass, filespec):
-        warnings.warn('``from_filespec`` class method is deprecated\n'
-                      'Please use the ``from_filename`` class method '
-                      'instead',
-                      DeprecationWarning, stacklevel=2)
-        klass.from_filename(filespec)
-
     @classmethod
     def from_file_map(klass, file_map):
         raise NotImplementedError
 
     @classmethod
+    @deprecate_with_version('from_files class method is deprecated.\n'
+                            'Please use the ``from_file_map`` class method '
+                            'instead.',
+                            '1.0', '3.0')
     def from_files(klass, file_map):
-        warnings.warn('``from_files`` class method is deprecated\n'
-                      'Please use the ``from_file_map`` class method '
-                      'instead',
-                      DeprecationWarning, stacklevel=2)
         return klass.from_file_map(file_map)
 
     @classmethod
@@ -326,11 +314,11 @@ def filespec_to_file_map(klass, filespec):
         return file_map
 
     @classmethod
+    @deprecate_with_version('filespec_to_files class method is deprecated.\n'
+                            'Please use the "filespec_to_file_map" class '
+                            'method instead.',
+                            '1.0', '3.0')
     def filespec_to_files(klass, filespec):
-        warnings.warn('``filespec_to_files`` class method is deprecated\n'
-                      'Please use the ``filespec_to_file_map`` class method '
-                      'instead',
-                      DeprecationWarning, stacklevel=2)
         return klass.filespec_to_file_map(filespec)
 
     def to_filename(self, filename):
@@ -350,20 +338,19 @@ def to_filename(self, filename):
         self.file_map = self.filespec_to_file_map(filename)
         self.to_file_map()
 
+    @deprecate_with_version('to_filespec method is deprecated.\n'
+                            'Please use the "to_filename" method instead.',
+                            '1.0', '3.0')
     def to_filespec(self, filename):
-        warnings.warn('``to_filespec`` is deprecated, please '
-                      'use ``to_filename`` instead',
-                      DeprecationWarning, stacklevel=2)
         self.to_filename(filename)
 
     def to_file_map(self, file_map=None):
         raise NotImplementedError
 
+    @deprecate_with_version('to_files method is deprecated.\n'
+                            'Please use the "to_file_map" method instead.',
+                            '1.0', '3.0')
     def to_files(self, file_map=None):
-        warnings.warn('``to_files`` method is deprecated\n'
-                      'Please use the ``to_file_map`` method '
-                      'instead',
-                      DeprecationWarning, stacklevel=2)
         self.to_file_map(file_map)
 
     @classmethod