Python中如何检查NewType值类型且不破坏Pyright类型检查

两个核心设计特性导致了你遇到的问题：

• NewType 是纯静态类型检查阶段的标记工具，运行时不会生成真实的新类型：你定义的BoardId = NewType("BoardId", str)在运行时就是个返回入参的普通函数，根本不是类/类型对象，自然不能传给isinstance当第二个参数，传了就会抛你看到的TypeError。
• 直接写isinstance(board_id, str)做分支判断时，pyright这类类型检查器会自动把通过判断的board_id收窄为普通str类型。而在类型系统的定义里，BoardId是str的子类型，普通str不能直接赋值给BoardId位置，就触发了类型不兼容的报错。

最干净的实现方式是自定义类型守卫，既不破坏运行时逻辑，也不会干扰类型检查流程：

1. 导入依赖：Python 3.13+可直接从typing导入TypeIs，低版本从typing_extensions导入兼容版本
2. 编写专门判断单个BoardId的守卫函数，运行时判断逻辑仍然是检查是否为字符串，但通过返回类型标注告诉类型检查器：判断通过时值为BoardId类型，而非普通str
3. 替换原有代码中的isinstance判断即可

完整代码示例：

from typing import NewType, Iterable, List, Union
# Python <3.13 用下面这行导入
from typing_extensions import TypeIs
# Python 3.13+ 替换为 from typing import TypeIs

BoardId = NewType("BoardId", str)

def is_board_id(value: object) -> TypeIs[BoardId]:
    # 运行时BoardId本质就是str，直接判断字符串类型即可
    return isinstance(value, str)

class YourService:
    async def get_stickies(
        self, board_id: Union[BoardId, Iterable[BoardId]]
    ) -> List[Sticky]:
        board_ids: Iterable[BoardId] = (
            (board_id,) if is_board_id(board_id) else board_id
        )
        # 后续业务逻辑正常编写即可
        ...

这种实现没有任何强制类型转换，不会绕过类型检查：如果后续有代码误传普通str给需要BoardId的位置，类型检查器仍然会正常报错，运行时也不会有额外性能损耗。

注意：不要为了快速过检查直接在报错行加# type: ignore，这种写法会完全绕过类型校验，后续入参逻辑变更时检查器无法捕获错误，不推荐使用。

如果不想额外引入守卫函数，也可以直接在分支内用NewType本身做标记，BoardId(x)运行时会直接返回原对象、没有任何转换开销，只是给类型检查器传递类型收窄信号：

from typing import NewType, Iterable, List, Union

BoardId = NewType("BoardId", str)

class YourService:
    async def get_stickies(
        self, board_id: Union[BoardId, Iterable[BoardId]]
    ) -> List[Sticky]:
        if isinstance(board_id, str):
            board_ids = (BoardId(board_id),)
        else:
            board_ids = board_id
        # 后续业务逻辑
        ...

内容的提问来源于stack exchange，提问作者Lajos