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，尤其是当你看到以下情况时：
  • [tool.ty]
    配置段存在于
    pyproject.toml
    中
  • 存在
    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:
如需详细信息，请查阅官方文档：