如何配置pyright识别已知变量__salt__不报告未定义错误

在VSCode中编写自定义SaltStack模块、状态文件时，使用pyright进行代码静态检查会频繁抛出"__salt__" is not defined错误。逐行添加# pyright: ignore[reportUndefinedVariable]注释抑制报错的操作繁琐，可通过项目级配置统一声明__salt__为已知全局变量，从根源关闭该类误报，具体配置方法如下：

方式1：通过pyright配置文件声明全局变量（推荐） #

该方式配置最简单，仅需声明变量名即可消除报错：

• 在项目根目录创建pyright配置文件pyrightconfig.json
• 在配置项中声明所有Salt运行时注入的全局变量，示例配置如下：

{
  "reportUndefinedVariable": "error",
  "globals": [
    "__salt__",
    "__grains__",
    "__pillar__",
    "__opts__",
    "__env__",
    "__runner__",
    "__context__",
    "__ret__",
    "__states__",
    "__utils__"
  ]
}

• 保存配置后，通过VSCode命令面板执行Pyright: Restart Server重启pyright服务，配置即可生效。

配置中除__salt__外的其余双下划线变量，均为Salt执行模块、状态逻辑时自动注入的内置全局对象，一并加入声明可避免后续出现同类未定义报错。

方式2：通过类型存根文件声明全局变量 #

如果需要同时获得全局变量的类型提示，可使用类型存根文件的方式配置：

• 在项目根目录创建后缀为.pyi的类型存根文件，例如命名为salt_globals.pyi
• 在文件中声明所有Salt全局变量及对应类型，示例内容如下：

from typing import Any, Dict

__salt__: Dict[str, Any]
__grains__: Dict[str, Any]
__pillar__: Dict[str, Any]
__opts__: Dict[str, Any]
__env__: str
__runner__: Any
__context__: Dict[str, Any]
__ret__: Dict[str, Any]
__states__: Dict[str, Any]
__utils__: Dict[str, Any]

pyright会自动扫描项目下的.pyi存根文件，识别到上述全局变量声明后，既不会再抛出未定义错误，编写代码时还能提供基础的类型补全提示。

• 不要在业务代码中手动初始化这些双下划线变量，这类变量是Salt运行时自动注入的上下文对象，手动赋值会覆盖运行时注入值，导致业务逻辑异常。
• 如果使用VSCode多根工作区模式，需要将pyrightconfig.json放置在对应工作区的根目录，或在工作区配置中明确指定pyright配置文件的加载路径。
• 若项目中使用了Salt自定义扩展的全局变量，可按照相同规则将变量名加入全局声明列表即可。

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