本文へスキップ

Pythonの型チェッカーによる型の絞り込みの仕組み

python-type-narrowing

型の絞り込み(type narrowing)とは

型の絞り込み(type narrowing)とは、型チェッカーが代入や条件の判定をもとに、プログラムの位置ごとに変数の型を型注釈の型(declared type)より限定する処理である。
int | str型の変数valueも、if isinstance(value, str):の分岐の中ではstr型と判定される。

  • 絞り込みの仕組みがなければ、int | str型の値に許可される操作はintとstrに共通の操作だけで、isinstanceによる確認の後のvalue.upper()もエラーになる
  • 確認の後の分岐ではその型に固有の操作がエラーにならず、確認なしのvalue.upper()は実行前の型エラーになる
  • 型チェッカーは条件の成立時と不成立時の型を個別に判定し、分岐の合流の後の型を各分岐の型のいずれか(Union型)にする
    • returnやassertの後の行の型も、到達しうる分岐の型だけで決定される
    • ループの先頭には前の周回の末尾の型が合流する
  • 条件として解釈される式と絞り込みの対象の式の範囲は、型チェッカーの組み込みの規則による
    • 戻り値の型がboolの自作の関数や、変数を添字にした式(d[key])は対象外である
    • この規則は型の仕様に規定がなく、mypyとpyrightで判定が異なる
  • 確認の後に呼び出した関数による属性の変更は追跡の対象外で、実行時の値と判定は一致しない場合がある

前提となる用語

Union型とLiteral型

Union型は値が複数の型のいずれかであることの表現で、int | strはintかstrの値の型である。
Literal型は取りうる値そのものの型で、Literal["a"]の値は文字列全体ではなく"a"に限られる。

declared type

declared typeは、変数や引数の型注釈の型である。
def normalize(value: int | str)のvalueのdeclared typeはint | strで、関数の中で代入可能な値の範囲はこの型の範囲である。

型ガード

型ガード(type guard) は、絞り込みの条件として型チェッカーが解釈する式である。
value is None、isinstance(value, str)、type(value) is intなどが該当する。

条件の成立時と不成立時で型が個別に判定される

以降の例の型チェッカーの診断はmypyとpyrightの標準の設定での出力である。

例の typing.assert_type はPython 3.11以降の関数である。
assert_typeは、型チェッカーの判定の結果が第2引数の型と異なる場合をエラーにする関数で、実行時には何もしない。

型ガードの条件が成立する分岐と成立しない分岐では、型チェッカーの判定も異なる。

from typing import assert_type

def check_none(name: str | None) -> None:
    if name is not None:
        assert_type(name, str)
    else:
        assert_type(name, None)

def clean(value: str | None) -> str:
    if value is None:
        return ""
    assert_type(value, str)
    return value.upper()

def shout(value: object) -> str:
    assert isinstance(value, str)
    assert_type(value, str)
    return value.upper()
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations

cleanではNoneの分岐がreturnで終了するので、if文の後に到達する値はstrだけと判定される。
assertの後も同様で、型チェッカーはassertの条件の成立を前提に、後の行の型をstrと判定する。

分岐の合流の後は各分岐の型のUnion型になる

次の図のnormalizeのように、合流の前の分岐ごとの型が同一なら、合流の後もその型になる。

flowchart TD A["value: int | str"] --> B{"isinstance(value, str)"} B -- "成立" --> C["value: str"] C --> D["value = len(value)"] D --> E["value: int"] B -- "不成立" --> F["value: int"] E --> G["合流の後のvalue: int"] F --> G

次のnormalizeは、strの分岐でvalueにintの値を代入するので、合流の前のどちらの分岐でもintになり、合流の後もintである。
maybe_resetでは、片方の分岐でだけNoneを代入するので、合流の後はint | Noneになる。

from typing import assert_type

def normalize(value: int | str) -> int:
    if isinstance(value, str):
        value = len(value)
    assert_type(value, int)
    return value

def maybe_reset(value: int | None, reset: bool) -> int:
    if value is None:
        return 0
    if reset:
        value = None
    return value + 1
# mypy
# error: Unsupported operand types for + ("None" and "int")  [operator]
# pyright
# error: Operator "+" not supported for "None" (reportOptionalOperand)

ループの中の代入も同じ規則で、ループの先頭では前の周回の末尾の型が合流する。
次の例のNodeは、連結リストの要素の説明用のクラスである。

from __future__ import annotations

class Node:
    def __init__(self, following: Node | None = None) -> None:
        self.next = following

def walk(current: Node | None) -> None:
    if current is None:
        return
    for _ in range(2):
        current = current.next
# mypy
# error: Item "None" of "Node | None" has no attribute "next"  [union-attr]
# pyright
# error: "next" is not a known attribute of "None" (reportOptionalMemberAccess)

1周目のcurrentはNodeだが、current.nextの代入でNode | Noneになり、2周目のcurrent.nextがエラーになる。
walk(Node())の実行では、2周目にAttributeErrorで失敗する。

条件として解釈される式

型ガードとして解釈される式の種類は、型チェッカーの組み込みの規則で定義される。
mypyとpyrightの両方で条件として解釈される主な式は次の表のとおりである(mypy、pyright)。

条件の式 成立時の型 不成立時の型
x is None None Noneの除外後の型
isinstance(x, T) T Tの除外後の型
type(x) is int(x: int | str) int int | str
x == "a"(xがLiteral型) Literal["a"] 残りのLiteral
x(真偽の判定) Noneと偽の値の除外後の型 偽になりうる値の型

