Pylance无法识别存根文件？如何解决交叉引用类型报错

项目结构 #

mypackage/
├─ subpackage/
│  ├─ __init__.py
│  ├─ module.py
│  ├─ module.pyi
├─ __init__.py

存根文件module.pyi内容 #

class Apple:
    tree: Tree

class Tree:
    apples: Apple

问题场景 #

module.py内容如下时，Pylance和pyflakes会提示名称'Tree'未定义：

class Apple:
    def __init__(self, tree: Tree):
        pass

class Tree:
    def __init__(self, apples: Apple):
        pass

解决方案 #

存根文件（.pyi）仅用于给类型检查器补充类型信息，不会让.py文件直接引用其中的类定义。解决这个报错有两种实用方式：

• 使用Python的前向引用特性，配合from __future__ import annotations（Python 3.7及以上版本支持）。此方式会将类型注解视为字符串，延迟解析，避免定义顺序导致的未定义报错：

  from __future__ import annotations
  
  class Apple:
      def __init__(self, tree: Tree):
          pass
  
  class Tree:
      def __init__(self, apples: Apple):
          pass
  

• 直接使用字符串形式的类型注解，无需导入额外模块，效果和上面的方式一致：

  class Apple:
      def __init__(self, tree: 'Tree'):
          pass
  
  class Tree:
      def __init__(self, apples: 'Apple'):
          pass
  

另外，当前存根文件的位置是合规的（与.py文件同目录、同名），不需要移动位置——它的作用是给类型检查器提供补充类型信息，而非解决.py文件本身的代码定义顺序问题。

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