RF: replace numpy deprecation decorator with ours

Replace `np.deprecate_with_doc` with `deprecate_with_version`.

There are other deprecations around the code-base that could be
signalled with this decorator.

Author: matthew-brett

nibabel/gifti/gifti.py

@@ -23,6 +23,7 @@
 from ..nifti1 import data_type_codes, xform_codes, intent_codes
 from .util import (array_index_order_codes, gifti_encoding_codes,
                    gifti_endian_codes, KIND2FMT)
+from ..deprecated import deprecate_with_version
 
 # {en,de}codestring in deprecated in Python3, but
 # {en,de}codebytes not available in Python2.
@@ -47,7 +48,10 @@ def from_dict(klass, data_dict):
             meda.data.append(nv)
         return meda
 
-    @np.deprecate_with_doc("Use the metadata property instead.")
+    @deprecate_with_version(
+        'get_metadata method deprecated. '
+        "Use the metadata property instead."
+        '2.1', '4.0')
     def get_metadata(self):
         return self.metadata
 
@@ -156,7 +160,10 @@ def __init__(self, key=0, red=None, green=None, blue=None, alpha=None):
         self.blue = blue
         self.alpha = alpha
 
-    @np.deprecate_with_doc("Use the rgba property instead.")
+    @deprecate_with_version(
+        'get_rgba method deprecated. '
+        "Use the rgba property instead."
+        '2.1', '4.0')
     def get_rgba(self):
         return self.rgba
 
@@ -249,7 +256,9 @@ def print_summary(self):
         print('Affine Transformation Matrix: \n', self.xform)
 
 
-@np.deprecate_with_doc("This is an internal API that will be discontinued.")
+@deprecate_with_version(
+    "data_tag is an internal API that will be discontinued.",
+    '2.1', '4.0')
 def data_tag(dataarray, encoding, datatype, ordering):
     class DataTag(xml.XmlSerializable):
 
@@ -371,10 +380,10 @@ def num_dim(self):
 
     # Setter for backwards compatibility with pymvpa
     @num_dim.setter
+    @deprecate_with_version(
+        "num_dim will be read-only in future versions of nibabel",
+        '2.1', '4.0')
     def num_dim(self, value):
