Merge pull request #1179 from effigies/type/primary_image_api

ENH: Annotate SpatialImage API, improve  superclass annotations

Author: effigies

nibabel/analyze.py

@@ -1064,5 +1064,5 @@ def to_file_map(self, file_map=None, dtype=None):
             hdr['scl_inter'] = inter
 
 
-load = AnalyzeImage.load
+load = AnalyzeImage.from_filename
 save = AnalyzeImage.instance_to_filename

nibabel/arrayproxy.py

@@ -59,6 +59,9 @@
 if ty.TYPE_CHECKING:  # pragma: no cover
     import numpy.typing as npt
 
+    # Taken from numpy/__init__.pyi
+    _DType = ty.TypeVar('_DType', bound=np.dtype[ty.Any])
+
 
 class ArrayLike(ty.Protocol):
     """Protocol for numpy ndarray-like objects
@@ -68,9 +71,19 @@ class ArrayLike(ty.Protocol):
     """
 
     shape: tuple[int, ...]
-    ndim: int
 
-    def __array__(self, dtype: npt.DTypeLike | None = None, /) -> npt.NDArray:
+    @property
+    def ndim(self) -> int:
+        ...  # pragma: no cover
+
+    # If no dtype is passed, any dtype might be returned, depending on the array-like
+    @ty.overload
+    def __array__(self, dtype: None = ..., /) -> np.ndarray[ty.Any, np.dtype[ty.Any]]:
+        ...  # pragma: no cover
+
+    # Any dtype might be passed, and *that* dtype must be returned
+    @ty.overload
+    def __array__(self, dtype: _DType, /) -> np.ndarray[ty.Any, _DType]:
         ...  # pragma: no cover
 
     def __getitem__(self, key, /) -> npt.NDArray:

nibabel/brikhead.py

@@ -564,4 +564,4 @@ def filespec_to_file_map(klass, filespec):
         return file_map
 
 
-load = AFNIImage.load
+load = AFNIImage.from_filename

nibabel/dataobj_images.py

@@ -20,12 +20,14 @@
 if ty.TYPE_CHECKING:  # pragma: no cover
     import numpy.typing as npt
 
+ArrayImgT = ty.TypeVar('ArrayImgT', bound='DataobjImage')
+
 
 class DataobjImage(FileBasedImage):
     """Template class for images that have dataobj data stores"""
 
     _data_cache: np.ndarray | None
-    _fdata_cache: np.ndarray | None
+    _fdata_cache: np.ndarray[ty.Any, np.dtype[np.floating]] | None
 
     def __init__(
         self,
@@ -222,7 +224,7 @@ def get_fdata(
         self,
         caching: ty.Literal['fill', 'unchanged'] = 'fill',
         dtype: npt.DTypeLike = np.float64,
-    ) -> np.ndarray:
+    ) -> np.ndarray[ty.Any, np.dtype[np.floating]]:
         """Return floating point image data with necessary scaling applied
 
         The image ``dataobj`` property can be an array proxy or an array.  An
@@ -421,12 +423,12 @@ def ndim(self) -> int:
 
     @classmethod
     def from_file_map(
-        klass,
+        klass: type[ArrayImgT],
         file_map: FileMap,
         *,
         mmap: bool | ty.Literal['c', 'r'] = True,
         keep_file_open: bool | None = None,
-    ):
+    ) -> ArrayImgT:
         """Class method to create image from mapping in ``file_map``
 
         Parameters
