本文へスキップ

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

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 に近い。

関連事例

  • データ分析支援

    事例:過去実績を提案に活用する分析の仕組み

    広告代理店との取り組みです。同社は過去実績の示唆を次の提案へ反映し、結果をどのように予測したか、その背景まで提案先のクライアントへ説明できるようになりました。KDOT は案ごとの見込みと判断材料を比較できる仕組みを業務アプリとして実装しました。さらに業務アプリの中核となる処理ロジックと機械学習モデルについて、特許手続きを担う弁理士が技術の新規性や工夫を検討するための資料を作成しました。その後この発明には特許が付与されました。

  • データ基盤構築 / 技術顧問(技術企業向け)

    事例:効果検証の分析処理基盤

    効果検証を提供する分析会社との取り組みです。同社は分析者の人数に比例してしか売上と利益を伸ばせない事業の形を、効果検証をプロダクトとして提供することで変革しようとしていました。手法とモデルは同社のまま、社内では開発できなかった、データと機械学習の重い推定を製品として動かす仕組みの開発を、開発支援会社の KDOT に任せました。推定を案件ごとの手作業ではなくシステムで実行できるようになったことで、同社は人数に比例しない形で売上と利益を伸ばすことを目指せるようになりました。

お問い合わせ・ご相談

システム開発、データ活用、プロダクトづくりのことならお気軽にご相談ください。要件が固まる前の整理や、お見積もりだけのご依頼も承ります。