astral-ty

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ty: Python Type Checker and Language Server

ty：Python类型检查器与语言服务器

ty is an extremely fast Python type checker and language server that replaces mypy, Pyright, and other type checkers.

ty是一款极速的Python类型检查器与语言服务器，可替代mypy、Pyright等其他类型检查器。

Navigation Rule

导航规则

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
```
配置文件

Invocation Rules

调用规则

Choose the right way to invoke 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

选择正确的ty调用方式：

```
uv run ty ...
```
- 当ty是项目依赖项时使用，确保使用固定版本；或当ty全局安装且你处于项目环境中时使用，此时虚拟环境会被更新。
```
uvx ty ...
```
- 当ty不是项目依赖项时使用，或用于快速一次性检查

Type Checking Commands Rule

类型检查命令规则

Use these commands for 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

See references/basic-checking.md for basic type checking examples.

使用以下命令进行类型检查：

bash

ty check                      # 检查当前目录下的所有文件
ty check path/to/file.py      # 检查指定文件
ty check src/                 # 检查指定目录

如需基础类型检查示例，请查看references/basic-checking.md。

Rule Configuration Rules

规则配置规则

Configure rule levels as needed:

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 Rules

Python版本目标规则

Target specific Python versions and platforms:

bash

ty check --python-version 3.12     # Check against Python 3.12
ty check --python-platform linux   # Target Linux platform

See references/version-targeting.md for version targeting examples.

指定目标Python版本与平台：

bash

ty check --python-version 3.12     # 针对Python 3.12进行检查
ty check --python-platform linux   # 目标平台为Linux

如需版本目标示例，请查看references/version-targeting.md。

Configuration Rule

配置规则

ty is configured in

pyproject.toml

ty.toml

toml

undefined

ty的配置可在

pyproject.toml

或

ty.toml

中进行：

toml

undefined

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


See [references/configuration.md](references/configuration.md) for configuration examples and per-file overrides.

[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


如需配置示例与单文件覆盖规则，请查看[references/configuration.md](references/configuration.md)。

Per-File Overrides Rule

单文件覆盖规则

Use overrides to apply different rules to specific files:

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 Rule

语言服务器规则

The plugin automatically configures the ty language server for Python files (

.py

and

.pyi

插件会自动为Python文件（

.py

与

.pyi

）配置ty语言服务器。

Migration Rules

迁移规则

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

bash

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

See references/migration.md for migration examples.

bash

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

如需迁移示例，请查看references/migration.md。

Ignore Comments Rule

忽略注释规则

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]

Bad: blanket ty ignore

不推荐：全局ty忽略

x = undefined_var # ty: ignore

Bad: tool agnostic blanket ignore

不推荐：通用工具全局忽略

x = undefined_var # type: ignore

undefined

x = undefined_var # type: ignore

undefined

Documentation Reference

文档参考

For detailed information, see the official documentation at https://docs.astral.sh/ty/

如需详细信息，请查看官方文档：https://docs.astral.sh/ty/

Additional References

额外参考

CI/CD integration: See references/ci-cd.md
Advanced configuration: See references/advanced.md

CI/CD集成：查看references/ci-cd.md
高级配置：查看references/advanced.md