-        warnings.warn(
-            "num_dim will be read-only in future versions of nibabel",
-            DeprecationWarning, stacklevel=2)
         if value != len(self.dims):
             raise ValueError('num_dim value {0} != number of dimensions '
                              'len(self.dims) {1}'
@@ -463,7 +472,10 @@ def _to_xml_element(self):
 
         return data_array
 
-    @np.deprecate_with_doc("Use the to_xml() function instead.")
+    @deprecate_with_version(
+        'to_xml_open method deprecated. '
+        'Use the to_xml() function instead.',
+        '2.1', '4.0')
     def to_xml_open(self):
         out = """<DataArray Intent="%s"
 \tDataType="%s"
@@ -487,7 +499,10 @@ def to_xml_open(self):
                       self.ext_offset,
                       )
 
-    @np.deprecate_with_doc("Use the to_xml() function instead.")
+    @deprecate_with_version(
+        'to_xml_close method deprecated. '
+        'Use the to_xml() function instead.',
+        '2.1', '4.0')
     def to_xml_close(self):
         return "</DataArray>\n"
 
@@ -507,7 +522,10 @@ def print_summary(self):
             print('Coordinate System:')
             print(self.coordsys.print_summary())
 
-    @np.deprecate_with_doc("Use the metadata property instead.")
+    @deprecate_with_version(
+        'get_metadata method deprecated. '
+        "Use the metadata property instead."
+        '2.1', '4.0')
     def get_metadata(self):
         return self.meta.metadata
 
@@ -591,11 +609,18 @@ def labeltable(self, labeltable):
             raise TypeError("Not a valid GiftiLabelTable instance")
         self._labeltable = labeltable
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+
+    @deprecate_with_version(
+        'set_labeltable method deprecated. '
+        "Use the gifti_img.labeltable property instead.",
+        '2.1', '4.0')
     def set_labeltable(self, labeltable):
         self.labeltable = labeltable
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'get_labeltable method deprecated. '
+        "Use the gifti_img.labeltable property instead.",
+        '2.1', '4.0')
     def get_labeltable(self):
         return self.labeltable
 
@@ -615,11 +640,17 @@ def meta(self, meta):
             raise TypeError("Not a valid GiftiMetaData instance")
         self._meta = meta
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'set_meta method deprecated. '
+        "Use the gifti_img.meta property instead.",
+        '2.1', '4.0')
     def set_metadata(self, meta):
         self.meta = meta
 
-    @np.deprecate_with_doc("Use the gifti_img.labeltable property instead.")
+    @deprecate_with_version(
+        'get_meta method deprecated. '
+        "Use the gifti_img.meta property instead.",
+        '2.1', '4.0')
     def get_meta(self):
         return self.meta
 
@@ -651,7 +682,10 @@ def get_arrays_from_intent(self, intent):
         it = intent_codes.code[intent]
         return [x for x in self.darrays if x.intent == it]
 
-    @np.deprecate_with_doc("Use get_arrays_from_intent instead.")
+    @deprecate_with_version(
+        'getArraysFromIntent method deprecated. '
+        "Use get_arrays_from_intent instead.",
+        '2.1', '4.0')
     def getArraysFromIntent(self, intent):
         return self.get_arrays_from_intent(intent)
 

nibabel/gifti/giftiio.py

@@ -12,8 +12,12 @@
 
 import numpy as np
 
+from ..deprecated import deprecate_with_version
 
-@np.deprecate_with_doc("Use nibabel.load() instead.")
+
+@deprecate_with_version('giftiio.read function deprecated. '
+                        "Use nibabel.load() instead.",
+                        '2.1', '4.0')
 def read(filename):
     """ Load a Gifti image from a file
 
@@ -31,7 +35,9 @@ def read(filename):
     return load(filename)
 
 
-@np.deprecate_with_doc("Use nibabel.save() instead.")
+@deprecate_with_version('giftiio.write function deprecated. '
+                        "Use nibabel.load() instead.",
+                        '2.1', '4.0')
 def write(image, filename):
     """ Save the current image to a new file
 

nibabel/gifti/parse_gifti_fast.py

@@ -24,6 +24,7 @@
                    gifti_endian_codes)
 from ..nifti1 import data_type_codes, xform_codes, intent_codes
 from ..xmlutils import XmlParser
+from ..deprecated import deprecate_with_version
 
 
 class GiftiParseError(ExpatError):
@@ -340,9 +341,12 @@ def pending_data(self):
         return self._char_blocks is not None
 
 
+
 class Outputter(GiftiImageParser):
 
-    @np.deprecate_with_doc("Use GiftiImageParser instead.")
+    @deprecate_with_version('Outputter class deprecated. '
+                            "Use GiftiImageParser instead.",
+                            '2.1', '4.0')
     def __init__(self):
         super(Outputter, self).__init__()
 
@@ -351,6 +355,8 @@ def initialize(self):
         self.__init__()
 
 
-@np.deprecate_with_doc("Use GiftiImageParser.parse() instead.")
+@deprecate_with_version('parse_gifti_file deprecated. '
+                        "Use GiftiImageParser.parse() instead.",
+                        '2.1', '4.0')
 def parse_gifti_file(fname=None, fptr=None, buffer_size=None):
     GiftiImageParser(buffer_size=buffer_size).parse(fname=fname, fptr=fptr)

nibabel/gifti/tests/test_gifti.py

@@ -206,17 +206,29 @@ def test_labeltable():
     img.labeltable = new_table
     assert_equal(len(img.labeltable.labels), 2)
 
+    # Test deprecations
+    with clear_and_catch_warnings() as w:
+        warnings.filterwarnings('always', category=DeprecationWarning)
+        newer_table = GiftiLabelTable()
+        newer_table.labels += ['test', 'me', 'again']
+        img.set_labeltable(newer_table)
+        assert_equal(len(w), 1)
+        assert_equal(len(img.get_labeltable().labels), 3)
+        assert_equal(len(w), 2)
+
 
 def test_metadata():
     nvpair = GiftiNVPairs('key', 'value')
-    da = GiftiMetaData(nvpair=nvpair)
-    assert_equal(da.data[0].name, 'key')
-    assert_equal(da.data[0].value, 'value')
+    md = GiftiMetaData(nvpair=nvpair)
+    assert_equal(md.data[0].name, 'key')
+    assert_equal(md.data[0].value, 'value')
     # Test deprecation
     with clear_and_catch_warnings() as w:
         warnings.filterwarnings('always', category=DeprecationWarning)
-        assert_equal(len(GiftiDataArray().get_metadata()), 0)
+        assert_equal(md.get_metadata(), dict(key='value'))
         assert_equal(len(w), 1)
+        assert_equal(len(GiftiDataArray().get_metadata()), 0)
+        assert_equal(len(w), 2)
 
 
 def test_gifti_label_rgba():

nibabel/gifti/tests/test_giftiio.py

@@ -11,7 +11,8 @@
 
 from nose.tools import (assert_true, assert_false, assert_equal,
                         assert_raises)
-from ...testing import clear_and_catch_warnings
+from nibabel.testing import clear_and_catch_warnings
+from nibabel.tmpdirs import InTemporaryDirectory
 
 
 from .test_parse_gifti_fast import (DATA_FILE1, DATA_FILE2, DATA_FILE3,
@@ -29,7 +30,10 @@ def setUp(self):
 def test_read_deprecated():
     with clear_and_catch_warnings() as w:
         warnings.simplefilter('always', DeprecationWarning)
-        from nibabel.gifti.giftiio import read
+        from nibabel.gifti.giftiio import read, write
 
-        read(DATA_FILE1)
+        img = read(DATA_FILE1)
         assert_equal(len(w), 1)
+        with InTemporaryDirectory():
+            write(img, 'test.gii')
+        assert_equal(len(w), 2)

nibabel/loadsave.py

@@ -11,14 +11,14 @@
 
 import os.path as op
 import numpy as np
-import warnings
 
 from .filename_parser import splitext_addext
 from .openers import ImageOpener
 from .filebasedimages import ImageFileError
 from .imageclasses import all_image_classes
 from .arrayproxy import is_proxy
 from .py3k import FileNotFoundError
+from .deprecated import deprecate_with_version
 
 
 def load(filename, **kwargs):
@@ -48,7 +48,9 @@ def load(filename, **kwargs):
                          filename)
 
 
-@np.deprecate
+@deprecate_with_version('guessed_image_type deprecated.'
+                        '2.1',
+                        '4.0')
 def guessed_image_type(filename):
     """ Guess image type from file `filename`
 
@@ -62,8 +64,6 @@ def guessed_image_type(filename):
     image_class : class
         Class corresponding to guessed image type
     """
-    warnings.warn('guessed_image_type is deprecated', DeprecationWarning,
-                  stacklevel=2)
     sniff = None
     for image_klass in all_image_classes:
         is_valid, sniff = image_klass.path_maybe_image(filename, sniff)
@@ -124,8 +124,10 @@ def save(img, filename):
     converted.to_filename(filename)
 
 
-@np.deprecate_with_doc('Please use ``img.dataobj.get_unscaled()`` '
-                       'instead')
+@deprecate_with_version('read_img_data deprecated.'
+                        'Please use ``img.dataobj.get_unscaled()`` instead.'
+                        '2.0.1',
+                        '4.0')
 def read_img_data(img, prefer='scaled'):
     """ Read data from image associated with files
 
@@ -210,7 +212,9 @@ def read_img_data(img, prefer='scaled'):
         return hdr.raw_data_from_fileobj(fileobj)
 
 
-@np.deprecate
+@deprecate_with_version('which_analyze_type deprecated.'
+                        '2.1',
+                        '4.0')
 def which_analyze_type(binaryblock):
     """ Is `binaryblock` from NIfTI1, NIfTI2 or Analyze header?
 
@@ -238,8 +242,6 @@ def which_analyze_type(binaryblock):
     * if ``sizeof_hdr`` is 348 or byteswapped 348 assume Analyze
     * Return None
     """
-    warnings.warn('which_analyze_type is deprecated', DeprecationWarning,
-                  stacklevel=2)
     from .nifti1 import header_dtype
     hdr_struct = np.ndarray(shape=(), dtype=header_dtype, buffer=binaryblock)
     bs_hdr_struct = hdr_struct.byteswap()

nibabel/orientations.py

@@ -13,6 +13,8 @@
 import numpy as np
 import numpy.linalg as npl
 
+from .deprecated import deprecate_with_version
+
 
 class OrientationError(Exception):
     pass
@@ -228,7 +230,10 @@ def inv_ornt_aff(ornt, shape):
     return np.dot(undo_flip, undo_reorder)
 
 
-@np.deprecate_with_doc("Please use inv_ornt_aff instead")
+@deprecate_with_version('orientation_affine deprecated. '
+                        'Please use inv_ornt_aff instead'
+                        '1.3',
+                        '3.0')
 def orientation_affine(ornt, shape):
     return inv_ornt_aff(ornt, shape)
 

nibabel/volumeutils.py

@@ -21,6 +21,7 @@
 
 from .casting import (shared_range, type_info, OK_FLOATS)
 from .openers import Opener
+from .deprecated import deprecate_with_version
 
 sys_is_le = sys.byteorder == 'little'
 native_code = sys_is_le and '<' or '>'
@@ -373,7 +374,10 @@ def make_dt_codes(codes_seqs):
     return Recoder(dt_codes, fields + ['dtype', 'sw_dtype'], DtypeMapper)
 
 
-@np.deprecate_with_doc('Please use arraywriter classes instead')
+@deprecate_with_version('can_cast deprecated. '
+                        'Please use arraywriter classes instead',
+                        '1.2',
+                        '3.0')
 def can_cast(in_type, out_type, has_intercept=False, has_slope=False):
     ''' Return True if we can safely cast ``in_type`` to ``out_type``
 
@@ -1007,7 +1011,10 @@ def working_type(in_type, slope=1.0, inter=0.0):
     return val.dtype.type
 
 
-@np.deprecate_with_doc('Please use arraywriter classes instead')
+@deprecate_with_version('calculate_scale deprecated. '
+                        'Please use arraywriter classes instead',
+                        '1.2',
+                        '3.0')
 def calculate_scale(data, out_dtype, allow_intercept):
     ''' Calculate scaling and optional intercept for data
 
@@ -1052,7 +1059,10 @@ def calculate_scale(data, out_dtype, allow_intercept):
     return get_slope_inter(writer) + (mn, mx)
 
 
-@np.deprecate_with_doc('Please use arraywriter classes instead')
+@deprecate_with_version('scale_min_max deprecated. Please use arraywriter '
+                        'classes instead.',
+                        '1.2',
+                        '3.0')
 def scale_min_max(mn, mx, out_type, allow_intercept):
     ''' Return scaling and intercept min, max of data, given output type