@@ -460,12 +462,12 @@ def from_file_map(
 
     @classmethod
     def from_filename(
-        klass,
+        klass: type[ArrayImgT],
         filename: FileSpec,
         *,
         mmap: bool | ty.Literal['c', 'r'] = True,
         keep_file_open: bool | None = None,
-    ):
+    ) -> ArrayImgT:
         """Class method to create image from filename `filename`
 
         Parameters

nibabel/ecat.py

@@ -747,12 +747,14 @@ def __getitem__(self, sliceobj):
 class EcatImage(SpatialImage):
     """Class returns a list of Ecat images, with one image(hdr/data) per frame"""
 
-    _header = EcatHeader
-    header_class = _header
+    header_class = EcatHeader
+    subheader_class = EcatSubHeader
     valid_exts = ('.v',)
-    _subheader = EcatSubHeader
     files_types = (('image', '.v'), ('header', '.v'))
 
+    _header: EcatHeader
+    _subheader: EcatSubHeader
+
     ImageArrayProxy = EcatImageArrayProxy
 
     def __init__(self, dataobj, affine, header, subheader, mlist, extra=None, file_map=None):
@@ -879,14 +881,14 @@ def from_file_map(klass, file_map, *, mmap=True, keep_file_open=None):
         hdr_file, img_file = klass._get_fileholders(file_map)
         # note header and image are in same file
         hdr_fid = hdr_file.get_prepare_fileobj(mode='rb')
-        header = klass._header.from_fileobj(hdr_fid)
+        header = klass.header_class.from_fileobj(hdr_fid)
         hdr_copy = header.copy()
         # LOAD MLIST
         mlist = np.zeros((header['num_frames'], 4), dtype=np.int32)
         mlist_data = read_mlist(hdr_fid, hdr_copy.endianness)
         mlist[: len(mlist_data)] = mlist_data
         # LOAD SUBHEADERS
-        subheaders = klass._subheader(hdr_copy, mlist, hdr_fid)
+        subheaders = klass.subheader_class(hdr_copy, mlist, hdr_fid)
         # LOAD DATA
         # Class level ImageArrayProxy
         data = klass.ImageArrayProxy(subheaders)

nibabel/filebasedimages.py

@@ -24,6 +24,11 @@
 FileMap = ty.Mapping[str, FileHolder]
 FileSniff = ty.Tuple[bytes, str]
 
+ImgT = ty.TypeVar('ImgT', bound='FileBasedImage')
+HdrT = ty.TypeVar('HdrT', bound='FileBasedHeader')
+
+StreamImgT = ty.TypeVar('StreamImgT', bound='SerializableImage')
+
 
 class ImageFileError(Exception):
     pass
@@ -33,7 +38,7 @@ class FileBasedHeader:
     """Template class to implement header protocol"""
 
     @classmethod
-    def from_header(klass, header=None):
+    def from_header(klass: type[HdrT], header: FileBasedHeader | ty.Mapping | None = None) -> HdrT:
         if header is None:
             return klass()
         # I can't do isinstance here because it is not necessarily true
@@ -47,19 +52,19 @@ def from_header(klass, header=None):
         )
 
     @classmethod
-    def from_fileobj(klass, fileobj: io.IOBase):
-        raise NotImplementedError
+    def from_fileobj(klass: type[HdrT], fileobj: io.IOBase) -> HdrT:
+        raise NotImplementedError  # pragma: no cover
 
-    def write_to(self, fileobj: io.IOBase):
-        raise NotImplementedError
+    def write_to(self, fileobj: io.IOBase) -> None:
+        raise NotImplementedError  # pragma: no cover
 
-    def __eq__(self, other):
-        raise NotImplementedError
+    def __eq__(self, other: object) -> bool:
+        raise NotImplementedError  # pragma: no cover
 
-    def __ne__(self, other):
+    def __ne__(self, other: object) -> bool:
         return not self == other
 
-    def copy(self) -> FileBasedHeader:
+    def copy(self: HdrT) -> HdrT:
         """Copy object to independent representation
 
         The copy should not be affected by any changes to the original
