basedpyright

Basedpyright是pyright的一个分支，它改进了类型检查、增强了vscode支持，并将pylance的功能集成到了语言服务器中。

📚 文档 | 🛝 在线试用

为什么要创建这个分支？

创建这个分支主要有两个原因：

1. pyright缺少一些只在微软闭源的vscode扩展pylance中提供的功能
2. pyright的维护者无故关闭有效问题并对用户发火

以下是我们在basedpyright中添加的新功能的（大致）完整列表：

能够固定vscode使用的版本

在pyright中，如果vscode扩展更新了，你可能会在项目中看到CI中没有出现的错误，反之亦然。参见这个问题。

basedpyright通过在扩展中添加importStrategy选项来解决这个问题，默认情况下会在你的项目中查找basedpyright pypi包。

发布为pypi包 - 无需nodejs

pyright只发布为npm包，这需要你安装nodejs。pypi上的版本只是一个非官方的包装器，它在你第一次调用cli时安装node和npm包，这个过程相当不稳定。

Python开发者不应该被要求安装nodejs来对他们的Python代码进行类型检查。它应该像mypy、ruff和几乎所有其他Python工具一样，只是一个普通的pypi包。这就是为什么basedpyright正式发布在pypi上，它捆绑了npm包。

新的诊断规则

reportUnreachable - 报告原本会被完全忽略的代码的错误

pyright经常错误地将代码标记为不可达。在大多数情况下，不可达代码是一个错误，因此应该报告为错误，但pyright没有选项来报告不可达代码。事实上，不可达代码甚至根本不会被类型检查：

if sys.platform == "win32":
  1 + "" # 没有错误

默认情况下，如果pyright本身运行在非Windows操作系统上，它会将上面代码中的主体视为不可达。这当然是不好的，因为如果你写了这样的检查，你可能是想让你的代码在多个平台上执行。

更糟糕的是，不可达代码甚至不会被类型检查，所以上面明显无效的1 + ""将完全被类型检查器忽略。

basedpyright通过reportUnreachable选项解决了这个问题，该选项会对这种未检查的代码报告错误。在这个例子中，如果你希望代码是可达的，你可以更新你的pyright配置，使用pythonPlatform选项指定更多平台。

reportAny - 完全禁止Any类型

pyright有一些选项可以禁止"Unknown"类型，比如reportUnknownVariableType、reportUnknownParameterType等。但是"Unknown"不是一个真正的类型，而是pyright用来表示来自未类型化代码或未跟踪导入的Any的一种区分。如果你想禁止所有类型的Any，pyright没有办法做到：

def foo(bar, baz: Any) -> Any:
    print(bar) # 错误：未知类型
    print(baz) # 没有错误

basedpyright引入了reportAny选项，它会对任何被类型化为Any的使用报告错误。

reportIgnoreCommentWithoutRule - 强制所有忽略注释都指定一个错误代码

在你的pyright: ignore注释中指定一个错误代码是一个好习惯：

# pyright: ignore[reportUnreachable]

这样，如果错误发生变化或者将来在同一行出现新的错误，你会得到一个新的错误，因为注释没有考虑到其他错误。

注意，type: ignore注释（enableTypeIgnoreComments）是不安全的，默认情况下是禁用的（参见#330和#55）。我们建议使用pyright: ignore注释代替。

reportPrivateLocalImportUsage - 防止本地代码中的隐式重新导出

pyright的reportPrivateImportUsage规则只检查py.typed包内第三方模块的私有导入。但是没有理由你自己的代码不应该受到相同的限制。要显式重新导出某些内容，给它一个冗余的别名如PEP484的"存根文件"部分所述（尽管它只提到了存根文件，但其他类型检查器如mypy也将这种行为扩展到了源文件）：

# foo.py

from .some_module import a  # 私有导入
from .some_module import b as b  # 显式重新导出

# bar.py
# reportPrivateLocalImportUsage 错误，因为 `a` 没有被 `foo` 模块显式重新导出:
from foo import a

# 没有错误，因为 `b` 被显式重新导出:
from foo import b

reportImplicitRelativeImport - 报告无效的"相对"导入错误

pyright 允许这样的无效导入:

# ./module_name/foo.py:

# ./module_name/bar.py:
import foo # 错误! 应该是 `import module_name.foo` 或 `from module_name import foo`

乍看之下这似乎是正确的，并且在直接作为脚本运行 bar.py 时也能正常工作，但当它作为模块被导入时，就会崩溃:

# ./main.py:
import module_name.bar  # ModuleNotFoundError: No module named 'foo'

新的 reportImplicitRelativeImport 规则禁止这种导入。如果你想进行相对导入，正确的方法是从 .（当前包）导入:

# ./module_name/bar.py:
from . import foo

reportInvalidCast - 防止非重叠的 cast

