Merge pull request #759 from effigies/fix/load_options

effigies · web-flow · commit e8935b0bf9f1 · 2019-05-23T13:14:25.000-04:00
RF: Move mmap/keep_file_open parameters to DataobjImage.from_file*
diff --git a/nibabel/analyze.py b/nibabel/analyze.py
@@ -988,47 +988,6 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
                            'file_map': copy_file_map(file_map)}
         return img
 
-    @classmethod
-    @kw_only_meth(1)
-    def from_filename(klass, filename, mmap=True, keep_file_open=None):
-        '''Class method to create image from filename `filename`
-
-        .. deprecated:: 2.4.1
-            ``keep_file_open='auto'`` is redundant with `False` and has
-            been deprecated. It will raise an error in nibabel 3.0.
-
-        Parameters
-        ----------
-        filename : str
-            Filename of image to load
-        mmap : {True, False, 'c', 'r'}, optional, keyword only
-            `mmap` controls the use of numpy memory mapping for reading image
-            array data.  If False, do not try numpy ``memmap`` for data array.
-            If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A
-            `mmap` value of True gives the same behavior as ``mmap='c'``.  If
-            image data file cannot be memory-mapped, ignore `mmap` value and
-            read array from file.
-        keep_file_open : { None, True, False }, optional, keyword only
-            `keep_file_open` controls whether a new file handle is created
-            every time the image is accessed, or a single file handle is
-            created and used for the lifetime of this ``ArrayProxy``. If
-            ``True``, a single file handle is created and used. If ``False``,
-            a new file handle is created every time the image is accessed.
-            The default value (``None``) will result in the value of
-            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
-
-        Returns
-        -------
-        img : Analyze Image instance
-        '''
-        if mmap not in (True, False, 'c', 'r'):
-            raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
-        file_map = klass.filespec_to_file_map(filename)
-        return klass.from_file_map(file_map, mmap=mmap,
-                                   keep_file_open=keep_file_open)
-
-    load = from_filename
-
     @staticmethod
     def _get_fileholders(file_map):
         """ Return fileholder for header and image
diff --git a/nibabel/brikhead.py b/nibabel/brikhead.py
@@ -541,40 +541,6 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
         return klass(data, hdr.get_affine(), header=hdr, extra=None,
                      file_map=file_map)
 
-    @classmethod
-    @kw_only_meth(1)
-    def from_filename(klass, filename, mmap=True, keep_file_open=None):
-        """
-        Creates an AFNIImage instance from `filename`
-
-        .. deprecated:: 2.4.1
-            ``keep_file_open='auto'`` is redundant with `False` and has
-            been deprecated. It will raise an error in nibabel 3.0.
-
-        Parameters
-        ----------
-        filename : str
-            Path to BRIK or HEAD file to be loaded
-        mmap : {True, False, 'c', 'r'}, optional, keyword only
-            `mmap` controls the use of numpy memory mapping for reading image
-            array data.  If False, do not try numpy ``memmap`` for data array.
-            If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A
-            `mmap` value of True gives the same behavior as ``mmap='c'``.  If
-            image data file cannot be memory-mapped, ignore `mmap` value and
-            read array from file.
-        keep_file_open : {None, True, False}, optional, keyword only
-            `keep_file_open` controls whether a new file handle is created
-            every time the image is accessed, or a single file handle is
-            created and used for the lifetime of this ``ArrayProxy``. If
-            ``True``, a single file handle is created and used. If ``False``,
-            a new file handle is created every time the image is accessed.
-            The default value (``None``) will result in the value of
-            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT` being used.
-        """
-        file_map = klass.filespec_to_file_map(filename)
-        return klass.from_file_map(file_map, mmap=mmap,
-                                   keep_file_open=keep_file_open)
-
     @classmethod
     def filespec_to_file_map(klass, filespec):
         """
@@ -620,7 +586,5 @@ def filespec_to_file_map(klass, filespec):
             file_map[key].filename = fname
         return file_map
 
-    load = from_filename
-
 
 load = AFNIImage.load
diff --git a/nibabel/cifti2/cifti2.py b/nibabel/cifti2/cifti2.py
@@ -29,6 +29,7 @@
 from ..dataobj_images import DataobjImage
 from ..nifti2 import Nifti2Image, Nifti2Header
 from ..arrayproxy import reshape_dataobj
+from ..keywordonly import kw_only_meth
 
 
 def _float_01(val):
@@ -1355,7 +1356,8 @@ def nifti_header(self):
         return self._nifti_header
 
     @classmethod
-    def from_file_map(klass, file_map):
+    @kw_only_meth(1)
+    def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
         """ Load a CIFTI-2 image from a file_map
 
         Parameters
@@ -1368,7 +1370,8 @@ def from_file_map(klass, file_map):
             Returns a Cifti2Image
          """
         from .parse_cifti2 import _Cifti2AsNiftiImage, Cifti2Extension
-        nifti_img = _Cifti2AsNiftiImage.from_file_map(file_map)
+        nifti_img = _Cifti2AsNiftiImage.from_file_map(file_map, mmap=mmap,
+                                                      keep_file_open=keep_file_open)
 
         # Get cifti2 header
         for item in nifti_img.header.extensions:
@@ -1380,7 +1383,7 @@ def from_file_map(klass, file_map):
                              'extension')
 
         # Construct cifti image.
-        # User array proxy object where possible
+        # Use array proxy object where possible
         dataobj = nifti_img.dataobj
         return Cifti2Image(reshape_dataobj(dataobj, dataobj.shape[4:]),
                            header=cifti_header,
@@ -1455,33 +1458,5 @@ def set_data_dtype(self, dtype):
         self._nifti_header.set_data_dtype(dtype)
 
 
-def load(filename):
-    """ Load cifti2 from `filename`
-
-    Parameters
-    ----------
-    filename : str
-        filename of image to be loaded
-
-    Returns
-    -------
-    img : Cifti2Image
-        cifti image instance
-
-    Raises
-    ------
-    ImageFileError: if `filename` doesn't look like cifti
-    IOError : if `filename` does not exist
-    """
-    return Cifti2Image.from_filename(filename)
-
-
-def save(img, filename):
-    """ Save cifti to `filename`
-
-    Parameters
-    ----------
-    filename : str
-        filename to which to save image
-    """
-    Cifti2Image.instance_to_filename(img, filename)
+load = Cifti2Image.from_filename
+save = Cifti2Image.instance_to_filename
diff --git a/nibabel/dataobj_images.py b/nibabel/dataobj_images.py
@@ -11,6 +11,7 @@
 import numpy as np
 
 from .filebasedimages import FileBasedImage
+from .keywordonly import kw_only_meth
 from .deprecated import deprecate_with_version
 
 
@@ -404,3 +405,82 @@ def get_shape(self):
         """ Return shape for image
         """
         return self.shape
+
+    @classmethod
+    @kw_only_meth(1)
+    def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
+        ''' Class method to create image from mapping in ``file_map``
+
+        .. deprecated:: 2.4.1
+            ``keep_file_open='auto'`` is redundant with `False` and has
+            been deprecated. It will raise an error in nibabel 3.0.
+
+        Parameters
+        ----------
+        file_map : dict
+            Mapping with (kay, value) pairs of (``file_type``, FileHolder
+            instance giving file-likes for each file needed for this image
+            type.
+        mmap : {True, False, 'c', 'r'}, optional, keyword only
+            `mmap` controls the use of numpy memory mapping for reading image
+            array data.  If False, do not try numpy ``memmap`` for data array.
+            If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A
+            `mmap` value of True gives the same behavior as ``mmap='c'``.  If
+            image data file cannot be memory-mapped, ignore `mmap` value and
+            read array from file.
+        keep_file_open : { None, True, False }, optional, keyword only
+            `keep_file_open` controls whether a new file handle is created
+            every time the image is accessed, or a single file handle is
+            created and used for the lifetime of this ``ArrayProxy``. If
+            ``True``, a single file handle is created and used. If ``False``,
+            a new file handle is created every time the image is accessed.
+            If ``file_map`` refers to an open file handle, this setting has no
+            effect. The default value (``None``) will result in the value of
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
+
+        Returns
+        -------
+        img : DataobjImage instance
+        '''
+        raise NotImplementedError
+
+    @classmethod
+    @kw_only_meth(1)
+    def from_filename(klass, filename, mmap=True, keep_file_open=None):
+        '''Class method to create image from filename `filename`
+
+        .. deprecated:: 2.4.1
+            ``keep_file_open='auto'`` is redundant with `False` and has
+            been deprecated. It will raise an error in nibabel 3.0.
+
+        Parameters
+        ----------
+        filename : str
+            Filename of image to load
+        mmap : {True, False, 'c', 'r'}, optional, keyword only
+            `mmap` controls the use of numpy memory mapping for reading image
+            array data.  If False, do not try numpy ``memmap`` for data array.
+            If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A
+            `mmap` value of True gives the same behavior as ``mmap='c'``.  If
+            image data file cannot be memory-mapped, ignore `mmap` value and
+            read array from file.
+        keep_file_open : { None, True, False }, optional, keyword only
+            `keep_file_open` controls whether a new file handle is created
+            every time the image is accessed, or a single file handle is
+            created and used for the lifetime of this ``ArrayProxy``. If
+            ``True``, a single file handle is created and used. If ``False``,
+            a new file handle is created every time the image is accessed.
+            The default value (``None``) will result in the value of
+            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
+
+        Returns
+        -------
+        img : DataobjImage instance
+        '''
+        if mmap not in (True, False, 'c', 'r'):
+            raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
+        file_map = klass.filespec_to_file_map(filename)
+        return klass.from_file_map(file_map, mmap=mmap,
+                                   keep_file_open=keep_file_open)
+
+    load = from_filename
diff --git a/nibabel/ecat.py b/nibabel/ecat.py
@@ -54,6 +54,7 @@
 from .arraywriters import make_array_writer
 from .wrapstruct import WrapStruct
 from .fileslice import canonical_slicers, predict_shape, slice2outax
+from .keywordonly import kw_only_meth
 from .deprecated import deprecate_with_version
 
 BLOCK_SIZE = 512
@@ -873,7 +874,8 @@ def _get_fileholders(file_map):
         return file_map['header'], file_map['image']
 
     @classmethod
-    def from_file_map(klass, file_map):
+    @kw_only_meth(1)
+    def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
         """class method to create image from mapping
         specified in file_map
         """
diff --git a/nibabel/freesurfer/mghformat.py b/nibabel/freesurfer/mghformat.py
@@ -536,17 +536,18 @@ def filespec_to_file_map(klass, filespec):
     @classmethod
     @kw_only_meth(1)
     def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
-        '''Load image from ``file_map``
+        ''' Class method to create image from mapping in ``file_map``
 
         .. deprecated:: 2.4.1
             ``keep_file_open='auto'`` is redundant with `False` and has
             been deprecated. It will raise an error in nibabel 3.0.
 
         Parameters
         ----------
-        file_map : None or mapping, optional
-           files mapping.  If None (default) use object's ``file_map``
-           attribute instead
+        file_map : dict
+            Mapping with (kay, value) pairs of (``file_type``, FileHolder
+            instance giving file-likes for each file needed for this image
+            type.
         mmap : {True, False, 'c', 'r'}, optional, keyword only
             `mmap` controls the use of numpy memory mapping for reading image
             array data.  If False, do not try numpy ``memmap`` for data array.
@@ -563,6 +564,10 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
             If ``file_map`` refers to an open file handle, this setting has no
             effect. The default value (``None``) will result in the value of
             ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
+
+        Returns
+        -------
+        img : MGHImage instance
         '''
         if mmap not in (True, False, 'c', 'r'):
             raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
@@ -577,47 +582,6 @@ def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
         img = klass(data, affine, header, file_map=file_map)
         return img
 
-    @classmethod
-    @kw_only_meth(1)
-    def from_filename(klass, filename, mmap=True, keep_file_open=None):
-        ''' Class method to create image from filename ``filename``
-
-        .. deprecated:: 2.4.1
-            ``keep_file_open='auto'`` is redundant with `False` and has
-            been deprecated. It will raise an error in nibabel 3.0.
-
-        Parameters
-        ----------
-        filename : str
-            Filename of image to load
-        mmap : {True, False, 'c', 'r'}, optional, keyword only
-            `mmap` controls the use of numpy memory mapping for reading image
-            array data.  If False, do not try numpy ``memmap`` for data array.
-            If one of {'c', 'r'}, try numpy memmap with ``mode=mmap``.  A
-            `mmap` value of True gives the same behavior as ``mmap='c'``.  If
-            image data file cannot be memory-mapped, ignore `mmap` value and
-            read array from file.
-        keep_file_open : { None, True, False }, optional, keyword only
-            `keep_file_open` controls whether a new file handle is created
-            every time the image is accessed, or a single file handle is
-            created and used for the lifetime of this ``ArrayProxy``. If
-            ``True``, a single file handle is created and used. If ``False``,
-            a new file handle is created every time the image is accessed.
-            The default value (``None``) will result in the value of
-            ``nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT`` being used.
-
-        Returns
-        -------
-        img : MGHImage instance
-        '''
-        if mmap not in (True, False, 'c', 'r'):
-            raise ValueError("mmap should be one of {True, False, 'c', 'r'}")
-        file_map = klass.filespec_to_file_map(filename)
-        return klass.from_file_map(file_map, mmap=mmap,
-                                   keep_file_open=keep_file_open)
-
-    load = from_filename
-
     def to_file_map(self, file_map=None):
         ''' Write image to `file_map` or contained ``self.file_map``
 
diff --git a/nibabel/minc1.py b/nibabel/minc1.py
@@ -17,6 +17,7 @@
 from .spatialimages import SpatialHeader, SpatialImage
 from .fileslice import canonical_slicers
 
+from .keywordonly import kw_only_meth
 from .deprecated import FutureWarningMixin
 
 _dt_dict = {
@@ -310,7 +311,9 @@ class Minc1Image(SpatialImage):
     ImageArrayProxy = MincImageArrayProxy
 
     @classmethod
-    def from_file_map(klass, file_map):
+    @kw_only_meth(1)
+    def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
+        # Note that mmap and keep_file_open are included for proper
         with file_map['image'].get_prepare_fileobj() as fobj:
             minc_file = Minc1File(netcdf_file(fobj))
             affine = minc_file.get_affine()
diff --git a/nibabel/minc2.py b/nibabel/minc2.py
@@ -27,6 +27,7 @@
 """
 import numpy as np
 
+from .keywordonly import kw_only_meth
 from .optpkg import optional_package
 h5py, have_h5py, setup_module = optional_package('h5py')
 
@@ -158,7 +159,8 @@ class Minc2Image(Minc1Image):
     header_class = Minc2Header
 
     @classmethod
-    def from_file_map(klass, file_map):
+    @kw_only_meth(1)
+    def from_file_map(klass, file_map, mmap=True, keep_file_open=None):
         holder = file_map['image']
         if holder.filename is None:
             raise MincError('MINC2 needs filename for load')
diff --git a/nibabel/tests/test_dataobj_images.py b/nibabel/tests/test_dataobj_images.py
diff --git a/nibabel/tests/test_image_api.py b/nibabel/tests/test_image_api.py
