AI

tyの使い方完全ガイド【インストールから応用まで】

tyの使い方完全ガイド【インストールから応用まで】

Python開発の現場では、コードの品質と堅牢性を保つことが重要です。特に大規模なプロジェクトでは、型ヒントを適切に活用することで、バグを未然に防ぎ、チーム開発を円滑に進められます。しかし、既存の型チェッカーは速度やIDE連携に課題を抱えることがありました。

もし型チェックが遅く、デバッグに多くの時間を費やしていたらどうでしょうか。CI/CDパイプラインも型チェックのために長時間停止し、開発のボトルネックとなるかもしれません。実行時に型エラーが発覚し、本番環境で予期せぬ障害を引き起こすこともあり得ます。

ここに、その課題を解決する強力なツールが登場しました。それが「ty」です。tyがあれば、数千行にも及ぶPythonコードも瞬時にチェックできます。型エラーは開発中にリアルタイムで通知され、修正も容易です。CI/CDも高速化し、あなたはより重要な開発作業に集中できるでしょう。

tyはPython開発における型安全性の常識を塗り替える可能性を秘めています。この記事では、tyの基本的な使い方から、実際の開発で役立つ応用例までを詳しく解説します。

tyとは

tyは、Pythonのための超高速な型チェッカーであり、言語サーバーです。Rustで書かれており、既存の型チェッカーであるmypyやPyrightと比較して、10倍から100倍もの速度を実現しています。

このツールは、Python開発ツールで有名なAstral社が開発しました。Astral社は、高速なパッケージインストーラ uv や、Linter/Formatterの Ruff の開発元でもあります。tyはこれらのツールと連携し、Python開発体験全体を向上させることを目指しています。

tyの主な目的は、開発者が型ヒントを最大限に活用し、コードの品質と信頼性を高めることです。ベータ版ではありますが、その速度と高機能性から、次世代のPython型チェッカーとして大きな注目を集めています。

tyの主要な特徴:

  • 圧倒的な速度: mypyやPyrightよりも桁違いに高速です。
  • 包括的な診断: エラー箇所や原因を詳細に表示します。
  • 高度なIDE連携: 言語サーバーとして、VS Codeなどのエディタと深く統合されます。
  • 設定の柔軟性: ルールレベルの調整や、ファイルごとの設定が可能です。
  • 段階的な導入: 部分的に型付けされたコードや、既存プロジェクトへの導入を考慮した設計です。
  • 先進的な型システム: 交差型（intersection types）や高度な型ナローイングをサポートします。

tyは「ティー・ワイ」と発音します。Pythonの型（Type）をチェックするツールとして、その名がつけられました。

インストール方法

tyを使うには、まずインストールが必要です。公式では、同じAstral社製のパッケージインストーラ uv を介した uvx コマンドの使用が推奨されています。

uvのインストール

uvx を使うためには、まず uv をインストールする必要があります。uv はRust製で、pipよりも高速なパッケージ管理ツールです。

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

上記のコマンドを実行すると、uv が $HOME/.cargo/bin にインストールされます。このパスを環境変数 PATH に追加してください。

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc # または ~/.zshrc
source ~/.bashrc # または source ~/.zshrc

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

Windowsの場合も、uv がインストールされたディレクトリを環境変数 Path に追加してください。

tyのインストールと実行

uv がインストールされていれば、uvx コマンドで ty を直接実行できます。uvx は一時的にパッケージをインストールして実行するため、グローバル環境を汚染しません。

uvx ty check

プロジェクトに ty をインストールする場合は、uv を使ってインストールします。

uv pip install ty

または、Python標準の pip を使ってインストールすることも可能です。

pip install ty

インストール後、ty --version を実行してバージョンが表示されれば成功です。

ty --version

基本的な使い方

tyの最も基本的な使い方は、プロジェクトの型チェックを実行することです。ここでは、最低限知っておきたいコマンドを3つ紹介します。