大多数情况下进行类型转换时，你希望转换为更窄或更宽的类型:

foo: int | None
cast(int, foo) #  更窄的类型
cast(object, foo) #  更宽的类型

但 pyright 不会阻止转换为与原始类型不重叠的类型:

foo: int
cast(str, foo)

在这个例子中，如果 foo 是 int 类型，就不可能同时是 str 类型，因为 int 和 str 类型不重叠。reportInvalidCast 规则将报告这种无效的类型转换。

关于使用 TypedDict 进行类型转换的注意事项

cast 的一个常见用例是将普通 dict 转换为 TypedDict:

foo: dict[str, int | str]
bar = cast(dict[{"foo": int, "bar": str}], foo)

不幸的是，当启用此规则时，这会导致 reportInvalidCast 错误，因为尽管在运行时 TypedDict 是一个 dict，但类型检查器将其视为 Mapping 的一个无关子类型，它没有 clear 方法，如果在 TypedDict 上调用该方法会破坏其类型安全性。

这意味着尽管它们之间的类型转换是一个常见用例，但从技术上讲，TypedDict 和 dict 并不重叠。

reportUnsafeMultipleInheritance - 禁止从多个具有构造函数的不同基类继承

Python 中的多重继承很糟糕:

class Foo:
    def __init__(self):
        super().__init__()
class Bar:
    def __init__(self):
        ...

class Baz(Foo, Bar):
    ...

Baz()

在这个例子中，Baz() 调用 Foo.__init__，而 Foo 中的 super().__init__() 现在调用 Bar.__init__，尽管 Foo 并没有继承 Bar。

这完全没有意义且非常不安全，因为无法静态地知道超类会是什么。

pyright 有 reportMissingSuperCall 规则，出于这个原因，即使你的类没有基类，它也会报错。但这很糟糕，因为无法知道未知的 __init__ 接受什么参数，这意味着即使你添加了对 super().__init__() 的调用，你也不知道它可能需要什么参数。所以启用这个规则时非常烦人，而且几乎没有什么好处，因为它在安全性方面几乎没有什么区别。

reportUnsafeMultipleInheritance 在有多个带有 __init__ 或 __new__ 方法的基类时禁止多重继承，因为无法保证所有这些方法都会以正确的参数被调用（或被调用）。这允许 reportMissingSuperCall 更宽松。也就是说，当启用 reportUnsafeMultipleInheritance 时，只有在类确实有基类的情况下，才会报告缺少 super() 调用。

reportUnusedParameter - 报告未使用的函数参数错误

pyright 会对未使用的函数参数报告未使用的诊断:

def print_value(value: str): # "value" 未被访问
  print("something else")

但就像无法到达的代码一样，这只是将代码变灰而不是实际报告为错误。basedpyright 引入了一个新的 reportUnusedParameter 诊断规则，它支持所有严重性选项（"error"、"warning" 和 "none"）以及 "unused"，后者是 pyright 中的默认行为。

重新实现 pylance 独有功能

basedpyright 重新实现了一些 Microsoft 为 pylance 独占的功能，pylance 是 Microsoft 基于 pyright 语言服务器构建的闭源 VS Code 扩展，具有一些额外的独占功能（更多信息请参见 pylance FAQ）。

以下功能已在 basedpyright 的语言服务器中重新实现，这意味着它们不再是 VS Code 独有的。你可以使用任何支持语言服务器协议的编辑器。有关在你选择的编辑器中安装 pyright 的更多信息，请参阅安装说明。

导入建议代码操作

pyright 仅支持将导入建议作为自动完成建议，而不是快速修复（参见此问题）。

basedpyright 重新实现了 pylance 的导入建议代码操作:

语义高亮

之前	之后

basedpyright 重新实现了 pylance 的语义高亮，并进行了一些额外改进:

• 标记为 Final 的变量具有正确的"只读"颜色
• 支持 Python 3.12 中的新 type 关键字
• Final 变量被着色为只读

语义高亮提供程序的初始实现改编自 pyright-inlay-hints 项目。

内联提示

basedpyright 对从 pyright-inlay-hints 改编的原始实现进行了多项改进和错误修复。

编译的内置模块的文档字符串

许多内置模块是用 C 语言编写的，这意味着 pyright 语言服务器无法静态检查和显示它们的文档字符串给用户。不幸的是，这些文档字符串在这些模块的 .pyi 存根中也不可用，因为typeshed 维护者认为这会带来太多维护负担。

pylance 通过在用户机器上运行"文档字符串抓取"脚本来解决这个问题，该脚本导入编译的内置模块，在运行时抓取所有文档字符串，然后保存它们，以便语言服务器可以读取。然而，这并不理想，原因如下:

