RF+TST: specify versions for DeprecationWarnings

Specify version at which DeprecationWarning was first raised, and
planned version for removal.

Add tests for some deprecations that were not being tested.

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/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):
@@ -273,11 +269,11 @@ 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
@@ -318,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):
@@ -342,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

nibabel/imageclasses.py

@@ -7,7 +7,6 @@
 #
 ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ##
 ''' Define supported image classes and names '''
-import warnings
 
 from .analyze import AnalyzeImage
 from .freesurfer import MGHImage
@@ -20,6 +19,7 @@
 from .spm99analyze import Spm99AnalyzeImage
 from .spm2analyze import Spm2AnalyzeImage
 from .volumeutils import Recoder
+from .deprecated import deprecate_with_version
 
 from .optpkg import optional_package
 _, have_scipy, _ = optional_package('scipy')
@@ -35,9 +35,9 @@
 # DEPRECATED: mapping of names to classes and class functionality
 class ClassMapDict(dict):
 
+    @deprecate_with_version('class_map is deprecated.',
+                            '2.1', '4.0')
     def __getitem__(self, *args, **kwargs):
-        warnings.warn("class_map is deprecated.", DeprecationWarning,
-                      stacklevel=2)
         return super(ClassMapDict, self).__getitem__(*args, **kwargs)
 
 class_map = ClassMapDict(
@@ -90,9 +90,9 @@ def __getitem__(self, *args, **kwargs):
 
 class ExtMapRecoder(Recoder):
 
+    @deprecate_with_version('ext_map is deprecated.',
+                            '2.1', '4.0')
     def __getitem__(self, *args, **kwargs):
-        warnings.warn("ext_map is deprecated.", DeprecationWarning,
-                      stacklevel=2)
         return super(ExtMapRecoder, self).__getitem__(*args, **kwargs)
 
 # mapping of extensions to default image class names

nibabel/loadsave.py

@@ -131,12 +131,11 @@ def save(img, filename):
 def read_img_data(img, prefer='scaled'):
     """ Read data from image associated with files
 
-    We've deprecated this function and will remove it soon. If you want
-    unscaled data, please use ``img.dataobj.get_unscaled()`` instead.  If you
-    want scaled data, use ``img.get_data()`` (which will cache the loaded
-    array) or ``np.array(img.dataobj)`` (which won't cache the array). If you
-    want to load the data as for a modified header, save the image with the
-    modified header, and reload.
+    If you want unscaled data, please use ``img.dataobj.get_unscaled()``
+    instead.  If you want scaled data, use ``img.get_data()`` (which will cache
+    the loaded array) or ``np.array(img.dataobj)`` (which won't cache the
+    array). If you want to load the data as for a modified header, save the
+    image with the modified header, and reload.
 
     Parameters
     ----------

nibabel/parrec.py

@@ -139,6 +139,7 @@
 from .nifti1 import unit_codes
 from .fileslice import fileslice, strided_scalar
 from .openers import ImageOpener
+from .deprecated import deprecate_with_version
 
 # PSL to RAS affine
 PSL_TO_RAS = np.array([[0, 0, -1, 0],  # L -> R
@@ -822,23 +823,21 @@ def _get_unique_image_prop(self, name):
                               'not suppported.'.format(name, props))
         return props[0]
 
+    @deprecate_with_version('get_voxel_size deprecated. '
+                            'Please use "get_zooms" instead.',
+                            '2.0', '4.0')
     def get_voxel_size(self):
         """Returns the spatial extent of a voxel.
 
         Does not include the slice gap in the slice extent.
 
-        This function is deprecated and we will remove it in future versions of
-        nibabel.  Please use ``get_zooms`` instead.  If you need the slice
-        thickness not including the slice gap, use ``self.image_defs['slice
-        thickness']``.
+        If you need the slice thickness not including the slice gap, use
+        ``self.image_defs['slice thickness']``.
 
         Returns
         -------
         vox_size: shape (3,) ndarray
         """
-        warnings.warn('Please use "get_zooms" instead of "get_voxel_size"',
-                      DeprecationWarning,
-                      stacklevel=2)
         # slice orientation for the whole image series
         slice_thickness = self._get_unique_image_prop('slice thickness')
         voxsize_inplane = self._get_unique_image_prop('pixel spacing')

nibabel/spatialimages.py

@@ -133,14 +133,13 @@
 
 '''
 
-import warnings
-
 import numpy as np
 
 from .filebasedimages import FileBasedHeader, FileBasedImage
 from .filebasedimages import ImageFileError  # flake8: noqa; for back-compat
 from .viewers import OrthoSlicer3D
 from .volumeutils import shape_zoom_affine
+from .deprecated import deprecate_with_version
 
 
 class HeaderDataError(Exception):
@@ -308,9 +307,11 @@ def supported_np_types(obj):
 class Header(SpatialHeader):
     '''Alias for SpatialHeader; kept for backwards compatibility.'''
 
+    @deprecate_with_version('Header class is deprecated.\n'
+                            'Please use SpatialHeader instead.'
+                            'instead.',
+                            '2.1', '4.0')
     def __init__(self, *args, **kwargs):
-        warnings.warn('Header is deprecated, use SpatialHeader',
-                      DeprecationWarning, stacklevel=2)
         super(Header, self).__init__(*args, **kwargs)
 
 
@@ -373,11 +374,10 @@ def __init__(self, dataobj, affine, header=None,
         self._data_cache = None
 
     @property
+    @deprecate_with_version('_data attribute not part of public API. '
+                            'please use "dataobj" property instead.',
+                            '2.0', '4.0')
     def _data(self):
-        warnings.warn('Please use ``dataobj`` instead of ``_data``; '
-                      'We will remove this wrapper for ``_data`` soon',
-                      FutureWarning,
-                      stacklevel=2)
         return self._dataobj
 
     @property
@@ -612,14 +612,13 @@ def uncache(self):
     def shape(self):
         return self._dataobj.shape
 
+    @deprecate_with_version('get_shape method is deprecated.\n'
+                            'Please use the ``img.shape`` property '
+                            'instead.',
+                            '1.2', '3.0')
     def get_shape(self):
         """ Return shape for image
-
-        This function deprecated; please use the ``shape`` property instead
         """
-        warnings.warn('Please use the shape property instead of get_shape',
-                      DeprecationWarning,
-                      stacklevel=2)
         return self.shape
 
     def get_data_dtype(self):

nibabel/tests/test_image_api.py

@@ -153,6 +153,14 @@ def validate_shape(self, imaker, params):
         # Read only
         assert_raises(AttributeError, setattr, img, 'shape', np.eye(4))
 
+    def validate_shape_deprecated(self, imaker, params):
+        # Check deprecated get_shape API
+        with clear_and_catch_warnings() as w:
+            warnings.simplefilter('always', DeprecationWarning)
+            img = imaker()
+            assert_equal(img.get_shape(), params['shape'])
+            assert_equal(len(w), 1)
+
     def validate_dtype(self, imaker, params):
         # data / storage dtype
         img = imaker()
@@ -246,7 +254,7 @@ def validate_data_deprecated(self, imaker, params):
         with warnings.catch_warnings(record=True) as warns:
             warnings.simplefilter("always")
             assert_data_similar(img._data, params)
-            assert_equal(warns.pop(0).category, FutureWarning)
+            assert_equal(warns.pop(0).category, DeprecationWarning)
         # Check setting _data raises error
         fake_data = np.zeros(img.shape).astype(img.get_data_dtype())
         assert_raises(AttributeError, setattr, img, '_data', fake_data)

nibabel/tests/test_imageclasses.py

@@ -2,6 +2,7 @@
 """
 
 from os.path import dirname, join as pjoin
+import warnings
 
 import numpy as np
 
@@ -12,9 +13,13 @@
 from nibabel.nifti1 import Nifti1Image
 from nibabel.nifti2 import Nifti2Image
 
-from nibabel.imageclasses import spatial_axes_first
+from nibabel import imageclasses
+from nibabel.imageclasses import spatial_axes_first, class_map, ext_map
+
+from nose.tools import (assert_true, assert_false, assert_equal)
+
+from nibabel.testing import clear_and_catch_warnings
 
-from nose.tools import (assert_true, assert_false)
 
 DATA_DIR = pjoin(dirname(__file__), 'data')
 
@@ -46,3 +51,15 @@ def test_spatial_axes_first():
         img = nib.load(pjoin(DATA_DIR, fname))
         assert_true(len(img.shape) == 4)
         assert_false(spatial_axes_first(img))
+
+
+def test_deprecations():
+    with clear_and_catch_warnings(modules=[imageclasses]) as w:
+        warnings.filterwarnings('always', category=DeprecationWarning)
+        nifti_single = class_map['nifti_single']
+        assert_equal(nifti_single['class'], Nifti1Image)
+        assert_equal(len(w), 1)
+        nifti_ext = ext_map['.nii']
+        assert_equal(nifti_ext, 'nifti_single')
+        assert_equal(len(w), 2)
+

nibabel/tests/test_spatialimages.py

@@ -335,6 +335,39 @@ def test_get_data(self):
         assert_false(rt_img.get_data() is out_data)
         assert_array_equal(rt_img.get_data(), in_data)
 
+    def test_api_deprecations(self):
+
+        class FakeImage(self.image_class):
+
+            files_types = (('image', '.foo'),)
+
+            @classmethod
+            def to_file_map(self, file_map=None):
+                pass
+
+            @classmethod
+            def from_file_map(self, file_map=None):
+                pass
+
+        arr = np.arange(24, dtype=np.int16).reshape((2, 3, 4))
+        aff = np.eye(4)
+        img = FakeImage(arr, aff)
+        bio = BytesIO()
+        file_map = FakeImage.make_file_map({'image': bio})
+
+        with clear_and_catch_warnings() as w:
+            warnings.simplefilter('always', DeprecationWarning)
+            img.to_files(file_map)
+            assert_equal(len(w), 1)
+            img.to_filespec('an_image')
+            assert_equal(len(w), 2)
+            img = FakeImage.from_files(file_map)
+            assert_equal(len(w), 3)
+            file_map = FakeImage.filespec_to_files('an_image')
+            assert_equal(list(file_map), ['image'])
+            assert_equal(file_map['image'].filename, 'an_image.foo')
+            assert_equal(len(w), 4)
+
 
 class MmapImageMixin(object):
     """ Mixin for testing images that may return memory maps """