如何为NumPy结构化数组正确使用typeguard类型检查？

你的代码存在两个核心问题：

1. Pylance提示“Variable not allowed in type expression”，因为mytype3是np.dtype实例，不是Python类型系统认可的类型注解——类型注解需要的是类型（如np.ndarray），而非描述数组类型的dtype对象。
2. typeguard未触发预期错误，因为它默认只校验对象是否为某个类型的实例：你传入的是np.ndarray实例，而函数注解写的是mytype3（dtype对象），两者不属于同一范畴，typeguard无法识别这种校验逻辑。

解决方案一：自定义类型守卫（Type Guard） #

借助typeguard的register_type_guard和typing.Annotated，实现针对特定dtype的数组校验：

import numpy as np
from typeguard import typechecked, register_type_guard
from typing import Annotated

mytype2 = np.dtype([("type", int), ("pos", float, 2)])
mytype3 = np.dtype([("type", int), ("pos", float, 3)])

# 定义校验逻辑：检查数组dtype是否与目标匹配
def check_ndarray_dtype(arr: np.ndarray, expected_dtype: np.dtype) -> bool:
    return np.array_equal(arr.dtype, expected_dtype)

# 为np.ndarray注册类型守卫
@register_type_guard(np.ndarray)
def ndarray_type_guard(arr: np.ndarray, expected_dtype: np.dtype) -> bool:
    return check_ndarray_dtype(arr, expected_dtype)

@typechecked
def process(data: Annotated[np.ndarray, mytype3]) -> None:
    print(data)

# 测试：传入mytype2数组会触发TypeError
data = np.array([(1, [2, 3])], dtype=mytype2)
process(data)

解决方案二：函数内部手动校验 #

如果场景简单，直接在函数开头添加dtype校验逻辑，更直观：

import numpy as np
from typeguard import typechecked

mytype2 = np.dtype([("type", int), ("pos", float, 2)])
mytype3 = np.dtype([("type", int), ("pos", float, 3)])

@typechecked
def process(data: np.ndarray) -> None:
    if not np.array_equal(data.dtype, mytype3):
        raise TypeError(f"预期dtype为{mytype3}，实际得到{data.dtype}")
    print(data)

# 测试：触发预期的TypeError
data = np.array([(1, [2, 3])], dtype=mytype2)
process(data)

两种方案都能解决你的问题：方案一适合多函数复用校验逻辑的场景，方案二更适合简单场景快速实现。

内容的提问来源于stack exchange，提问作者Abel Gutiérrez