ty-type-checking

ty 类型检查

使用 Astral（uv 和 ruff 的创建者）推出的极速 Python 类型检查器 ty 的专业知识。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 basedpyright……	在以下情况下改用 mypy……
想要最快的类型检查速度（快 10-100 倍）	需要开箱即用的最严格默认配置	需要丰富的插件生态系统
使用 Astral 工具链（uv、ruff）	想要 Microsoft 支持的替代方案	有旧版 mypy 配置
需要出色的诊断信息	需要兼容 Pylance	需要 mypy 专用插件
想要增量／监视模式	团队更偏好 Pyright 约定	需要 Django／Pydantic mypy 插件
正在设置新的 Python 项目	已在使用 basedpyright	已有 mypy 经验

核心优势

ty 的优势

• 极速（比 mypy 和 Pyright 快 10-100 倍）
• 使用 Rust 编写，性能出色
• 一流的诊断信息，灵感来自 Rust 编译器
• 针对 IDE 工作流优化的增量分析
• 内置 LSP，支持编辑器集成
• 一流的交叉类型支持
• 高级类型收窄和可达性分析
• 属于 Astral 生态系统（uv、ruff）

安装

通过 uv（推荐）

# Install globally as tool
uv tool install ty@latest

# Run without installing
uvx ty check

# Install as dev dependency
uv add --dev ty

通过 pip

pip install ty

VS Code 扩展

从 VS Code 插件市场安装 astral-sh.ty 扩展。

基本用法

类型检查

# Check current directory
ty check

# Check specific files or directories
ty check src/
ty check src/ tests/
ty check path/to/file.py

# Verbose output
ty check --verbose

# Hide progress indicators
ty check --hide-progress

输出控制

# Default output with diagnostics
ty check

# Hide progress spinners (useful for CI)
ty check --hide-progress

# Verbose mode for debugging
ty check --verbose

配置

pyproject.toml

[tool.ty]
# Python version targeting
python-version = "3.12"

# Files to exclude
exclude = [
    "**/__pycache__",
    "**/.venv",
    "**/node_modules",
    "tests/fixtures/**",
]

[tool.ty.rules]
# Configure rule severity: "error", "warn", or "ignore"
index-out-of-bounds = "error"
possibly-unbound = "warn"
unknown-type = "ignore"

ty.toml（独立配置）

# ty.toml takes precedence over pyproject.toml
python-version = "3.12"

exclude = [
    "**/__pycache__",
    "**/.venv",
]

[rules]
index-out-of-bounds = "error"
possibly-unbound = "warn"

配置优先级

1. 命令行参数（最高优先级）
2. 当前目录中的 ty.toml
3. pyproject.toml 的 [tool.ty] 部分
4. 用户配置：~/.config/ty/ty.toml（Linux）或 %APPDATA%\ty\ty.toml（Windows）
5. ty 默认配置（最低优先级）

CLI 选项

核心选项

标志	说明
--python <VERSION>	要使用的 Python 环境／版本
--project <PATH>	在指定项目目录中运行
--config <PATH>	ty.toml 配置文件的路径
--verbose	启用详细输出
--hide-progress	隐藏进度旋转图标／进度条

规则配置

标志	说明
--error <RULE>	将规则设为错误级别
--warn <RULE>	将规则设为警告级别
--ignore <RULE>	完全忽略规则

文件选择

标志	说明
--exclude <PATTERN>	要排除文件的 Glob 模式
--respect-ignore-files	遵循 .gitignore（默认）
--no-respect-ignore-files	忽略 .gitignore 文件

编辑器集成

VS Code

1. 安装扩展：astral-sh.ty
2. ty 提供 LSP，支持：
   • 实时类型检查
   • 跳转到定义
   • 带类型提示的自动补全
   • 自动导入建议
   • 重命名符号
   • 内嵌提示
   • 语义高亮

Neovim

-- Using nvim-lspconfig
require("lspconfig").ty.setup({
  settings = {
    ty = {
      -- Configuration options
    }
  }
})

PyCharm

ty 提供 PyCharm 插件，用于 IDE 集成。

CI 集成

GitHub Actions

name: Type Check

on: [push, pull_request]

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v2
        with:
          enable-cache: true

      - name: Run ty
        run: uvx ty check --hide-progress

Pre-commit 钩子

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ty
    rev: v0.0.10
    hooks:
      - id: ty

