Last update: 2023-12-06

Pyrightを使って型チェックする

Pyrightとは

PyrightはMicrosoft製のPythonコード向け静的型チェッカーです。 実行時にエラーが出ないコードだったとしても、型ヒントに合致しない値が代入される可能性がある場合は WarningやErrorを出してくれます。 

def hello(name: str):
    print(f'hello {name}!')

hello(10) # <- Error: 10はstr型ではないので割り当てられない。

導入は簡単です。

pipでインストールして… 

pip install pyright

コマンドを実行すればすぐに使い始めることができます。 

pyright

.../src/mypkg/hoge.py:4:7 - error: Argument of type "Literal[10]" cannot be assigned to parameter "msg" of type "str"
in function "hello"
    "Literal[10]" is incompatible with "str" (reportGeneralTypeIssues)
  1 error, 0 warnings, 0 informations

なぜPyrightを使うのか？

静的型チェックを行うためのパッケージは他にもあります。特にmypyは昔からメンテナンスが続いており、 信頼できるチェッカーの１つです。 その中でもPyrightが優れている点として、高速な動作と差分更新を行うためのWatchモードの搭載、 設定による細かい制御が可能であることなどを謳っています。

しかし、Pyrightを採用することによる最大の利点は、VSCodeに採用されているPython言語サポート用 バックエンドPylanceと互換性があることです。

The Pylance codebase is not open-source but you can contribute to Pyright to make improvements to the core typing engine that powers the Pylance experience.

– https://github.com/microsoft/pylance-release

PylanceはVSCodeの案内に従ってインストールすれば簡単に導入することができるので、 Pythonを書いている殆どの人は既に使っていると思います。

図1: Python拡張機能インストールの案内

表示されるポップアップのインストールボタンをクリックするだけで拡張機能が使える状態になります。

Pylanceの設定

Pyrightで型チェックを実行する前にVSCode上で正しく型チェック結果を可視化できるように設定しておきましょう。 VSCodeのPythonの拡張機能を入れていたとしても、型チェックの機能が有効化されていない場合があります。

左下の歯車から設定を開き、 python.analysis.typeCheckingMode を検索して表示してみてください。 初期値はOFFになっているので、 basic または strict にに変更しましょう。

すると次のように型チェックによるエラーメッセージが出力されるようになります。

図2: VSCodeのエラーメッセージ

strict モードでは、より細かくエラーを出してくれます。 VSCode上で表示されるエラーの数が増えますが、 この時点ではエラーに対するペナルティはないので、 より推奨される方法でコードを書きたい人は設定してみましょう。

Pyrightの運用

Pyrightを使えば、先述のVSCodeで実行されるような型チェックをコマンドラインで実行できます。 CIやpre-commmitを使って、型チェックエラーのコードの混入を機械的に防ぐことができるので、 レビュー工数の削減につながります。

Pyrightは特に設定しなくても動作しますが、チェックを除外するファイルの指定や、 無視するチェック項目など、細かく設定することができます。 設定は pyproject.toml や pyrightconfig.json ファイルに記載します。 

[tool.pyright]
include = ["src"]
exclude = ["**/node_modules",
    "**/__pycache__",
    "src/experimental",
    "src/typestubs"
]
ignore = ["src/oldstuff"]
defineConstant = { DEBUG = true }
stubPath = "src/stubs"

...
https://microsoft.github.io/pyright/#/configuration?id=sample-pyprojecttoml-file

Pyrightでは typeCheckingMode の初期値が standard になっています。このModeはVSCode側には存在しないので、 VSCodeに合わせる場合は、設定ファイルに記載して変更しておきます。 

[tool.pyright]
...
typeCheckingMode = "basic"

また、CIやpre-commitで実行するPyrightを strict モードで実行するのはあまりおすすめしません。 型チェックの対応に追われてなかなかコミットやマージができなくなります。 少なくともPyrightのチェックの厳しさはVSCodeを超えないようにしましょう。VSCode上で現れないエラーを修正する作業は かえって効率を落とす原因になります。

CIやpre-commitへの設定方法は公式ページにも記載があります。

型チェックの抑制

行末に type: ignore コメントを書くことで、その行のエラーを抑制することができます。 この記法はmypyなど他のチェッカーにも有効な一般的な方法です。 

a: int = "hoge"  # type: ignore

また、 pyright から始まるコメントで、特有の設定を記載することもできます。 次の例ではエラーを指定して抑制しています。 

# pyright: ignore [reportPrivateUsage, reportGeneralTypeIssues]

エラーの名前はVSCodeのメッセージにも記載に記載されいてるので、 エディタから離れることなくこれらのコメントを追加することができます。

まとめ

VSCodeの内部でも使われている静的型チェッカー、Pyrightを紹介しました。 mypyなど、他の型チェッカーをCIに導入する場合と比べて、VSCodeとの挙動の差がほとんどなくなるため、 Pylanceに対応するためのチューニングが不要となり、開発体験が良くなります。

開発チーム内でVSCodeユーザーが多数派の方々にはおすすめです。