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 は IDE 連携用の PyCharm プラグインを提供します。

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：約 5 ミリ秒で診断を再計算
• Pyright：約 400 ミリ秒
• 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/

エージェント向けの最適化

コンテキスト	コマンド
クイックチェック	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
• プレイグラウンド：https://play.ty.dev/