basedpyright-type-checking

Basedpyright 类型检查

Basedpyright 是 Pyright 的一个分支，增加了额外功能并采用更严格的默认设置，旨在实现最高的类型安全性和性能。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他工具……
为 Python 设置类型检查	格式化代码（使用 ruff format）
配置严格的类型验证	检查代码风格问题（使用 ruff check）
比较类型检查器（basedpyright 与 mypy）	检测未使用的代码（使用 vulture/deadcode）
设置 LSP，以便编辑器提供类型感知支持	运行测试（使用 pytest）

安装

通过 uv 安装（推荐）

# Install globally
uv tool install basedpyright

# Install as dev dependency
uv add --dev basedpyright

# Run with uv
uv run basedpyright

通过 pipx 安装

pipx install basedpyright

基本用法

# Check entire project
basedpyright

# Check specific files/directories
basedpyright src/ tests/

# Watch mode for development
basedpyright --watch

# Output JSON for tooling integration
basedpyright --outputjson

# Verbose diagnostics
basedpyright --verbose

配置

最简严格配置（pyproject.toml）

[tool.basedpyright]
typeCheckingMode = "strict"
pythonVersion = "3.12"
include = ["src"]
exclude = ["**/__pycache__", "**/.venv"]

# Basedpyright-specific strict rules
reportUnusedCallResult = "error"
reportImplicitStringConcatenation = "error"
reportMissingSuperCall = "error"
reportUninitializedInstanceVariable = "error"

类型检查模式

模式	描述	使用场景
off	不进行类型检查	遗留代码，开始迁移
basic	基本类型检查	逐步采用类型标注
standard	标准严格程度	大多数项目（Pyright 默认值）
strict	严格类型检查	类型安全的代码库
all	最高严格程度	高可信度系统

渐进式类型检查

# Start with basic mode
[tool.basedpyright]
typeCheckingMode = "basic"
include = ["src/new_module"]  # Type check new code only

# Gradually expand
include = ["src/new_module", "src/api"]

# Eventually enable strict mode
typeCheckingMode = "strict"
include = ["src"]

选择类型检查器

因素	Basedpyright	Pyright	mypy
速度	最快	最快	较慢
严格程度	默认设置最严格	可配置	可配置
LSP 支持	内置	内置	通过 dmypy
插件系统	有限	有限	丰富

如果希望借助更严格的默认设置和最快速度实现最高类型安全性，请选择 Basedpyright。 如果需要 Microsoft 官方支持以及兼容 VS Code Pylance，请选择 Pyright。 如果需要丰富的插件生态系统（django-stubs、pydantic-mypy），请选择 mypy。

行内错误抑制

# Inline type ignore
result = unsafe_operation()  # type: ignore[reportUnknownVariableType]

# Function-level ignore
def legacy_function():  # basedpyright: ignore
    pass

Agent 优化

场景	命令
快速检查	basedpyright
JSON 输出	basedpyright --outputjson
监视模式	basedpyright --watch
CI 检查	uv run basedpyright
详细输出	basedpyright --verbose

快速参考

标志	描述
--watch	开发用监视模式
--outputjson	为工具提供 JSON 输出
--verbose	详细诊断信息
--pythonversion X.Y	覆盖 Python 版本
--level <mode>	覆盖类型检查模式

有关详细配置选项、LSP 集成、迁移指南、CI 设置和最佳实践，请参阅 REFERENCE.md。