1. プロジェクト全体の型チェック

現在のディレクトリにあるPythonプロジェクト全体を型チェックするには、check サブコマンドを使用します。

ty check

このコマンドは、pyproject.toml などの設定ファイルに基づいて、プロジェクト内のすべてのPythonファイルをスキャンし、型エラーを報告します。

実行例:

例えば、main.py というファイルがあり、以下のようなコードが含まれているとします。

# main.py
def add(a: int, b: int) -> str: # 意図的に型エラーを混入
    return a + b

def subtract(a: int, b: int) -> int:
    return a - b

result_add: int = add(1, 2) # 戻り値の型が異なる
result_sub: str = subtract(5, 3) # 変数の型が異なる

print(result_add)
print(result_sub)

この main.py が存在するディレクトリで ty check を実行すると、以下のような出力が得られます。

$ ty check
error: Incompatible return type for `add`. Expected `str`, got `int` (TY0001)
  ┌─ main.py:2:12
  │
2 │ def add(a: int, b: int) -> str:
  │            ^^^ Expected `str`, got `int`
  │
  = This is an error because the function `add` is annotated to return `str`, but the expression `a + b` has type `int`.

error: Incompatible assignment. Expected `int`, got `str` (TY0002)
  ┌─ main.py:7:15
  │
7 │ result_add: int = add(1, 2)
  │               ^^^ Expected `int`, got `str`
  │
  = This is an error because `add` returns `str`, but `result_add` is annotated as `int`.

error: Incompatible assignment. Expected `str`, got `int` (TY0002)
  ┌─ main.py:8:15
  │
8 │ result_sub: str = subtract(5, 3)
  │               ^^^ Expected `str`, got `int`
  │
  = This is an error because `subtract` returns `int`, but `result_sub` is annotated as `str`.

Found 3 errors.

tyは、エラーの種類、ファイル名、行番号、そして詳細な説明を非常に読みやすい形で提示します。各エラーには TY0001 のようなエラーコードも付与されます。

2. 特定のファイルを型チェック

プロジェクト全体ではなく、特定のファイルだけを型チェックしたい場合は、check コマンドの後にファイルパスを指定します。

ty check src/my_module.py

3. 設定ファイルの初期化

tyの設定は pyproject.toml ファイルに記述することが推奨されています。ty init コマンドを実行すると、この設定ファイルに [tool.ty] セクションのひな形を追加できます。

ty init

実行すると、pyproject.toml が存在しない場合は新しく作成し、存在する場合は追記します。これにより、tyの各種設定を簡単に始められます。

pyproject.toml の例:

# pyproject.toml
[tool.ty]
# Pythonのターゲットバージョンを指定
target-version = "py311"
# 除外するファイルやディレクトリを指定
exclude = ["tests/*", "docs/*"]

これらのコマンドを覚えるだけで、tyを使った基本的な型チェックを開始できます。

便利な使い方・応用例 3選

tyの真価は、その速度と柔軟な設定、そしてIDEとの連携にあります。ここでは、実際の開発シーンで役立つ応用例を3つ紹介します。

1. CI/CDパイプラインへの組み込み

tyの最大のメリットの一つはその高速性です。この特徴を活かし、CI/CDパイプラインに型チェックを組み込むことで、マージ前にコードの品質を保証できます。

例えばGitHub Actionsを使ったCI/CDワークフローにtyを組み込む場合、以下のように設定できます。

# .github/workflows/type-check.yml
name: Type Check

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh
      - name: Add uv to PATH
        run: echo "$HOME/.cargo/bin" >> $GITHUB_PATH

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11' # プロジェクトのPythonバージョンに合わせる

      - name: Install project dependencies and ty
        run: uv pip install -r requirements.txt ty

      - name: Run ty check
        run: ty check

