# 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）](https://peps.python.org/pep-0647/#motivation) は、絞り込みの条件として型チェッカーが解釈する式である。
`value is None`、`isinstance(value, str)`、`type(value) is int`などが該当する。

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

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

例の [`typing.assert_type`](https://docs.python.org/3/library/typing.html#typing.assert_type) はPython 3.11以降の関数である。
`assert_type`は、型チェッカーの判定の結果が第2引数の型と異なる場合をエラーにする関数で、実行時には何もしない。

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

```python
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`のように、合流の前の分岐ごとの型が同一なら、合流の後もその型になる。

```mermaid
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`になる。

```python
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`は、連結リストの要素の説明用のクラスである。

```python
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](https://mypy.readthedocs.io/en/stable/type_narrowing.html)、[pyright](https://github.com/microsoft/pyright/blob/main/docs/type-concepts-advanced.md#type-guards)）。

| 条件の式 | 成立時の型 | 不成立時の型 |
|---|---|---|
| `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`のほかに空文字列などの偽の値も含まれる。

```python
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`を実行していても絞り込みの条件にならない。

```python
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の記事](https://kdot.co.jp/kdotdev/python-typeguard-typeis) で説明する。

## 絞り込みの対象の式

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

```python
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の絞り込みの対象の添字の式は、[整数のリテラルと文字列のリテラルの添字](https://github.com/microsoft/pyright/blob/main/docs/type-concepts-advanced.md#type-guards) である。
`value = d[key]`のようにローカル変数に代入してから確認すると、その変数は絞り込みの対象になる。

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

[型の仕様](https://typing.python.org/en/latest/spec/narrowing.html) は特定の文脈での式の型の絞り込みを型チェッカーに求めているが、その動作の大部分は未規定である。
規定があるのは`TypeGuard`と`TypeIs`の2つで、型ガードとして解釈する式の種類や代入の後の型の判定は、型チェッカーごとに異なる。

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

```python
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](https://github.com/microsoft/pyright/blob/main/docs/type-concepts-advanced.md#aliased-conditional-expression) と呼び、条件の変数と対象の変数がどちらもローカル変数で、代入が1回の場合に限定している。
mypyでも絞り込みの対象にするには、条件の式を`if`文に直接記述する。

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

```python
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`にする。

```python
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'
```

条件の確立と利用の間に別のコードが条件を無効にする問題は、[現在の型チェッカーの検出の対象外](https://typing.python.org/en/latest/guides/type_narrowing.html#invalidated-assumptions) である。
関数の呼び出しのたびに属性の絞り込みを解除すると、確認の直後のメソッドの呼び出しのような通常のコードの多くがエラーになる。
確認の時点の値で処理してよい場合は、[PythonのOptionalとNoneチェック](https://kdot.co.jp/kdotdev/python-optional-none) で説明したように、属性の値をローカル変数に代入してから確認する。
`reset()`の後の値が必要な処理では、呼び出しの後に属性を確認し直す。

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

TypeScriptでは同じ処理を [narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html) と呼び、処理の流れに基づく解析をcontrol flow analysisと呼ぶ。
Typed Racketでは [occurrence typing](https://docs.racket-lang.org/ts-guide/occurrence-typing.html) と呼ばれる。

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