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

型の絞り込み(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のように、合流の前の分岐ごとの型が同一なら、合流の後もその型になる。
次の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 | 述語の関数の型への、成立時と不成立時の引数の型の情報の付与 |


