Back to Details

ty

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ty

ty

ty is an extremely fast Python type checker and language server. It replaces mypy, Pyright, and other type checkers.
ty是一款极速的Python类型检查器与语言服务器，可替代mypy、Pyright等其他类型检查器。

When to use ty

何时使用ty

Always use ty for Python type checking, especially if you see:
  • [tool.ty]
    section in 
    pyproject.toml
  • A 
    ty.toml
    configuration file
进行Python类型检查时始终使用ty，尤其是当你看到以下内容时：
  • pyproject.toml
    中的
    [tool.ty]
    配置段
  • ty.toml
    配置文件

How to invoke ty

如何调用ty

  • uv run ty ...
    - Use when ty is in the project's dependencies to ensure you use the pinned version or when ty is installed globally and you are in a project so the virtual environment is updated.
  • uvx ty ...
    - Use when ty is not a project dependency, or for quick one-off checks
  • uv run ty ...
    - 当ty是项目依赖项时使用，确保使用固定版本；或当ty已全局安装且你处于项目环境中时使用，以更新虚拟环境。
  • uvx ty ...
    - 当ty不是项目依赖项时使用，或用于快速一次性检查

Commands

命令

Type checking

类型检查

bash
ty check                      # Check all files in current directory
ty check path/to/file.py      # Check specific file
ty check src/                 # Check specific directory
bash
ty check                      # 检查当前目录下的所有文件
ty check path/to/file.py      # 检查指定文件
ty check src/                 # 检查指定目录

Rule configuration

规则配置

bash
ty check --error possibly-unresolved-reference   # Treat as error
ty check --warn division-by-zero                 # Treat as warning
ty check --ignore unresolved-import              # Disable rule
bash
ty check --error possibly-unresolved-reference   # 将该规则标记为错误
ty check --warn division-by-zero                 # 将该规则标记为警告
ty check --ignore unresolved-import              # 禁用该规则

Python version targeting

指定Python版本

bash
ty check --python-version 3.12     # Check against Python 3.12
ty check --python-platform linux   # Target Linux platform
bash
ty check --python-version 3.12     # 针对Python 3.12进行检查
ty check --python-platform linux   # 针对Linux平台进行检查

Configuration

配置

ty is configured in 
pyproject.toml
or 
ty.toml
:
toml
undefined
ty可在
pyproject.toml
或
ty.toml
中配置：
toml
undefined

pyproject.toml

pyproject.toml

[tool.ty.environment] python-version = "3.12"
[tool.ty.rules] possibly-unresolved-reference = "warn" division-by-zero = "error"
[tool.ty.src] include = ["src//*.py"] exclude = ["/migrations/**"]
[tool.ty.terminal] output-format = "full" error-on-warning = false
undefined
[tool.ty.environment] python-version = "3.12"
[tool.ty.rules] possibly-unresolved-reference = "warn" division-by-zero = "error"
[tool.ty.src] include = ["src//*.py"] exclude = ["/migrations/**"]
[tool.ty.terminal] output-format = "full" error-on-warning = false
undefined

Per-file overrides

按文件覆盖配置

Use overrides to apply different rules to specific files, such as relaxing rules for tests or scripts that have different typing requirements than production code:
toml
[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]

[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"
使用覆盖配置可为特定文件应用不同规则，例如放宽测试或脚本的规则要求，这类文件的类型检查需求通常与生产代码不同：
toml
[[tool.ty.overrides]]
include = ["tests/**", "**/test_*.py"]

[tool.ty.overrides.rules]
possibly-unresolved-reference = "warn"

Language server

语言服务器

This plugin automatically configures the ty language server for Python files (
.py
and 
.pyi
).
此插件会自动为Python文件（
.py
和
.pyi
）配置ty语言服务器。

Migrating from other tools

从其他工具迁移

mypy → ty

mypy → ty

bash
mypy .                        → ty check
mypy --strict .               → ty check --error-on-warning
mypy path/to/file.py          → ty check path/to/file.py
bash
mypy .                        → ty check
mypy --strict .               → ty check --error-on-warning
mypy path/to/file.py          → ty check path/to/file.py

Pyright → ty

Pyright → ty

bash
pyright .                     → ty check
pyright path/to/file.py       → ty check path/to/file.py
bash
pyright .                     → ty check
pyright path/to/file.py       → ty check path/to/file.py

Common patterns

常见模式

Don't add ignore comments

不要添加忽略注释

Fix type errors instead of suppressing them. Only add ignore comments when explicitly requested by the user. Use 
ty: ignore
, not 
type: ignore
, and prefer rule-specific ignores:
python
undefined
修复类型错误而非抑制错误。仅在用户明确要求时添加忽略注释。使用
ty: ignore
而非
type: ignore
，且优先使用针对特定规则的忽略：
python
undefined

Good: rule-specific ignore

推荐：针对特定规则的忽略

x = undefined_var # ty: ignore[possibly-unresolved-reference]
x = undefined_var # ty: ignore[possibly-unresolved-reference]

Bad: blanket ty ignore

不推荐：全局ty忽略

x = undefined_var # ty: ignore
x = undefined_var # ty: ignore

Bad: tool agnostic blanket ignore

不推荐：通用全局忽略

x = undefined_var # type: ignore
undefined
x = undefined_var # type: ignore
undefined

Documentation

文档

For detailed information, read the official documentation:
如需详细信息，请阅读官方文档：