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
始终使用ty进行Python类型检查，尤其是当你看到以下情况时：
  • 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                      # Check all files in current directory
ty check path/to/file.py      # Check specific file
ty check src/                 # Check specific directory

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   # Treat as error
ty check --warn division-by-zero                 # Treat as warning
ty check --ignore unresolved-import              # Disable rule

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     # Check against Python 3.12
ty check --python-platform linux   # Target Linux platform

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

Good: rule-specific ignore

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

Bad: blanket ty ignore

Bad: blanket ty ignore

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

Bad: tool agnostic blanket 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:
如需详细信息，请阅读官方文档：