この設定により、main ブランチへのプッシュやプルリクエスト時に、自動的に ty check が実行されます。型エラーがあればCIが失敗し、マージを阻止することで、本番環境へのバグ混入リスクを大幅に低減できます。

2. 大規模プロジェクトでの段階的導入と部分的な抑制

既存の大規模なPythonプロジェクトにtyを導入する際、一度に全ての型エラーを修正するのは困難な場合があります。tyは、このような状況に対応するための柔軟な設定を提供します。

a. ファイルごとの設定上書き（overrides）

pyproject.toml の [tool.ty.overrides] セクションを使用すると、特定のファイルやディレクトリに対して異なるルールを適用できます。

例えば、レガシーコードが多く残る src/legacy/ ディレクトリでは、型アノテーションの不足に関する警告レベルを下げる設定が考えられます。

# pyproject.toml
[tool.ty]
target-version = "py311"

[tool.ty.rules]
# 未使用変数に関する警告をエラーにする
unused-variable = "error"

[tool.ty.overrides]
# src/legacy/ ディレクトリ内のファイルでは、型アノテーションの不足を警告として扱う
"src/legacy/*" = { missing-annotation = "warning" }
# 特定のファイルでは、すべての型チェックを無視する
"src/temp_script.py" = { ignore = true }

これにより、新規コードには厳格なルールを適用しつつ、既存のレガシーコードには段階的に型付けを進められるようになります。

b. 抑制コメント

特定の行やブロックで型エラーを抑制したい場合は、# ty: ignore コメントを使用します。

# my_module.py
def process_data(data: dict) -> int:
    # 辞書のキーの型が不明なため、tyが警告を出す可能性がある
    # この行での型チェックを一時的に無視する
    value = data["some_key"] # ty: ignore[TY0003]
    return int(value)

# ファイル全体の型チェックを無視したい場合 (非推奨だが緊急時などに)
# ty: ignore-file

# ty: ignore[TYXXXX] のように特定のエラーコードを指定することも可能です。これにより、意図しない他のエラーまで無視してしまうことを防げます。

3. エディタ（VS Codeなど）との連携によるリアルタイムフィードバック

tyは強力な言語サーバー機能を備えており、VS Code、PyCharm、Neovimなどのエディタと深く統合できます。これにより、コードを記述中にリアルタイムで型エラーのフィードバックを受け取ることが可能になります。

VS Codeでの連携例:

  1. tyのインストール: プロジェクトの仮想環境に ty をインストールします。

    uv pip install ty
# または pip install ty

  2. VS Code拡張機能のインストール: VS Codeの拡張機能マーケットプレイスで「ty」を検索し、公式のty拡張機能をインストールします。

  3. 設定の確認: 通常、拡張機能をインストールするだけで自動的にty言語サーバーが起動し、型チェックが開始されます。VS Codeの設定 (settings.json) で、tyの実行パスや設定ファイルを指定することも可能です。

    // .vscode/settings.json
{
    "python.analysis.typeCheckingMode": "off", // Pylanceなどの他の型チェッカーをオフにする
    "ty.path": ["uvx", "ty"], // uvxを使ってtyを実行する
    "ty.args": ["--config", "pyproject.toml"], // tyに渡す引数
    "ty.enabled": true
}

    "python.analysis.typeCheckingMode": "off" は、Pylanceなど他のPython言語サーバーによる型チェックを無効にし、tyに任せるための設定です。

これにより、コードを入力するそばから型エラーがハイライト表示されたり、カーソルを合わせたときに型の情報が表示されたり、コード補完が型情報を考慮して行われたりします。開発体験が劇的に向上し、バグの早期発見・修正に繋がります。

他ツールとの組み合わせ

tyは単体でも強力ですが、他のツールと組み合わせることで、その真価をさらに発揮します。特に、同じAstral社製のツールとの相性は抜群です。

1. uv (パッケージマネージャー)