GitLab CI

ty-check:
  stage: test
  image: python:3.12
  before_script:
    - pip install ty
  script:
    - ty check --hide-progress

常见模式

快速类型检查

# Fast check of current project
ty check

# Check specific module
ty check src/api/

# Check with custom Python version
ty check --python 3.11

配置规则严重级别

# Make specific rules errors
ty check --error index-out-of-bounds --error possibly-unbound

# Ignore noisy rules
ty check --ignore unknown-type

# Mix severities
ty check --error division-by-zero --warn possibly-unbound --ignore unknown-type

排除文件

# Exclude test fixtures
ty check --exclude "tests/fixtures/**"

# Exclude multiple patterns
ty check --exclude "**/*_test.py" --exclude "**/conftest.py"

# Don't respect .gitignore
ty check --no-respect-ignore-files

与其他类型检查器的比较

性能

类型检查器	相对速度	备注
ty	1 倍（基准）	最快，基于 Rust
Pyright	慢 10-60 倍	性能良好
mypy	慢 10-100 倍	速度较慢，但成熟

在编辑器中（编辑文件后）：

• ty：约 5ms 重新计算诊断信息
• Pyright：约 400ms
• mypy：数秒

功能对比

功能	ty	basedpyright	mypy
速度	最快	快	中等
LSP	内置	内置	dmypy
诊断	优秀	良好	基础
插件系统	有限	有限	丰富
交叉类型	一等支持	部分支持	有限
生态系统	Astral（uv、ruff）	Microsoft	独立

迁移

从 mypy 迁移

# mypy.ini / [tool.mypy]
[mypy]
python_version = 3.12
strict = true
warn_unused_ignores = true

# Equivalent ty configuration
[tool.ty]
python-version = "3.12"

[tool.ty.rules]
# Configure equivalent strictness via rules

从 Pyright/basedpyright 迁移

# [tool.pyright] or [tool.basedpyright]
[tool.basedpyright]
pythonVersion = "3.12"
typeCheckingMode = "strict"

# Equivalent ty configuration
[tool.ty]
python-version = "3.12"

[tool.ty.rules]
# Configure strictness via rules

最佳实践

1. 与 Astral 工具链搭配使用

# Combine with uv and ruff for complete workflow
uv init my-project && cd my-project
uv add --dev ty ruff
uv run ty check
uv run ruff check --fix

2. 配置项目级设置

# pyproject.toml - recommended setup
[tool.ty]
python-version = "3.12"
exclude = [
    "**/__pycache__",
    "**/.venv",
    "**/build",
    "**/dist",
]

[tool.ty.rules]
# Start with defaults, adjust as needed

3. 在 CI 中隐藏进度

# Always use --hide-progress in CI for cleaner logs
ty check --hide-progress

4. 渐进式采用

# Start by checking new code only
ty check src/new_module/

# Gradually expand coverage
ty check src/

Agentic 优化

场景	命令
快速检查	ty check
CI 检查	ty check --hide-progress
详细调试	ty check --verbose
检查模块	ty check src/module/
严格错误检查	ty check --error possibly-unbound
忽略规则	ty check --ignore unknown-type

快速参考

必备命令

# Basic type checking
ty check                          # Check current directory
ty check src/                     # Check specific directory
ty check file.py                  # Check specific file

# Configuration
ty check --config ty.toml         # Use custom config
ty check --python 3.12            # Specify Python version

# Output control
ty check --verbose                # Verbose output
ty check --hide-progress          # No progress indicators

# Rule control
ty check --error RULE             # Treat as error
ty check --warn RULE              # Treat as warning
ty check --ignore RULE            # Ignore rule

# File selection
ty check --exclude "pattern"      # Exclude files

最简配置

# pyproject.toml
[tool.ty]
python-version = "3.12"
exclude = ["**/__pycache__", "**/.venv"]

另请参阅

• basedpyright-type-checking - 默认设置更严格的替代类型检查器
• ruff-linting - 来自同一生态系统的快速代码检查
• ruff-formatting - 来自同一生态系统的快速格式化
• python-development - 通用 Python 开发模式

参考资料

• 官方文档：https://docs.astral.sh/ty/
• GitHub：https://github.com/astral-sh/ty
• 博客公告：https://astral.sh/blog/ty
• Playground：https://play.ty.dev/