Improve type hints of interface classes that inherit from BaseInterface

[mcsitter]

Goal

Improve static typing (e.g., mypy, IDE support) for Nipype interface classes that inherit from BaseInterface, so that concrete types of inputs and outputs are correctly inferred.

Background

Inputs and outputs are instantiated dynamically from input_spec / output_spec in BaseInterfaces __init__ function, which prevents mypy from inferring their concrete types in subclasses.
Since InputSpec and OutputSpec classes inherit from traits.HasTraits, and recent versions of traits include type stubs, type hinting these classes is now feasible.

Option 1: Explicit annotations in subclasses

Add inputs: FooInputSpec / outputs: FooOutputSpec to each interface class.
Example:

class NewSegment(SPMCommand):
    input_spec = NewSegmentInputSpec
    output_spec = NewSegmentOutputSpec

    inputs: NewSegmentInputSpec
    outputs: NewSegmentOutputSpec

Pros: Simple, minimal change, no base-class refactor needed
Cons: Must be repeated for every interface

Option 2: Generic base / command classes

Make Interface (and intermediate command classes) use Generic types to propagate input/output types.

Example:

from typing import TypeVar, Generic

# Type variables for input/output specs
I = TypeVar("I", bound=BaseInterfaceInputSpec)
O = TypeVar("O", bound=BaseInterfaceOutputSpec)

# Generic base interface
class Interface(Generic[I, O]):
    inputs: I
    outputs: O

# Concrete interface specifying generics
class NewSegment(BaseInterface[NewSegmentInputSpec, NewSegmentOutputSpec]):
    input_spec = NewSegmentInputSpec
    output_spec = NewSegmentOutputSpec

# Usage example
seg = NewSegment()
seg.inputs.warping_regularization  # mypy knows type
seg.outputs.bias_corrected_images  # mypy knows type

Pros: DRY, scalable, propagates types
Cons: Requires broader changes

Next steps

I’d like feedback on whether this is desirable and which approach fits Nipype best. In my local install I tried Option 1, but Option 2 may be better overall, as it would also allow base-class methods to have typed return values.
I’m happy to start with a small, incremental PR for SPM interfaces using either approach, based on your preference.

Open to suggestions and alternatives.

[effigies]

I do not personally have a lot of enthusiasm for this, as my experience is that adding type annotations to legacy codebases is an exercise in frustration. One small change leads to a large number of other changes.

That said, if you're interested, I'd suggest option 2. There's no need for BaseInterfaceInnputSpec/BaseInterfaceOutputSpec. Just use TraitedSpec.

If you're going to annotate, you should test your annotations, so add a type-checking environment to tox. We should also avoid importing from typing at runtime. Use the following idiom:

TYPE_CHECKING = False
if TYPE_CHECKING:
    from typing import TypeVar, Generic
    ...

You may need to use from __future__ import annotations to keep things working. Hopefully it doesn't need to be added to every file.