• 仅会生成用户当前操作系统和Python版本可用的模块和函数的文档字符串。因此,如果您正在进行跨平台项目开发,或者编写需要在多个Python版本上运行的代码,您将无法看到当前Python安装中不可用的编译内置模块的文档字符串。
• 判断内置对象是否为编译对象是在模块级别进行的,这意味着像 re 和 os 这样有Python源文件但包含重新导出的编译函数的模块,会被视为完全用Python编写。这导致Pylance中仍然缺少许多这些模块的文档字符串。
• 这可能会更慢,因为这些文档字符串需要在用户启动VSCode时,或用户将鼠标悬停在内置类/函数上时进行抓取(声明:我实际上不知道它何时运行,因为Pylance是闭源的)。

basedpyright通过使用docify来抓取所有当前支持的Python版本和所有平台(macOS、Windows和Linux)的所有编译内置函数/类的文档字符串,并将它们包含在basedpyright包附带的默认typeshed存根中,从而解决了所有这些问题。

示例

以下是basedpyright在Windows上运行时的内置文档字符串演示,与Pylance相比:

basedpyright

pylance

生成带有文档字符串的自定义存根

basedpyright使用docify为其存根添加文档字符串。如果您有第三方编译模块,并希望basedpyright能看到其文档字符串,您可以执行相同操作:

python -m docify path/to/stubs/for/package --in-place

或者,如果您使用的是不同版本的typeshed,可以使用 --if-needed 参数来复制basedpyright的typeshed版本是如何为您当前的平台和Python版本生成的:

python -m docify path/to/typeshed/stdlib --if-needed --in-place

重命名包和模块

在重命名包或模块时,basedpyright会更新所有使用到新名称的地方,就像Pylance一样:

对无效配置报错

在pyright中,如果您有任何无效的配置,它可能会也可能不会在控制台打印警告,然后继续进行类型检查,只要没有类型错误,退出代码就会是0:

[tool.pyright]
mode = "strict"  # 错误!您要找的设置叫做 `typeCheckingMode`

在这个例子中,错误很容易被忽视,因为您认为您处于严格模式,但实际上pyright只是忽略了该设置,并默默地继续在"basic"模式下进行类型检查。

为了解决这个问题,basedpyright在遇到任何无效配置时都会以代码3退出。

修复 reportRedeclaration 和 reportDuplicateImport 规则

如果重新声明具有相同类型,pyright不会报告重新声明:

foo: int = 1
foo: int = 2  # 没有错误

它也不关心您是否在多个不同的 import 语句中或别名中有重复的导入:

from foo import bar
from bar import bar  # 没有错误
from baz import foo as baz, bar as baz  # 没有错误

basedpyright通过在重新声明或导入与现有导入同名的情况下始终报告错误来解决这两个问题。

更好的默认设置

我们认为类型检查器和代码检查工具应该默认尽可能严格,让用户了解所有可用的规则,以便他们能更容易地做出关于哪些规则不想在其项目中启用的明智决定。这就是为什么在basedpyright中更改了以下默认设置

typeCheckingMode

原来是 basic,现在默认为 all。将来我们打算添加基线,以便在现有代码库中轻松采用更严格的规则。

pythonPlatform

原来假设pyright运行的操作系统是您的代码将运行的唯一操作系统,这种情况很少见。在basedpyright中, pythonPlatform 默认为 All,这假设您的代码可以在任何操作系统上运行。

内联 TypedDict 支持

pyright曾经支持内联定义 TypedDict,像这样:

foo: dict[{"foo": int, "bar": str}] = {"foo": "a", "bar": 1}

这是一个实验性功能,由于从未被纳入PEP而被移除。但这个功能非常方便,我们认为没有理由不继续支持它,所以我们在basedpyright中将其加回。

目前可以通过将 enableExperimentalFeatures 设置为 false 来禁用此功能。未来一旦我们添加更多"基于"功能,将会有一个单独的 enableNonStandardFeatures 选项。

改进与CI平台的集成

常规pyright有针对GitHub Actions和GitLab的第三方集成,但它们难以安装/设置。这些集成已内置于basedpyright中,使它们更易于使用。

GitHub Actions

basedpyright自动检测它是否在GitHub Action中运行,并修改其输出以使用GitHub工作流命令。这意味着错误将自动显示在您的拉取请求中受影响的代码行上:

这是对常规pyright的改进,后者需要您使用第三方操作,该操作需要样板代码才能工作。basedpyright只需自动执行,无需您做任何特殊操作:

# .github/workflows/your_workflow.yaml

jobs:
  check:
    steps:
      - run: ...  # 检出仓库,安装依赖等
      - run: basedpyright  # 不需要额外参数。它会自动检测是否在GitHub Action中运行

GitLab代码质量报告

--gitlabcodequality 参数将输出一个GitLab代码质量报告,该报告会显示在合并请求中:

