PythonのTypeGuardとTypeIsによる型の絞り込み

TypeGuardとTypeIsとは
TypeGuardとTypeIsとは、自作の判定関数の戻り値の型の注釈である。
この注釈で、関数の結果が引数の型の絞り込みの条件になる。
実行時の戻り値は普通のboolの値で、効果は型チェッカーの判定に限られる。
TypeGuardはPython 3.10、TypeIsはPython 3.13で typingに追加された 。
それ以前のPythonではtyping_extensions(TypeIsは4.10.0以降)から利用する。
- 戻り値の型が
boolの自作の判定関数では、中でisinstanceを実行していても、型チェッカーはifの分岐の中で引数の型を限定しない - 説明用の判定関数
is_strの戻り値の型をTypeGuard[str]かTypeIs[str]にすると、if is_str(value):の分岐の中ではstrのメソッドの呼び出しがエラーにならない TypeGuardの絞り込みはTrueの分岐だけで、TypeIsはTrueとFalseの両方の分岐で型を限定するint | str型の値のTypeIs[str]のelseの分岐はintになり、TypeGuard[str]ではint | strのままである- 引数の型が
list[object]の関数のTypeIs[list[str]]のように、引数の型の部分型でない型への絞り込みはTypeIsでは不可能で、TypeGuardだけで可能である
- 判定の条件と戻り値の型の約束の一致は型チェッカーの確認の対象外で、条件に誤りがあれば絞り込みの判定も不正確になる
前提となる用語
型の絞り込み
型の絞り込み(type narrowing)とは、型チェッカーが条件の判定をもとに、分岐の中の変数の型を型注釈の型(declared type)より限定する処理である。
int | str型のvalueは、if isinstance(value, str):の分岐の中ではstr型と判定される。
条件として解釈される式の種類と、絞り込みの対象外になる書き方は Pythonの型チェッカーによる型の絞り込みの仕組み で説明した。
部分型
型Aの値を型Bの値の代わりに利用可能なとき、AをBの部分型と呼ぶ。
strはobjectの部分型で、boolはintの部分型である。
list[object]型の値にはintの要素を追加できるが、list[str]型の値には追加できないので、list[str]はlist[object]の部分型ではない。
戻り値の型がboolの関数では型が限定されない
以降の例の型チェッカーの診断はmypyとpyrightの標準の設定での出力である。
例の typing.assert_type はPython 3.11以降の関数である。
assert_typeは、型チェッカーの判定の結果が第2引数の型と異なる場合をエラーにする関数で、実行時には何もしない。
確認の処理を自作の関数の中に記述すると、その関数の呼び出しは型チェッカーにとって絞り込みの条件ではない。
def is_str(value: object) -> bool:
return isinstance(value, str)
def show(value: int | str) -> None:
if is_str(value):
print(value.upper())
# mypy
# error: Item "int" of "int | str" has no attribute "upper" [union-attr]
# pyright
# error: Cannot access attribute "upper" for class "int"
# 実行時(show("hello"))
# HELLO
isinstanceをif文の条件に直接記述すれば絞り込みの対象になるが、要素の型の確認のような複数の行の処理は、関数にしないと呼び出し側ごとに重複する。
TypeGuardで関数の結果を絞り込みに反映する
戻り値の型をTypeGuard[T]にすると、型チェッカーは関数の結果がTrueの分岐で、1番目の引数の式をT型と判定する。
次の説明用の関数is_str_listの戻り値は、要素がすべてstrの場合にTrueである。
from typing import TypeGuard, assert_type
def is_str_list(values: list[object]) -> TypeGuard[list[str]]:
return all(isinstance(value, str) for value in values)
def show(items: list[object]) -> None:
if is_str_list(items):
assert_type(items, list[str])
print(", ".join(items))
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations
isinstance(items, list[str])は 実行時のTypeError になる。
各要素の確認を関数として定義する場合は、戻り値の型にTypeGuard[list[str]]を指定できる。
TypeGuardでは、このように引数の型の部分型でない型への絞り込みも 許可されている 。
引数の型の部分型への限定を必須にすると、list[object]からlist[str]への絞り込みのような有用な例が不可能になるからである。
ただし、同じリストをlist[object]として保持する別の変数からstr以外の要素を追加すると、list[str]という絞り込みの前提が成立しなくなる。
Falseの分岐では型が限定されない
TypeGuardによる絞り込みは、関数の結果がTrueの分岐に限られる。
from typing import TypeGuard, assert_type
def is_str(value: object) -> TypeGuard[str]:
return isinstance(value, str)
def show(value: int | str) -> None:
if is_str(value):
assert_type(value, str)
else:
assert_type(value, int | str)
print(value + 1)
# mypy
# error: Unsupported operand types for + ("str" and "int") [operator]
# pyright
# error: Operator "+" not supported for types "int | str" and "Literal[1]"
elseの分岐のvalueはint | strのままで、value + 1がエラーになる。
TypeGuard[T]のFalseは「T型でない」という意味ではないので、Falseの分岐からTを除外できない。
PEP 742 は正の整数の場合だけTrueのTypeGuard[int]も適切な用途の例としており、そのFalseの分岐には負の整数も到達する。
TypeIsはFalseの分岐でも型を限定する
この関数の戻り値の型をTypeIs[str]にすると、elseの分岐のvalueはstrを除外したintになる。
from typing import TypeIs, assert_type
def is_str(value: object) -> TypeIs[str]:
return isinstance(value, str)
def show(value: int | str) -> None:
if is_str(value):
assert_type(value, str)
else:
assert_type(value, int)
print(value + 1)
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations
TypeIs[T]の関数の戻り値は、引数がT型の場合にTrue、それ以外の場合にFalseという前提である。
この前提があるので、型チェッカーはFalseの分岐でもisinstanceの規則でTを除外できる。
TypeGuard[T]のTrueの分岐の型はTそのものだが、TypeIs[T]のTrueの分岐では、引数の元の型とTの両方に属する値の型に限定される。
from typing import TypeGuard, TypeIs, assert_type
def is_int_guard(value: object) -> TypeGuard[int]:
return isinstance(value, int)
def is_int(value: object) -> TypeIs[int]:
return isinstance(value, int)
def show(value: bool | str) -> None:
if is_int_guard(value):
assert_type(value, int)
def show_intersection(value: bool | str) -> None:
if is_int(value):
assert_type(value, bool)
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations
bool | str型の値のTypeGuard[int]のTrueの分岐はintで、元の型のboolの情報は判定に反映されない。
元の型を条件付きで保持する案は、Union型などでの規則の複雑化に対して利点が限定的として 不採用になった 。
TypeIs[int]のTrueの分岐は、bool | strの要素のうちintの部分型のboolである。
TypeIsの型引数は引数の型の部分型に限られる
TypeIsの型引数が引数の型の部分型でない場合、関数の定義の行がエラーになる。
from typing import TypeIs
def is_str_list(values: list[object]) -> TypeIs[list[str]]:
return all(isinstance(value, str) for value in values)
# mypy
# error: Narrowed type "list[str]" is not a subtype of input type "list[object]" [narrowed-type-not-subtype]
# pyright
# error: Return type of TypeIs ("list[str]") is not consistent with value parameter type ("list[object]") (reportGeneralTypeIssues)
引数の型をlist[object]のまま要素の型を確認するこの例では、TypeGuardを使用する。
要素の参照のための関数では、引数の型をSequence[object]に変更できる。
Sequence[str]はその部分型なので、TypeIs[Sequence[str]]を指定できる。
Sequenceは要素の追加のメソッドのない読み取り専用の型なので、listと異なり、要素の型の部分型の関係がそのままSequenceの部分型の関係になる。
この性質を 共変 と呼ぶ。
関数の実装と戻り値の型の不一致は検出されない
TypeGuardとTypeIsの関数の中の処理と戻り値の型の意味の一致は、型チェッカーの確認の対象外である。
次のis_nonempty_strの戻り値は空文字列の場合にFalseで、TypeIs[str]の前提に反する。
from typing import TypeIs, assert_type
def is_nonempty_str(value: object) -> TypeIs[str]:
return isinstance(value, str) and value != ""
def read_value() -> int | str:
return ""
value = read_value()
if is_nonempty_str(value):
assert_type(value, str)
else:
assert_type(value, int)
print(value + 1)
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations
# 実行時
# TypeError: can only concatenate str (not "int") to str
型チェッカーはelseの分岐のvalueをintと判定するが、実行時の値は空文字列で、value + 1がTypeErrorで失敗する。
空文字列以外のstrだけをTrueにする条件なら、Falseの分岐を限定しないTypeGuard[str]が適切な指定である。
typingの解説の文書 も、条件と戻り値の型の約束が一致しない関数を型チェッカーは検出できないと説明している。
TypeIs[T]の関数の条件は、T型の値すべてでTrue、それ以外の値でFalseになる条件にし、テストでTrueとFalseの両方の値を確認する。
絞り込みの対象は1番目の引数である
絞り込みの対象は関数の1番目の位置引数の式である。
メソッドではselfの次の引数が対象になり、引数のない関数への指定はエラーになる。
from typing import TypeGuard, TypeIs, assert_type
def f() -> TypeGuard[int]:
return True
class StringChecker:
def is_str(self, value: object) -> TypeIs[str]:
return isinstance(value, str)
def show(value: int | str) -> None:
checker = StringChecker()
if checker.is_str(value):
assert_type(value, str)
# mypy
# error: TypeGuard functions must have a positional argument [valid-type]
# pyright
# error: User-defined type guard functions and methods must have at least one input parameter (reportGeneralTypeIssues)
任意の引数を絞り込みの対象とする案は 不採用になった 。
TypeScriptの開発者も、1番目以外の引数を対象にする実例を認識していなかったからである。
selfを対象にする案も、実装が複雑になる割に用途が少ないとして不採用になった。
TypeGuardとTypeIsの使い分け
PEP 742 は多くの場合にTypeIsの動作のほうが利用者の期待と一致するとして、まずTypeIsの検討を推奨している。
TypeGuardは非推奨ではなく、次の2つの場合はTypeIsではなくTypeGuardで表現する。
| 条件 | 指定 |
|---|---|
引数の型の部分型への限定で、T型の値すべてでTrue |
TypeIs[T] |
引数の型の部分型でない型への限定(list[object]からlist[str]など) |
TypeGuard[T] |
T型の値の一部だけでTrue(正の整数だけなど) |
TypeGuard[T] |
TypeGuardの型引数が引数の型と互換なときだけTypeIsと同じ動作にする案は、PEP 742で不採用になった 。
既存のTypeGuardの関数のelseの分岐の判定に影響が及び、型引数による動作の切り替えも利用者の混乱の原因になるからである。
TypeScriptの type predicate(x is T)は、TypeIsと同様にfalseの分岐でも型を限定する。
TypeGuardは、成立時に限って型の情報を付与するTyped Racketの one-sided propositions に近い。


