Pre-Doc: Working with type hints

[effigies]

Since 5.0, we've been starting to add type hints to NiBabel in order to enable using type checkers to catch bugs or allow type-aware IDEs to provide auto-complete suggestions.

While the API hasn't changed, these type-aware tools may promote different default practices. I want to start this discussion as a place to work out a new set of recommendations and eventually promote this to a document to go on the website.

[effigies]

Loading images

Previously, we recommended using the universal loading function:

import nibabel as nib

img = nib.load('bold.nii.gz')

Because of the number of formats that can be handled by load(), all we can say is that the return type is a FileBasedImage.

If you know the type of image you're working with, the most precise way to let type checkers know is to use the .from_filename() class method on your target class:

img = nib.Nifti1Image.from_filename('bold.nii.gz')

Here, the type checker will know that you have a Nifti1Image and all of its particular methods will be available to you. On the other hand, you might only care about the SpatialImage API and not want to allow your code to depend on the specifics of Nifti1Image. You could then write:

img: nib.spatialimages.SpatialImage = nib.Nifti1Image.from_filename('bold.nii.gz')

You can also write your own helper function that allows you to dynamically declare the API you want available at check time and raise an error if unsatisfied at runtime:

from typing import TypeVar

import nibabel as nib

ImgT = TypeVar('ImgT', bound=nib.filebasedimages.FileBasedImage)


def load_api(fname: str, api: type[ImgT]) -> ImgT:
    img = nib.load(fname)
    if not isinstance(img, api):
        raise TypeError(f'File {fname} does not implement {api} interface')
    return img


img = load_api('test.nii.gz', nib.spatialimages.SpatialImage)  # Succeeds
img = load_api('test.nii.gz', nib.Nifti2Image)  # Fails with Nifti1Image, passes with Nifti2Image

This provides you with the dynamic detection of types that nib.load() provides, while not leaving you stuck with the almost entirely useless FileBasedImage type.