@@ -153,6 +158,7 @@ class FileBasedImage:
     """
 
     header_class: Type[FileBasedHeader] = FileBasedHeader
+    _header: FileBasedHeader
     _meta_sniff_len: int = 0
     files_types: tuple[tuple[str, str | None], ...] = (('image', None),)
     valid_exts: tuple[str, ...] = ()
@@ -186,7 +192,7 @@ def __init__(
         self._header = self.header_class.from_header(header)
         if extra is None:
             extra = {}
-        self.extra = extra
+        self.extra = dict(extra)
 
         if file_map is None:
             file_map = self.__class__.make_file_map()
@@ -196,7 +202,7 @@ def __init__(
     def header(self) -> FileBasedHeader:
         return self._header
 
-    def __getitem__(self, key):
+    def __getitem__(self, key) -> None:
         """No slicing or dictionary interface for images"""
         raise TypeError('Cannot slice image objects.')
 
@@ -221,7 +227,7 @@ def get_filename(self) -> str | None:
         characteristic_type = self.files_types[0][0]
         return self.file_map[characteristic_type].filename
 
-    def set_filename(self, filename: str):
+    def set_filename(self, filename: str) -> None:
         """Sets the files in the object from a given filename
 
         The different image formats may check whether the filename has
@@ -239,16 +245,16 @@ def set_filename(self, filename: str):
         self.file_map = self.__class__.filespec_to_file_map(filename)
 
     @classmethod
-    def from_filename(klass, filename: FileSpec):
+    def from_filename(klass: type[ImgT], filename: FileSpec) -> ImgT:
         file_map = klass.filespec_to_file_map(filename)
         return klass.from_file_map(file_map)
 
     @classmethod
-    def from_file_map(klass, file_map: FileMap):
-        raise NotImplementedError
+    def from_file_map(klass: type[ImgT], file_map: FileMap) -> ImgT:
+        raise NotImplementedError  # pragma: no cover
 
     @classmethod
-    def filespec_to_file_map(klass, filespec: FileSpec):
+    def filespec_to_file_map(klass, filespec: FileSpec) -> FileMap:
         """Make `file_map` for this class from filename `filespec`
 
         Class method
@@ -282,7 +288,7 @@ def filespec_to_file_map(klass, filespec: FileSpec):
             file_map[key] = FileHolder(filename=fname)
         return file_map
 
-    def to_filename(self, filename: FileSpec, **kwargs):
+    def to_filename(self, filename: FileSpec, **kwargs) -> None:
         r"""Write image to files implied by filename string
 
         Parameters
@@ -301,11 +307,11 @@ def to_filename(self, filename: FileSpec, **kwargs):
         self.file_map = self.filespec_to_file_map(filename)
         self.to_file_map(**kwargs)
 
-    def to_file_map(self, file_map: FileMap | None = None, **kwargs):
-        raise NotImplementedError
+    def to_file_map(self, file_map: FileMap | None = None, **kwargs) -> None:
+        raise NotImplementedError  # pragma: no cover
 
     @classmethod
-    def make_file_map(klass, mapping: ty.Mapping[str, str | io.IOBase] | None = None):
+    def make_file_map(klass, mapping: ty.Mapping[str, str | io.IOBase] | None = None) -> FileMap:
         """Class method to make files holder for this image type
 
         Parameters
@@ -338,7 +344,7 @@ def make_file_map(klass, mapping: ty.Mapping[str, str | io.IOBase] | None = None
     load = from_filename
 
     @classmethod
-    def instance_to_filename(klass, img: FileBasedImage, filename: FileSpec):
+    def instance_to_filename(klass, img: FileBasedImage, filename: FileSpec) -> None:
         """Save `img` in our own format, to name implied by `filename`
 
         This is a class method
@@ -354,28 +360,28 @@ def instance_to_filename(klass, img: FileBasedImage, filename: FileSpec):
         img.to_filename(filename)
 
     @classmethod
-    def from_image(klass, img: FileBasedImage):
+    def from_image(klass: type[ImgT], img: FileBasedImage) -> ImgT:
         """Class method to create new instance of own class from `img`
 
         Parameters
         ----------
-        img : ``spatialimage`` instance
+        img : ``FileBasedImage`` instance
            In fact, an object with the API of ``FileBasedImage``.
 
         Returns
         -------
-        cimg : ``spatialimage`` instance
+        img : ``FileBasedImage`` instance
            Image, of our own class
         """