uv は pip や pip-tools の代替となる高速なPythonパッケージマネージャーです。tyと同じAstral社製であり、uvx コマンドを通じてtyを簡単に実行できます。

  • 組み合わせ方:uv を使ってプロジェクトの依存関係と ty をインストールし、uv run ty check や uvx ty check で型チェックを実行します。これにより、環境構築から型チェックまでをスムーズに実行できます。

    # 依存関係をインストール
uv pip install -r requirements.txt

# tyをインストール
uv pip install ty

# tyを実行
uv run ty check

2. Ruff (Linter & Formatter)

Ruff もまた、tyと同じAstral社製の超高速なPython LinterおよびFormatterです。tyと同様にRustで書かれており、非常に高速に動作します。コードのスタイルチェックや自動整形と、型チェックを組み合わせることで、一貫したコード品質を保てます。

  • 組み合わせ方:pyproject.toml でtyとRuffの設定を一元管理し、CI/CDパイプラインやpre-commitフックで両方を実行します。

    # pyproject.toml
[tool.ruff]
line-length = 88
select = ["E", "F", "W", "I"] # よく使われるルールセット

[tool.ty]
target-version = "py311"
# ... tyの他の設定 ...

    CI/CDやpre-commitで両方を実行する例:

    # pre-commit設定例 (.pre-commit-config.yaml)
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.0.292 # 最新バージョンを指定
  hooks:
    - id: ruff
      args: [--fix, --exit-non-zero-on-fix]
    - id: ruff-format
- repo: local
  hooks:
    - id: ty-check
      name: Run ty check
      entry: uvx ty check # または ty check
      language: system
      types: [python]
      pass_filenames: false

3. Git Hooks (pre-commitなど)

pre-commit のようなGitフック管理ツールとtyを組み合わせることで、コミット前に自動的に型チェックを実行できます。これにより、型エラーを含むコードがリポジトリにコミットされるのを防ぎます。

  • 組み合わせ方:pre-commit をインストールし、.pre-commit-config.yaml にtyの実行設定を追加します。

    # .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: ty-check
        name: Run ty check with ty
        entry: ty check
        language: system # 仮想環境のtyを使用
        types: [python]
        pass_filenames: false # プロジェクト全体をチェック

    この設定により、git commit を実行するたびに ty check が走り、型エラーがあればコミットが中断されます。

よくある設定・カスタマイズ

tyの設定は、PEP 518で定義されている pyproject.toml ファイルの [tool.ty] セクションに記述することが推奨されます。これにより、プロジェクトの依存関係やビルド設定などと一元的に管理できます。

以下に、よく使われる設定項目とカスタマイズ例を示します。

# pyproject.toml

[tool.ty]
# Pythonのターゲットバージョンを指定します。
# これにより、tyは指定されたPythonバージョンの構文や標準ライブラリに基づいて型チェックを行います。
target-version = "py311"

# 型チェックから除外するファイルやディレクトリを指定します。
# globパターンを使用できます。例えば、テストコードやドキュメント生成用のスクリプトなど。
exclude = ["tests/*", "docs/*", "old_scripts/temp_*.py"]

# 型チェックに含めるファイルやディレクトリを指定します。
# excludeと組み合わせて、より詳細な制御が可能です。
# include = ["src/**/*.py"]

# 型チェックのルールレベルをカスタマイズします。
# 各ルールに対して "error", "warning", "ignore" のいずれかを設定できます。
# デフォルトでは多くのルールが "error" に設定されています。
[tool.ty.rules]
# 未使用の変数をエラーとして扱います。
unused-variable = "error"
# 関数の戻り値の型アノテーションがない場合に警告を出します。
missing-return-type = "warning"
# 関数の引数に型アノテーションがない場合に警告を出します。
missing-parameter-type = "warning"
# Any型が使われている箇所を警告します。厳密な型付けを目指す場合に有効です。
disallow-any = "warning"
# オーバーロードの定義が正しくない場合にエラーを出します。
invalid-overload = "error"
# 未解決のインポートをエラーとして扱います。
unresolved-import = "error"