真偽の判定の不成立時の型には、Noneのほかに空文字列などの偽の値も含まれる。

from typing import Literal, assert_type

def check_truth(name: str | None) -> None:
    if name:
        assert_type(name, str)
    else:
        assert_type(name, Literal[""] | None)
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations

type(x) is intの不成立時にintが除外されない理由は、intのサブクラスのboolの値の場合にも条件が成立しないことである。
isinstance(x, int)と異なり、type(x) is intの不成立は「intの値でない」ことを意味しない。

一方、戻り値の型がboolの自作の関数の呼び出しは、中でisinstanceを実行していても絞り込みの条件にならない。

def is_str(value: object) -> bool:
    return isinstance(value, str)

def shout(value: object) -> None:
    if is_str(value):
        print(value.upper())
# mypy
# error: "object" has no attribute "upper"  [attr-defined]
# pyright
# error: Cannot access attribute "upper" for class "object"

型チェッカーにとって呼び出しの結果は戻り値の型のboolでしかなく、関数の中の処理と引数の型の関係は判定に使用されない。
自作の関数の結果を絞り込みに反映するには、戻り値の型にTypeGuardかTypeIsを指定する。
指定の方法と2つの違いは PythonのTypeGuardとTypeIsの記事 で説明する。

絞り込みの対象の式

絞り込みの対象には変数の名前、属性(self.count)、リテラルを添字にした式(d["k"]、args[0])が含まれる。
変数を添字にした式は対象外で、条件と同一の式でも確認の結果は利用されない。

def literal_key(d: dict[str, int | None]) -> None:
    if d["k"] is not None:
        print(d["k"] + 1)  # ok

def variable_key(d: dict[str, int | None], key: str) -> None:
    if d[key] is not None:
        print(d[key] + 1)
# mypy
# error: Unsupported operand types for + ("None" and "int")  [operator]
# pyright
# error: Operator "+" not supported for "None" (reportOptionalOperand)

この形の添字の式はmypyとpyrightのどちらでも絞り込みの対象外である。
pyrightの絞り込みの対象の添字の式は、整数のリテラルと文字列のリテラルの添字 である。
value = d[key]のようにローカル変数に代入してから確認すると、その変数は絞り込みの対象になる。

mypyとpyrightで判定が異なる場合

型の仕様 は特定の文脈での式の型の絞り込みを型チェッカーに求めているが、その動作の大部分は未規定である。
規定があるのはTypeGuardとTypeIsの2つで、型ガードとして解釈する式の種類や代入の後の型の判定は、型チェッカーごとに異なる。

条件の結果を変数に代入してからif文で判定する書き方では、pyrightだけがその変数を絞り込みの条件として解釈する。

def shout(value: int | str) -> None:
    is_str = isinstance(value, str)
    if is_str:
        print(value.upper())
# mypy
# error: Item "int" of "int | str" has no attribute "upper"  [union-attr]
# pyrightの出力: 0 errors, 0 warnings, 0 informations

pyrightの文書はこの形を Aliased Conditional Expression と呼び、条件の変数と対象の変数がどちらもローカル変数で、代入が1回の場合に限定している。
mypyでも絞り込みの対象にするには、条件の式をif文に直接記述する。

宣言と同時の代入の直後の型の判定も異なる。

x: int | str = 1
print(x + 1)
# mypy
# error: Unsupported operand types for + ("str" and "int")  [operator]
# pyrightの出力: 0 errors, 0 warnings, 0 informations

mypyでは宣言と同時の代入の直後もdeclared typeのint | strと判定され、x + 1はエラーになる。
pyrightは代入の値の型のLiteral[1]と判定し、エラーにしない。
mypyでこの演算をエラーにしないには、宣言と代入を別の行にするか、演算の前にisinstance(x, int)で確認する。

確認の後の関数の呼び出しは追跡の対象外である

次のCounterでは、確認の後のreset()の呼び出しがcountをNoneにする。

class Counter:
    count: int | None = 1

    def reset(self) -> None:
        self.count = None

    def next_count(self) -> int:
        if self.count is not None:
            self.reset()
            return self.count + 1
        return 0
# mypyの出力: Success: no issues found in 1 source file
# pyrightの出力: 0 errors, 0 warnings, 0 informations
# 実行時(Counter().next_count())
# TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'

条件の確立と利用の間に別のコードが条件を無効にする問題は、現在の型チェッカーの検出の対象外 である。
関数の呼び出しのたびに属性の絞り込みを解除すると、確認の直後のメソッドの呼び出しのような通常のコードの多くがエラーになる。
確認の時点の値で処理してよい場合は、PythonのOptionalとNoneチェック で説明したように、属性の値をローカル変数に代入してから確認する。
reset()の後の値が必要な処理では、呼び出しの後に属性を確認し直す。

他の言語の絞り込みとの対応

TypeScriptでは同じ処理を narrowing と呼び、処理の流れに基づく解析をcontrol flow analysisと呼ぶ。
Typed Racketでは occurrence typing と呼ばれる。

言語 名前 自作の述語による絞り込み
Python type narrowing TypeGuard、TypeIs
TypeScript narrowing x is T(type predicate)
Typed Racket occurrence typing 述語の関数の型への、成立時と不成立時の引数の型の情報の付与

この記事に出てくる用語

用語集の一覧へ

関連事例

  • データ分析支援

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

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

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

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

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

お問い合わせ・ご相談

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