-        raise NotImplementedError()
+        raise NotImplementedError  # pragma: no cover
 
     @classmethod
     def _sniff_meta_for(
         klass,
         filename: FileSpec,
         sniff_nbytes: int,
         sniff: FileSniff | None = None,
-    ):
+    ) -> FileSniff | None:
         """Sniff metadata for image represented by `filename`
 
         Parameters
@@ -425,7 +431,7 @@ def path_maybe_image(
         filename: FileSpec,
         sniff: FileSniff | None = None,
         sniff_max: int = 1024,
-    ):
+    ) -> tuple[bool, FileSniff | None]:
         """Return True if `filename` may be image matching this class
 
         Parameters
@@ -527,14 +533,14 @@ class SerializableImage(FileBasedImage):
     """
 
     @classmethod
-    def _filemap_from_iobase(klass, io_obj: io.IOBase):
+    def _filemap_from_iobase(klass, io_obj: io.IOBase) -> FileMap:
         """For single-file image types, make a file map with the correct key"""
         if len(klass.files_types) > 1:
             raise NotImplementedError('(de)serialization is undefined for multi-file images')
         return klass.make_file_map({klass.files_types[0][0]: io_obj})
 
     @classmethod
-    def from_stream(klass, io_obj: io.IOBase):
+    def from_stream(klass: type[StreamImgT], io_obj: io.IOBase) -> StreamImgT:
         """Load image from readable IO stream
 
         Convert to BytesIO to enable seeking, if input stream is not seekable
@@ -548,7 +554,7 @@ def from_stream(klass, io_obj: io.IOBase):
             io_obj = io.BytesIO(io_obj.read())
         return klass.from_file_map(klass._filemap_from_iobase(io_obj))
 
-    def to_stream(self, io_obj: io.IOBase, **kwargs):
+    def to_stream(self, io_obj: io.IOBase, **kwargs) -> None:
         r"""Save image to writable IO stream
 
         Parameters
@@ -561,7 +567,7 @@ def to_stream(self, io_obj: io.IOBase, **kwargs):
         self.to_file_map(self._filemap_from_iobase(io_obj), **kwargs)
 
     @classmethod
-    def from_bytes(klass, bytestring: bytes):
+    def from_bytes(klass: type[StreamImgT], bytestring: bytes) -> StreamImgT:
         """Construct image from a byte string
 
         Class method
@@ -592,7 +598,9 @@ def to_bytes(self, **kwargs) -> bytes:
         return bio.getvalue()
 
     @classmethod
-    def from_url(klass, url: str | request.Request, timeout: float = 5):
+    def from_url(
+        klass: type[StreamImgT], url: str | request.Request, timeout: float = 5
+    ) -> StreamImgT:
         """Retrieve and load an image from a URL
 
         Class method

nibabel/freesurfer/mghformat.py

@@ -589,5 +589,5 @@ def _affine2header(self):
         hdr['Pxyz_c'] = c_ras
 
 
-load = MGHImage.load
+load = MGHImage.from_filename
 save = MGHImage.instance_to_filename

nibabel/minc1.py

@@ -334,4 +334,4 @@ def from_file_map(klass, file_map, *, mmap=True, keep_file_open=None):
         return klass(data, affine, header, extra=None, file_map=file_map)
 
 
-load = Minc1Image.load
+load = Minc1Image.from_filename

nibabel/minc2.py

@@ -172,4 +172,4 @@ def from_file_map(klass, file_map, *, mmap=True, keep_file_open=None):
         return klass(data, affine, header, extra=None, file_map=file_map)
 
 
-load = Minc2Image.load
+load = Minc2Image.from_filename

nibabel/nifti1.py

@@ -25,10 +25,10 @@
 from .batteryrunners import Report
 from .casting import have_binary128
 from .deprecated import alert_future_error
-from .filebasedimages import SerializableImage
+from .filebasedimages import ImageFileError, SerializableImage
 from .optpkg import optional_package
 from .quaternions import fillpositive, mat2quat, quat2mat
-from .spatialimages import HeaderDataError, ImageFileError
+from .spatialimages import HeaderDataError
 from .spm99analyze import SpmAnalyzeHeader
 from .volumeutils import Recoder, endian_codes, make_dt_codes