如何在.pyi存根文件中为内部嵌套函数正确添加类型提示

首先明确核心规则：按照PEP 484对存根文件的规范定义，.pyi存根仅用于描述模块对外暴露的公开接口签名，不支持声明方法/函数内部的嵌套函数、局部变量等实现细节的类型。你之前尝试在存根的copy方法体内写walk_properties签名的写法本身不符合存根语法约定，PyCharm等IDE和mypy等类型检查工具都不会识别这类内部声明，自然无法生效。

存根文件的解析逻辑是：类型工具只会读取存根里类、公开方法、顶层函数的参数、返回值签名，不会深入解析方法体内部的代码结构，所以你就算在存根的方法里写了嵌套函数的定义，工具也不会把它和源码里实际的嵌套函数做关联匹配。

可行实现方案 #

• 最优方案（零结构改动、兼容所有类型工具）：仅在源码中为嵌套函数添加必要的类型标注，其余公开接口的类型全部保留在.pyi存根中。
  这种方式几乎不会影响源码整洁度：你不需要给方法内的value_copies、references等局部变量加任何标注，只需要给内部的walk_properties补一行参数和返回值声明即可，原有业务逻辑完全不受影响：

  class TemplateBase:
      def copy(self, _parent=None):
          def walk_properties(template_based: TemplateBase) -> None:
              for prop_holder in template_based.properties.values():
                  if isinstance(prop_holder.prop, TemplateBase):
                      walk_properties(prop_holder.prop)
                  elif isinstance(prop_value, PrimitiveBase):
                      value_copies[prop_value] = prop_value.copy()
                  else:
                      references.append(prop_value)
  
          value_copies = {}
          references = []
          walk_properties(self)
  

  这种写法下，你依然可以把TemplateBase类、copy方法等所有对外暴露接口的类型统一维护在.pyi文件里，嵌套函数的局部标注不会和存根声明冲突，所有类型工具都能正确识别。
• 备选方案（适合完全不想在源码写任何标注的场景）：将内部嵌套的walk_properties抽为类的私有方法（比如命名为_walk_properties），之后就可以在.pyi存根里为这个私有方法添加类型声明。但这种方案需要改动原有代码结构，非必要不推荐。

注意：不要为了强行把所有类型都塞到存根里去改动合理的代码结构，存根本来就是用来描述公开接口的，实现内部的局部类型标注直接写在源码里才是符合Python类型生态惯例的做法。

内容的提问来源于stack exchange，提问作者Simon Van den Bossche