NumPy 2.x 类型注解增强泛型化numpy.object_标量类型全解析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpynumpy.object_是 NumPy 中用于承载任意 Python 对象的标量类型其对应的 dtype 在科学计算与元数据传递场景中广泛使用。本文基于 NumPy 仓库的 typing 更新公告32075.typing.rst系统讲解numpy.object_从普通类升级为泛型类的变更其类型参数代表被包裹的 Python 对象缺省时默认为Any。读完本文你将掌握np.object_[T]的正确书写方式、它与NDArray[np.object_[T]]的配合用法以及这一变更如何在静态类型检查中显著提升 object-dtype 数组的类型推断精度。变更速览object_泛型化带来的能力本次变更的核心内容如下源自 32075.typing.rstnumpy.object_标量类型现在是一个泛型类型其类型参数表示被包裹的 Python 对象省略时默认为Any。也就是说在静态类型层面从前的写法import numpy as np from typing import Any x: np.ndarray[Any, np.dtype[np.object_]] # 丢失了元素类型信息现在可以升级为携带元素类型信息的写法x: np.ndarray[Any, np.dtype[np.object_[str]]] # 元素为 str 的 object 数组 y: np.ndarray[Any, np.dtype[np.object_[int]]] # 元素为 int 的 object 数组 z: np.ndarray[Any, np.dtype[np.object_]] # 缺省即 np.object_[Any]元素类型未知省略类型参数时默认为Any因此np.object_与np.object_[Any]在类型检查中等价旧的写法依然完全兼容不会破坏既有类型标注。类型桩中的泛型定义与运行时实现类型桩定义在仓库主类型桩文件 numpy/init.pyi 中object_被定义为一个final泛型类# NOTE: The object_ constructor returns the passed object, so instances with type # object_ cannot exists (at runtime). final class object_(generic[_ItemT_co], Generic[_ItemT_co]): classmethod # object_ is (also) subscriptable at runtime def __class_getitem__T - T: ...几个值得注意的设计细节final装饰object_被标记为最终类不允许被继承这是对运行时行为其构造器直接返回传入对象的类型层面约束协变类型参数_ItemT_co泛型参数使用协变covariant标注表示包裹的对象类型可以向其父类型收缩/放宽这使np.object_[int]可以被安全地视为np.object_[object]等运行时__class_getitem__同样可用类型桩中特别注明object_在运行时也可被下标化subscriptable见下节。运行时__class_getitem__的 C 实现在底层 C 实现 numpy/_core/src/multiarray/scalartypes.c.src 中object_的__class_getitem__被显式注册其注释直接说明了设计意图/* Returns np.object_ itself, so that e.g. np.object_[str] stays dtype-like */ static PyObject * objecttype_class_getitem(PyObject *cls, PyObject *NPY_UNUSED(args)) { return Py_NewRef(cls); }这意味着运行时np.object_[str]求值结果就是np.object_本身——类型参数只对静态类型检查有意义不会在运行时产生新的类对象。这一行为由仓库测试 numpy/_core/tests/test_scalar_methods.py 明确验证if cls in {np.bool, np.datetime64, np.object_}: ... assert np.object_[int] is np.object_因此np.object_[T]既是合法的 dtype 用法np.dtype[np.object_[T]]又不会给运行时带来任何额外开销或行为变化是纯类型层面的增强。泛型化带来的具体收益数组元素类型被保留object_泛型化的直接价值在于object-dtype 数组不再退化为元素类型全未知。在 numpy/_core/multiarray.pyi 中可以看到构造 object 数组的各类重载签名已全面使用np.object_[ItemT]def asarray(a: _ArrayLike[np.object_[ItemT]], ...) - np.ndarray[ShapeT, np.dtype[np.object_[ItemT]]]: ... def array(a: _ArrayLike[np.object_[ItemT]], ...) - np.ndarray[ShapeT, np.dtype[np.object_[ItemT]]]: ... def asanyarray(...) - _Array0D[np.object_[ItemT]]: ...例如np.array([a, b])在旧类型桩下会被推断为ndarray[Any, dtype[object_]]元素的str信息丢失泛型化之后asarray系列重载会捕获ItemT str从而得到ndarray[..., dtype[object_[str]]]后续对数组元素调用字符串方法也能被类型检查器正确校验。类似地在 numpy/_core/fromnumeric.pyi 的_ArrayLike[np.object_[ItemT]]参数中元素类型同样沿着调用链被传递和保留。与 dtype 系统的联动numpy/_core/_type_aliases.pyi 中OBJECT: np.dtype[np.object_]仍保持有效缺省参数默认Any不破坏既有代码numpy/dtypes.pyi 中 object 类型别名同样基于_SimpleDType[np.object_]泛型化后np.dtype[np.object_[int]]这类标注可以被合法书写。在 ufunc 签名中的应用元素级类型参与推断泛型化的object_也被大规模应用到 ufunc 的类型桩中使得 object-dtype 数组参与运算时能够利用元素类型做更精确的推断。以 numpy/_core/umath.pyi 中的add等通用函数为例def add( x1: npt.NDArray[np.object_[T1]], x2: npt.NDArray[np.object_[T2]], /, ... ) - npt.NDArray[np.object_[T1 | T2]]: ...即两个元素类型分别为T1、T2的 object 数组相加返回数组的元素类型被推断为T1 | T2联合类型。这与此前 32198.typing.rst 中ufunc 遵循 NumPy 提升规则推断输出 dtype的改进一脉相承——object_泛型化正是让 object-dtype 分支也能从输出Any升级为输出联合类型的关键一环。标量方法与类型守卫方法泛型参数还被用于刻画object_上的标量方法行为见 numpy/init.pyidef __hash__(self: object_[Hashable], /) - int: ... def __abs__T - object_[T]: ... def __call__**P, T - object_[T]: ... property def realT - object_[T]: ... property def imagT - object_[T]: ...这些签名利用self: object_[X]形式的类型守卫type guard约束把标量方法的能力与被包裹对象是否满足某个协议绑定起来只有np.object_[Hashable]才能调用__hash__并返回int包裹了可调用对象Callable[P, T]的np.object_[Callable[P, T]]可以直接被调用参数与返回值类型被完整推断包裹了复数协议对象_HasRealAndImag的object_可通过.real/.imag取出对应类型的分量。同时NDArray[object_[ItemT]]的__iter__见 numpy/init.pyi会返回Iterator[ItemT]使得遍历 object 数组时元素类型不再丢失。类型检查测试与验证仓库的类型测试reveal 测试在 numpy/typing/tests/data/reveal/scalars.pyi 中维护其中关于object_的断言包括O: np.object_ # cannot exists at runtime assert_type(O.real, np.object_) assert_type(O.imag, np.object_) # assert_type(np.object_(), None) # assert_type(np.object_(42), int) # assert_type(np.object_(Developers! * (1 6)), str)这里同时印证了类型桩注释中的说明object_的构造器在运行时直接返回传入对象因此类型为np.object_的实例在运行时并不存在——它纯粹是静态类型层面的抽象。测试中的assert_type断言正是本轮泛型化后由 CI 持续守护的契约确保np.object_、np.object_[Any]等标注在 mypy / pyright 等检查器下行为一致。使用建议与兼容性总结升级你的对象数组标注将NDArray[np.object_]或ndarray[Any, dtype[np.object_]]按需细化为NDArray[np.object_[str]]、ndarray[ShapeT, dtype[np.object_[int]]]等以恢复元素类型信息省略即Anynp.object_与np.object_[Any]完全等价旧代码无需任何修改即可继续通过类型检查运行时零开销np.object_[T]在运行时求值仍为np.object_本身见 scalartypes.c.src 与 test_scalar_methods.py因此可以在任何需要 dtype 的位置放心书写配合泛型 ufunc 签名让 object 数组参与np.add等运算时返回类型可从NDArray[object_[Any]]提升为NDArray[object_[T1 | T2]]建议同步关注 32198.typing.rst 描述的 ufunc 提升规则改进。这一变更与 32198.typing.rst、32357.typing.rst 等 typing 系列改进共同构成了 NumPy 2.x 时期对静态类型检查的持续投入从 ufunc 的按函数逐一分发与提升规则感知到Generator的 shape 推断再到本次object_的泛型化NumPy 的类型体系正在向可精确到元素类型与形状的方向全面演进。对于依赖 NumPy 构建类型安全数据管道的开发者而言np.object_[T]是这一体系中补齐 object-dtype 盲区的关键一环。【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NumPy 2.x 类型注解增强：泛型化 `numpy.object_` 标量类型全解析
NumPy 2.x 类型注解增强泛型化numpy.object_标量类型全解析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpynumpy.object_是 NumPy 中用于承载任意 Python 对象的标量类型其对应的 dtype 在科学计算与元数据传递场景中广泛使用。本文基于 NumPy 仓库的 typing 更新公告32075.typing.rst系统讲解numpy.object_从普通类升级为泛型类的变更其类型参数代表被包裹的 Python 对象缺省时默认为Any。读完本文你将掌握np.object_[T]的正确书写方式、它与NDArray[np.object_[T]]的配合用法以及这一变更如何在静态类型检查中显著提升 object-dtype 数组的类型推断精度。变更速览object_泛型化带来的能力本次变更的核心内容如下源自 32075.typing.rstnumpy.object_标量类型现在是一个泛型类型其类型参数表示被包裹的 Python 对象省略时默认为Any。也就是说在静态类型层面从前的写法import numpy as np from typing import Any x: np.ndarray[Any, np.dtype[np.object_]] # 丢失了元素类型信息现在可以升级为携带元素类型信息的写法x: np.ndarray[Any, np.dtype[np.object_[str]]] # 元素为 str 的 object 数组 y: np.ndarray[Any, np.dtype[np.object_[int]]] # 元素为 int 的 object 数组 z: np.ndarray[Any, np.dtype[np.object_]] # 缺省即 np.object_[Any]元素类型未知省略类型参数时默认为Any因此np.object_与np.object_[Any]在类型检查中等价旧的写法依然完全兼容不会破坏既有类型标注。类型桩中的泛型定义与运行时实现类型桩定义在仓库主类型桩文件 numpy/init.pyi 中object_被定义为一个final泛型类# NOTE: The object_ constructor returns the passed object, so instances with type # object_ cannot exists (at runtime). final class object_(generic[_ItemT_co], Generic[_ItemT_co]): classmethod # object_ is (also) subscriptable at runtime def __class_getitem__T - T: ...几个值得注意的设计细节final装饰object_被标记为最终类不允许被继承这是对运行时行为其构造器直接返回传入对象的类型层面约束协变类型参数_ItemT_co泛型参数使用协变covariant标注表示包裹的对象类型可以向其父类型收缩/放宽这使np.object_[int]可以被安全地视为np.object_[object]等运行时__class_getitem__同样可用类型桩中特别注明object_在运行时也可被下标化subscriptable见下节。运行时__class_getitem__的 C 实现在底层 C 实现 numpy/_core/src/multiarray/scalartypes.c.src 中object_的__class_getitem__被显式注册其注释直接说明了设计意图/* Returns np.object_ itself, so that e.g. np.object_[str] stays dtype-like */ static PyObject * objecttype_class_getitem(PyObject *cls, PyObject *NPY_UNUSED(args)) { return Py_NewRef(cls); }这意味着运行时np.object_[str]求值结果就是np.object_本身——类型参数只对静态类型检查有意义不会在运行时产生新的类对象。这一行为由仓库测试 numpy/_core/tests/test_scalar_methods.py 明确验证if cls in {np.bool, np.datetime64, np.object_}: ... assert np.object_[int] is np.object_因此np.object_[T]既是合法的 dtype 用法np.dtype[np.object_[T]]又不会给运行时带来任何额外开销或行为变化是纯类型层面的增强。泛型化带来的具体收益数组元素类型被保留object_泛型化的直接价值在于object-dtype 数组不再退化为元素类型全未知。在 numpy/_core/multiarray.pyi 中可以看到构造 object 数组的各类重载签名已全面使用np.object_[ItemT]def asarray(a: _ArrayLike[np.object_[ItemT]], ...) - np.ndarray[ShapeT, np.dtype[np.object_[ItemT]]]: ... def array(a: _ArrayLike[np.object_[ItemT]], ...) - np.ndarray[ShapeT, np.dtype[np.object_[ItemT]]]: ... def asanyarray(...) - _Array0D[np.object_[ItemT]]: ...例如np.array([a, b])在旧类型桩下会被推断为ndarray[Any, dtype[object_]]元素的str信息丢失泛型化之后asarray系列重载会捕获ItemT str从而得到ndarray[..., dtype[object_[str]]]后续对数组元素调用字符串方法也能被类型检查器正确校验。类似地在 numpy/_core/fromnumeric.pyi 的_ArrayLike[np.object_[ItemT]]参数中元素类型同样沿着调用链被传递和保留。与 dtype 系统的联动numpy/_core/_type_aliases.pyi 中OBJECT: np.dtype[np.object_]仍保持有效缺省参数默认Any不破坏既有代码numpy/dtypes.pyi 中 object 类型别名同样基于_SimpleDType[np.object_]泛型化后np.dtype[np.object_[int]]这类标注可以被合法书写。在 ufunc 签名中的应用元素级类型参与推断泛型化的object_也被大规模应用到 ufunc 的类型桩中使得 object-dtype 数组参与运算时能够利用元素类型做更精确的推断。以 numpy/_core/umath.pyi 中的add等通用函数为例def add( x1: npt.NDArray[np.object_[T1]], x2: npt.NDArray[np.object_[T2]], /, ... ) - npt.NDArray[np.object_[T1 | T2]]: ...即两个元素类型分别为T1、T2的 object 数组相加返回数组的元素类型被推断为T1 | T2联合类型。这与此前 32198.typing.rst 中ufunc 遵循 NumPy 提升规则推断输出 dtype的改进一脉相承——object_泛型化正是让 object-dtype 分支也能从输出Any升级为输出联合类型的关键一环。标量方法与类型守卫方法泛型参数还被用于刻画object_上的标量方法行为见 numpy/init.pyidef __hash__(self: object_[Hashable], /) - int: ... def __abs__T - object_[T]: ... def __call__**P, T - object_[T]: ... property def realT - object_[T]: ... property def imagT - object_[T]: ...这些签名利用self: object_[X]形式的类型守卫type guard约束把标量方法的能力与被包裹对象是否满足某个协议绑定起来只有np.object_[Hashable]才能调用__hash__并返回int包裹了可调用对象Callable[P, T]的np.object_[Callable[P, T]]可以直接被调用参数与返回值类型被完整推断包裹了复数协议对象_HasRealAndImag的object_可通过.real/.imag取出对应类型的分量。同时NDArray[object_[ItemT]]的__iter__见 numpy/init.pyi会返回Iterator[ItemT]使得遍历 object 数组时元素类型不再丢失。类型检查测试与验证仓库的类型测试reveal 测试在 numpy/typing/tests/data/reveal/scalars.pyi 中维护其中关于object_的断言包括O: np.object_ # cannot exists at runtime assert_type(O.real, np.object_) assert_type(O.imag, np.object_) # assert_type(np.object_(), None) # assert_type(np.object_(42), int) # assert_type(np.object_(Developers! * (1 6)), str)这里同时印证了类型桩注释中的说明object_的构造器在运行时直接返回传入对象因此类型为np.object_的实例在运行时并不存在——它纯粹是静态类型层面的抽象。测试中的assert_type断言正是本轮泛型化后由 CI 持续守护的契约确保np.object_、np.object_[Any]等标注在 mypy / pyright 等检查器下行为一致。使用建议与兼容性总结升级你的对象数组标注将NDArray[np.object_]或ndarray[Any, dtype[np.object_]]按需细化为NDArray[np.object_[str]]、ndarray[ShapeT, dtype[np.object_[int]]]等以恢复元素类型信息省略即Anynp.object_与np.object_[Any]完全等价旧代码无需任何修改即可继续通过类型检查运行时零开销np.object_[T]在运行时求值仍为np.object_本身见 scalartypes.c.src 与 test_scalar_methods.py因此可以在任何需要 dtype 的位置放心书写配合泛型 ufunc 签名让 object 数组参与np.add等运算时返回类型可从NDArray[object_[Any]]提升为NDArray[object_[T1 | T2]]建议同步关注 32198.typing.rst 描述的 ufunc 提升规则改进。这一变更与 32198.typing.rst、32357.typing.rst 等 typing 系列改进共同构成了 NumPy 2.x 时期对静态类型检查的持续投入从 ufunc 的按函数逐一分发与提升规则感知到Generator的 shape 推断再到本次object_的泛型化NumPy 的类型体系正在向可精确到元素类型与形状的方向全面演进。对于依赖 NumPy 构建类型安全数据管道的开发者而言np.object_[T]是这一体系中补齐 object-dtype 盲区的关键一环。【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址: https://gitcode.com/gh_mirrors/nu/numpy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考