为 NumPy 数组子类正确标注 __getitem__ 方法的类型提示
NumPy 的 ndarray 子类在运行时能保持类型（如切片返回原 subclass 实例），但静态类型检查器（如 Pyright）因缺乏泛型返回类型推导而报错；需手动重写 __getitem__ 并使用 Self 或协变泛型确保类型安全。
numpy 的 `ndarray` 子类在运行时能保持类型（如切片返回原 subclass 实例），但静态类型检查器（如 pyright）因缺乏泛型返回类型推导而报错；需手动重写 `__getitem__` 并使用 `self` 或协变泛型确保类型安全。
在 NumPy 中，通过 view() 机制实现的子类（如 ArraySubClass）天然支持“切片保留子类类型”的行为——这是由 ndarray.__getitem__ 在底层调用 __array_finalize__ 保证的。然而，类型检查器无法执行运行时逻辑，它仅依赖 .pyi 文件中定义的类型签名。当前 NumPy 官方类型存根（如 numpy/__init__.pyi）将 ndarray.__getitem__ 声明为：
def __getitem__(self, key: Union[
NDArray[integer[Any]],
NDArray[bool_],
Tuple[Union[NDArray[integer[Any]], NDArray[bool_]], ...]
]) -> ndarray[Any, _DType_co]: ...
该签名明确返回 ndarray（基类），而非调用者实际类型（如 ArraySubClass）。因此，即使 x[:, 0] 运行时是 ArraySubClass 实例，Pyright 仍将其推断为 ndarray[Any, Any]，导致形参类型不匹配错误。
✅ 正确解法：显式重写 __getitem__ 并标注 -> Self
自 Python 3.11 起，typing.Self 是解决此类“方法返回自身类型”问题的标准方案；对于更早版本，可使用 TypeVar 绑定到类本身。以下是推荐实现（兼容 Python ≥3.11）：
import numpy as np
from typing import Self, Union, Tuple, Any
class ArraySubClass(np.ndarray):
def __new__(cls, input_array: np.ndarray) -> Self:
obj = np.asarray(input_array).view(cls)
return obj
def __getitem__(self, key: Union[
np.ndarray,
np.bool_,
Tuple[Union[np.ndarray, np.bool_], ...]
]) -> Self:
# 调用父类实现，保证行为一致
result = super().__getitem__(key)
# 强制视图转换为当前子类（运行时安全，且对类型检查器明确）
if not isinstance(result, ArraySubClass):
result = result.view(ArraySubClass)
return result
? 关键点说明：
- -> Self 明确告诉类型检查器：无论 key 是什么，只要输入是 ArraySubClass，输出必然是 ArraySubClass；
- result.view(ArraySubClass) 在运行时确保类型一致性（尽管通常 __getitem__ 已返回子类，此步作为防御性保障）；
- 签名中 np.ndarray 和 np.bool_ 等类型应根据实际需求细化（例如用 np.ndarray[np.dtype[np.int64]]），此处为简洁示例。
⚠️ 注意事项与最佳实践
-
不要盲目覆盖所有魔术方法：仅当类型检查器报错且影响开发体验时才重写 __getitem__；过度标注可能增加维护成本。
-
避免 # type: ignore 滥用：临时压制错误会掩盖真实类型问题，应优先修复类型声明。
-
验证类型检查效果：在重写后，Pyright 应不再报错：
def f(x: ArraySubClass) -> None: print(x.shape) arr = ArraySubClass(np.zeros((3, 3))) f(arr[:, 0]) # ✅ 通过类型检查 -
兼容旧 Python 版本：若需支持 Python Self。
总之，这不是 Pyright 的 bug，而是 NumPy 类型存根设计上的历史局限。通过主动提供精准的 Self 返回类型，开发者可在不牺牲运行时行为的前提下，获得完整的静态类型安全保障。