# 特定のファイルやディレクトリに対して、ルールレベルを上書きします。
# 大規模な既存プロジェクトで段階的にtyを導入する際に非常に役立ちます。
[tool.ty.overrides]
# src/legacy/ ディレクトリ内の全てのファイルでは、型アノテーションの不足を警告として扱います。
"src/legacy/*" = { missing-annotation = "warning" }

# 特定のファイルでは、すべての型チェックを完全に無視します。
# 緊急時や一時的なスクリプトなどで使用します。
"src/experimental_feature.py" = { ignore = true }

# 特定のファイルでは、特定のルールのみを無視します。
"src/data_processing/script.py" = { rules = { disallow-any = "ignore" } }

設定のポイント

  • target-version: プロジェクトで使われているPythonのバージョンと一致させることが重要です。これにより、tyは正確な構文解析と型チェックを行えます。
  • exclude / include: プロジェクトの構造に合わせて適切に設定することで、不要なファイルのチェックをスキップし、型チェックの速度を向上させます。
  • [tool.ty.rules]: プロジェクトの型チェックの厳密さを調整します。新しいプロジェクトでは厳しめの設定から始め、既存のプロジェクトでは段階的に厳しくしていくのが良いでしょう。
  • [tool.ty.overrides]: 大規模なプロジェクトや、部分的にしか型付けされていないコードベースにtyを導入する際に非常に強力な機能です。特定のパスにのみ緩いルールを適用することで、導入のハードルを下げられます。

これらの設定を適切に行うことで、tyをプロジェクトのニーズに合わせて最適化し、最大限に活用できます。

今日からできる実行プラン

tyの導入は、Python開発の品質と効率を大きく向上させる第一歩です。ここでは、今日からtyを使い始めるための3ステップを紹介します。

ステップ1: uvとtyをインストールする

まずは、tyを動かすための環境を整えましょう。公式が推奨する uv を介したインストールが最もスムーズです。

# uvをインストール（macOS/Linuxの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc # または ~/.bashrc
source ~/.zshrc # 環境変数を反映

# プロジェクトの仮想環境にtyをインストール
# プロジェクトルートに移動して実行
uv pip install ty

uv がインストールされていれば、uvx ty check でtyを一時的に実行することも可能です。

ステップ2: 既存のPythonプロジェクトで型チェックを試す

インストールが完了したら、あなたの既存のPythonプロジェクトで ty check を実行してみましょう。

# プロジェクトのルートディレクトリで実行
ty check

初めて実行すると、多くの型エラーや警告が表示されるかもしれません。これはtyが潜在的な問題を顕在化させている証拠です。最初はすべてのエラーを修正しようとせず、どのような種類のエラーが多いのか、どこに問題があるのかを把握するだけでも十分です。

ステップ3: pyproject.tomlを設定し、IDE連携を検討する

tyの初期設定ファイルを生成し、プロジェクトに合わせてカスタマイズします。

ty init

生成された pyproject.toml を開き、target-version や exclude、include などをプロジェクトに合わせて調整してください。特に [tool.ty.overrides] を活用し、レガシーコードなどには緩やかなルールを適用することで、段階的な導入が可能になります。

次に、普段使っているエディタ（VS Codeなど）にtyの拡張機能をインストールし、言語サーバーとの連携を試してみてください。リアルタイムでのフィードバックは、開発体験を大きく変えるはずです。

これらのステップを踏むことで、tyの強力な型チェック機能をあなたの開発ワークフローにスムーズに組み込めるでしょう。tyはまだベータ版ですが、その革新的な速度と機能は、Python開発の未来を形作る重要なツールとなるはずです。ぜひ今日からtyを体験し、より堅牢で効率的な開発を目指してください。

参考文献

広告

-AI