【Python】 拡張子が .pyi のファイルってなんだろ？

この記事では、拡張子が .pyi となっているファイルについて解説します。

.pyi とは？

pyiファイルは、Python で静的型チェックを行うための mypyライブラリ が 型情報を記録しておくスタブファイルです。

スタブとは、大規模なシステム開発の際に、完成済みのプログラムの動作を検証するための、完成していないプログラムの代用となるプログラムのことである。または、外部プログラムとの細かなインターフェース制御を引き受けるプログラムのことである。
引用先: スタブとは (stub)： - IT用語辞典バイナリ

これではよくわからないので 実際に pyiファイルの使い方を見ていきますが、それにはまず、mypy について知っておく必要があります。

前提知識: mypyとは？

mypy とは、型ヒント通りにコードが書けているかチェックするライブラリです。

型ヒントで使用する型を指定しよう

例えば、以下のように module.py の関数に型ヒントを記述します。

module.py

def add(x: int, y: int) -> int:
    return x + y

定義した関数を main.py から使ったとする。

main.py

import module

module.add(1, 2)

この時、mypyコマンドを使って main.py を実行することで指定した型ヒント通りコードが書けているか確認することができる。

コマンドライン

$ mypy main.py
Success: no issues found in 1 source file

module.add()関数 に 型ヒントと異なる型を指定するとエラーが発生する。

main.py

import module

module.add(0.9, 1.8)

実行結果

$ mypy main.py   
main.py:3: error: Argument 1 to "add" has incompatible type "float"; expected "int"
Found 1 error in 1 file (checked 1 source file)

このように、静的型をチェックを行えるのが mypy です。

pyiファイルの使い方

pyiファイルは、mypy を使って型チェックは行いたいけどソースコードに型ヒントを書きたくないって時に使用します。

先ほどの例では module.add()関数 に直接型ヒントを書いていましたが、module.pyi を定義することで module.add()関数 に型ヒントを書かなくても型チェックを行えるようになります。

module.py

def add(x, y):
    return x + y

module.pyi

def add(x: int, y: int) -> int: ...

関数の中身は ... で省略できます。

同じように実行することで同様の結果を得ることができます。

main.py

import module

module.add(0.9, 1.8)

実行結果

$ mypy main.py   
main.py:3: error: Argument 1 to "add" has incompatible type "float"; expected "int"
Found 1 error in 1 file (checked 1 source file)

なので、pyiファイル を見かけたら 「mypy で型チェックを行う型ヒントが書かれているんだな〜。」 って解釈すれば良いかと思います。