要在GitLab CI中启用此功能,只需指定一个文件路径来输出报告,并在 .gitlab-ci.yml 文件的 artifacts.reports.codequality 部分中:

basedpyright:
  script: basedpyright --gitlabcodequality report.json
  artifacts:
    reports:
      codequality: report.json

改进的翻译

pyright中的翻译来自微软的本地化团队,他们不是程序员。这不仅导致翻译质量差,而且微软也不接受修复翻译的贡献(更多信息在这里)。 我们接受在basedpyright中进行翻译修正。有关如何贡献的信息，请参阅本地化指南。

basedmypy功能对等

basedmypy是mypy的一个分支，具有类似的目标：修复mypy中一些维护者似乎不优先考虑的严重问题。它还添加了许多新功能，这些功能可能尚未标准化，但在使用Python并不完美的类型系统时，可以极大地改善开发人员的体验。

我们的目标是将basedmypy的大部分功能移植到basedpyright，但如上所述，我们的首要任务是先修复pyright中的关键问题。

请注意，我们添加的任何非标准功能都将是可选的，因为我们打算支持那些无法控制其库使用哪种类型检查器的库开发者。

PyPI包

basedpyright与pyright的不同之处在于，它将命令行工具作为PyPI包发布，而不是npm包。这对Python开发者来说更加方便，因为无需安装任何额外的工具。

更多信息，请参阅安装说明。

VSCode扩展

安装

从VSCode扩展市场或Open VSX注册表安装扩展。

使用

basedpyright VSCode扩展将自动在你的Python环境中查找PyPI包。

如果你将basedpyright作为项目的开发依赖添加，我们建议将其添加到工作空间的推荐扩展列表中，以提示其他在你的仓库上工作的人安装它：

// .vscode/extensions.json

{
  "recommendations": ["detachhead.basedpyright"]
}

在.vscode/settings.json中，删除任何以python.analysis开头的设置，因为basedpyright不使用它们。你应该使用pyproject.toml中的tool.basedpyright（或tool.pyright）部分来设置这些选项（见下文）。

你还应该禁用Python扩展内置的语言服务器支持，因为它与basedpyright的语言服务器冲突。basedpyright扩展会检测到这个问题并建议自动修复。

将basedpyright与Pylance一起使用（不推荐）

除非你依赖于basedpyright尚未重新实现的Pylance独有功能，否则建议禁用/卸载Pylance扩展。

如果你确实想继续使用Pylance，basedpyright中的所有选项和命令都已重命名，以避免与Pylance扩展发生任何冲突，并且已删除阻止两个扩展同时启用的限制。为获得最佳体验，你应该在.vscode/settings.json文件中更改以下设置：

• 通过将"python.analysis.typeCheckingMode"设置为"off"来禁用Pylance的类型检查。这将防止Pylance显示其捆绑的pyright版本的重复错误，而这些错误已经由basedpyright扩展显示。
• 通过将"basedpyright.disableLanguageServices"设置为true来禁用basedpyright的LSP功能。这将防止重复的悬停文本和其他可能与Pylance的LSP产生的潜在问题。请记住，这可能会导致一些不一致的行为，因为Pylance使用自己版本的pyright LSP。

{
    "python.analysis.typeCheckingMode": "off",
    "basedpyright.disableLanguageServices": true
}

（basedpyright扩展会检测到这个问题并建议自动修复）

在线试用

你可以使用basedpyright在线试用在浏览器中尝试basedpyright。

预提交钩子

也支持与pre-commit集成。

# .pre-commit-config.yaml

repos:
  - repo: https://github.com/DetachHead/basedpyright-pre-commit-mirror
    rev: v1.13.0  # 或当时的最新版本
    hooks:
    - id: basedpyright

更多信息，请参阅此处的文档。

推荐设置

建议在你的项目中同时使用basedpyright CLI和VSCode扩展。VSCode扩展用于本地开发，而CLI用于你的CI。

以下是我建议在采用basedpyright时对你的项目进行的更改

pyproject.toml

我们建议使用pdm与pyprojectx（点击"inside project"标签）来管理你的依赖。

[tool.pyprojectx]
main = ["pdm==2.12.4"]  # 将pdm安装到你的项目中，而不是全局安装

[tool.pdm.dev-dependencies]  # 或poetry的等效设置
dev = [
    "basedpyright", # 你可以在此处固定版本，或者仅依赖锁定文件
]

[tool.basedpyright]
# 即使在严格模式下，许多设置也未启用，这就是为什么basedpyright包含一个"all"选项
# 然后你可以决定要禁用哪些规则
typeCheckingMode = "all"

固定你的依赖版本很重要，因为它允许你的CI构建可重现（即在同一提交上的两次运行将始终产生相同的结果）。basedpyright确保VSCode使用的pyright版本始终与这个固定版本匹配。