nanobind 2.0.0: How can I customize the stubgen type used for Eigen arguments/return parameters?

[breathe]

I'm trying to upgrade to nanobind 2 and will love to get rid of my manually maintained .pyi files.

Below is a random snippet from the generated .pyi file which demonstrates the generated types used for the Eigen:: matrix/vector types. These types are considered to be ArrayLike by nanobind's typegen.

from numpy.typing import ArrayLike


class AmbiguityEstimators:
    def __init__(self, arg0: Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')], arg1: AmbiguityFilterSettings, /) -> None: ...

    def reset(self, reset_flags: Annotated[ArrayLike, dict(dtype='bool', shape=(None), order='C')], carrier_smoothed_code_measurements: Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')]) -> None: ...

    def estimate(self, carrier_unsmoothed_code_measurements: Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')], carrier_position_measurements: Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')], carrier_init_position_measurements: Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')], loss_of_lock_flags: Annotated[ArrayLike, dict(dtype='bool', shape=(None), order='C')], likelihood_mixing: bool = True) -> None: ...

    @property
    def ambiguities(self) -> Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')]: ...

    @property
    def cov(self) -> Annotated[ArrayLike, dict(dtype='float64', shape=(None), order='C')]: ...

    @property
    def __len__(self) -> int: ...

My previous manually maintained types used numpy.typing.NDArray everywhere -- and in fact if I string replace ArrayLike with NDArray in the generated .pyi file, it all seems to work as I want. ArrayLike however, is apparently a MUCH broader type and leads to lots of type checking errors in my codebase which are spurious relative to the actual constraints I want the type system to enforce for my codebase.

Definition of ArrayLike:

    ArrayLike = Buffer | _DualArrayLike[
        dtype[Any],
        Union[bool, int, float, complex, str, bytes],
    ]

vs NDArray

NDArray = ndarray[Any, dtype[_ScalarType_co]]

I tried values like these in a pattern file but doesn't work ...

numpy.typing.ArrayLike:
  numpy.typing.NDArray

ArrayLike:
  NDArray

Using pattern file "/Users/ncohen/software/zephr/zephyrus/zephyrus/lib/native/type_pattern_list.txt" ..
  - loaded 2 patterns.

Module "zephyrus_native_ext" ..
  - importing ..
  - analyzing ..
  - warning: rule 'numpy.typing.ArrayLike' did not match any elements.
  - warning: rule 'ArrayLike' did not match any elements.
  - applied 0 patterns.
  - writing stub "/Users/ncohen/software/zephr/zephyrus/zephyrus/lib/native/zephyrus_native_ext.pyi" ..

(NOTE: there's a typo in the nanobind docs -- and I've confirmed that the behavior I am trying to get doesn't happen even when using the correct argument to nanobind_add_stubgen() -- fix for the doc bug here: #631

[wjakob]

This is related to #442. The problem is that nanobind ndarray annotations are quite expressive, and this doesn't map well onto the existing Python typing infrastructure (especially when considering that the library supports many nd-array frameworks besides NumPy). I'm interested in resolving this but don't quite know what's the best way to proceed. Perhaps you can take a look into #442 and chime in to see if we can find a solution that is agreeable to everyone?