# PythonのOptionalとNoneチェック

## Optionalとは

PythonのOptionalとは、ある型の値か`None`のどちらかになる値の型である。
`Optional[str]`は`str | None`の略記で、2つは同一の型である。

- 戻り値を`str`と宣言すると、呼び出し側では`None`を確認しない利用が型エラーにならず、実行時の`AttributeError`で初めて発覚する
- 型を`str | None`と宣言すると、`None`を確認せずに`str`のメソッドを呼び出す行は、mypyとpyrightによる実行前の型チェックでエラーになる
  - `if email is None: return`の後や`assert email is not None`の後では、型チェッカーが`email`を`str`型と判定する
  - `if value:`による確認も型の上ではエラーにならないが、`0`や空文字列も`None`と同じ分岐の対象になる
- `Optional`は値の型の指定で、引数を省略可能にする指定ではない
  - 省略可能な引数にはデフォルト値の指定が必要である
  - デフォルト値が`None`なら型にも`| None`が必要である
- 属性を`None`でないと確認した後に、その属性を変更するメソッドを呼び出しても、mypyとpyrightは確認の結果を維持する
  - 属性の値が実行時に`None`になって`AttributeError`で失敗するコードが、型エラーにならない
  - 対処は確認の前に属性の値をローカル変数に代入し、その変数を確認して利用する方法である

## 前提となる用語

### Union型

Union型は、値が複数の型のうちのいずれかであることの型での表現である。
`int | str`型の変数には`int`の値と`str`の値のどちらも代入できる。
`str | None`は`str`と`None`のUnion型で、`None`の値の型の表記は`None`である。

### 型の絞り込み

型の絞り込み（type narrowing）とは、`if`文などの条件をもとに、型チェッカーが分岐の中での変数の型の範囲を宣言より限定する処理である。
`str | None`型の`email`は、`if email is None: return`の後では`str`型と判定される。
`x is None`の形の条件では、成立する分岐の型は`None`、成立しない分岐の型は残りの型に [限定される](https://typing.python.org/en/latest/spec/narrowing.html) 。

## 戻り値の型がstrならNoneの戻り値がエラーになる

以降の例は名前からメールアドレスを検索する関数で説明する。
例の`typing.assert_type`はPython 3.11以降の関数で、診断はmypyとpyrightの標準の設定での出力である。
mypyの`--no-strict-optional`やpyrightの`typeCheckingMode: "off"`の設定では、以降の`None`に関するエラーは発生しない。
辞書の`get()`の戻り値はキーがなければ`None`なので、戻り値の型が`str`の関数はエラーになる。

```python
users: dict[str, str] = {"alice": "alice@example.com"}

def find_email(name: str) -> str:
    return users.get(name)
# mypy
# error: Incompatible return value type (got "str | None", expected "str")  [return-value]
# pyright
# error: Type "str | None" is not assignable to return type "str"
#   Type "str | None" is not assignable to type "str"
#     "None" is not assignable to "str" (reportReturnType)
```

型の確認は実行時には行われず、`find_email("bob")`の結果は`None`で、エラーにならない。
この関数の定義のエラーを無視すると、呼び出し側は`str`の宣言を前提に判定され、`None`の確認のない利用も型エラーにならない。

## str | None型のままではstrのメソッドの呼び出しがエラーになる

戻り値の型を`str | None`にすると、関数の定義はエラーにならない。
代わりに、呼び出し側で`None`の確認をせずに`str`のメソッドを呼び出す行がエラーになる。

```python
def find_email(name: str) -> str | None:
    return users.get(name)

print(find_email("bob").upper())
# mypy
# error: Item "None" of "str | None" has no attribute "upper"  [union-attr]
# pyright
# error: "upper" is not a known attribute of "None" (reportOptionalMemberAccess)
# 実行時
# AttributeError: 'NoneType' object has no attribute 'upper'
```

戻り値の型が`str`の関数では、この`AttributeError`は辞書に存在しない名前（`bob`など）で呼び出したときに初めて発生する。
`str | None`にすると、引数の値に関係なく、型チェックの時点でこの行がエラーになる。

`None`の確認を追加すると、エラーにならない。

```python
from typing import assert_type

def show(name: str) -> str:
    email = find_email(name)
    if email is None:
        return "unknown"
    assert_type(email, str)
    return email.upper()

print(show("bob"))    # unknown
print(show("alice"))  # ALICE@EXAMPLE.COM
```

`assert_type`は、型チェッカーの判定の結果と第2引数の型の不一致をエラーにする関数で、実行時には何もしない。

`None`になりえない箇所なら、`assert email is not None`でも`email`は`str`型と判定される。
`assert`は条件が不成立なら実行時に`AssertionError`を発生させ、`None`のままの処理の継続を防止する。
`python -O`で起動すると、`assert`文は実行されない。

## Noneの確認はif email:ではなくis Noneで記述する

`if count:`による確認でも、型チェッカーは分岐の中の`count`の型から`None`を除外する。
しかし`if count:`は`0`や空文字列でも不成立で、`None`以外の値も`else`の側の処理になる。

```python
def show(count: int | None) -> str:
    if count:
        return f"{count}件"
    return "不明"

def show_not_none(count: int | None) -> str:
    if count is not None:
        return f"{count}件"
    return "不明"

print(show(0))           # 不明
print(show_not_none(0))  # 0件
```

2つの関数はどちらもmypyとpyrightでエラーにならないが、`show(0)`は`不明`、`show_not_none(0)`は`0件`になる。
型チェッカーは`0`が`else`の側の処理になることを指摘しない。
`int`や`str`には偽と判定される値（`0`や`""`）があるので、`None`の確認を`is None`か`is not None`で記述する。

## Optional[X]とX | Noneは同一の型である

`Optional[X]`は`Union[X, None]`の [略記](https://peps.python.org/pep-0484/#union-types) である。
Python 3.10で [PEP 604](https://peps.python.org/pep-0604/) の`X | Y`の構文が追加され、`X | None`の表記も可能になった。
型チェッカーは3つの表記を [同一の型として処理する](https://typing.python.org/en/latest/spec/historical.html#union-and-optional) 。

```python
from typing import Optional, Union, assert_type

def f(value: Optional[int]) -> None:
    assert_type(value, int | None)  # ok

print(Optional[int] == int | None, Union[int, None] == int | None)  # True True
```

`Optional`と`Union`は、`|`の構文の追加以前からの表記として、型の仕様の「Historical and deprecated features」の章に分類されている。
Python 3.10以降を対象にしたコードでは、`X | None`の表記なら`typing`の`import`も不要である。

`Optional`を入れ子にしても型は`Optional[int]`と同一で、「値がない」と「値がないことを表す値がある」を型では区別できない。

```python
def g(value: Optional[Optional[int]]) -> None:
    assert_type(value, int | None)  # ok

print(Optional[Optional[int]] == Optional[int])  # True
```

## Optionalの引数も省略は不可能である

名前の`Optional`は省略可能を連想させるが、デフォルト値のない`Optional[str]`型の引数は省略するとエラーになる。

```python
def greet(name: Optional[str]) -> str:
    return f"Hello, {name}"

print(greet())
# mypy
# error: Missing positional argument "name" in call to "greet"  [call-arg]
# pyright
# error: Argument missing for parameter "name" (reportCallIssue)
# 実行時
# TypeError: greet() missing 1 required positional argument: 'name'
```

逆に、デフォルト値が`None`の引数の型が`str`なら、デフォルト値と型が一致せずエラーになる。

```python
def greet(name: str = None) -> str:
    return f"Hello, {name}"
# mypy
# error: Incompatible default for parameter "name" (default has type "None", parameter has type "str")  [assignment]
# pyright
# error: Expression of type "None" cannot be assigned to parameter of type "str"
#   "None" is not assignable to "str" (reportArgumentType)
```

省略可能で`None`も許可する引数には、型とデフォルト値の両方を指定する。

```python
def greet(name: str | None = None) -> str:
    return f"Hello, {name}"

print(greet())     # Hello, None
print(greet("a"))  # Hello, a
```

PEP 484の以前のバージョンは、デフォルト値が`None`の引数の型を暗黙に`Optional`とみなすことを型チェッカーに許可していた。
現在のPEP 484と型の仕様は、この扱いを推奨せず、型への`None`の明記を求める方向を型チェッカーに示している。
[mypyは0.991から](https://mypy-lang.blogspot.com/2022/11/mypy-0990-released.html) この暗黙の`Optional`を標準の設定で無効にし、`--implicit-optional`の指定がある場合だけ許可する。
mypy 0.990より前や`--implicit-optional`の設定では、`name: str = None`はエラーにならない。

## Noneの確認の後の判定が実行時と一致しない場合

メソッドの呼び出しによる属性の変更は型の絞り込みの追跡の対象外で、判定の結果が実行時の値と一致しないことがある。
次の説明用のクラス`Session`では、`logout()`が属性`user`を`None`にする。

```python
class Session:
    def __init__(self) -> None:
        self.user: str | None = "alice"

    def logout(self) -> None:
        self.user = None

s = Session()
if s.user is not None:
    s.logout()
    print(s.user.upper())
# mypy: Success: no issues found in 1 source file
# pyright: 0 errors, 0 warnings, 0 informations
# 実行時
# AttributeError: 'NoneType' object has no attribute 'upper'
```

型チェッカーは`s.logout()`の後も`s.user`を`str`型と判定し、mypyとpyrightのどちらもエラーにしない。
この例のように、確認の後に呼び出した処理が条件を無効にする問題は、 [現在の型チェッカーでは検出できない](https://typing.python.org/en/latest/guides/type_narrowing.html#invalidated-assumptions) 。

確認の時点の値で処理してよい場合は、属性の値をローカル変数に代入してから確認する。

```python
s = Session()
user = s.user
if user is not None:
    s.logout()
    print(user.upper())  # ALICE
    print(s.user)        # None
```

`logout()`はローカル変数の`user`を変更しないので、型チェッカーの判定と実行時の値が一致する。
`user`は確認の時点の値で、`logout()`の後の属性の現在の値ではない。

内側の関数から外側の変数を参照する場合も、確認の結果が維持されるかは、外側の変数への後からの代入の有無で異なる。

```python
def run(email: str | None) -> None:
    if email is None:
        return

    def inner() -> str:
        return email.upper()  # ok

    print(inner())

def run_reassigned(email: str | None) -> None:
    if email is None:
        return

    def inner() -> str:
        return email.upper()
    # mypy
    # error: Item "None" of "str | None" has no attribute "upper"  [union-attr]
    # pyright
    # error: "upper" is not a known attribute of "None" (reportOptionalMemberAccess)

    email = None
    print(inner())
```

`inner`の定義の後に`email`への代入がなければ、mypy 1.4以降とpyrightは`inner`の中でも`email`を`str`型と判定する。
代入があれば`inner`の呼び出しの時点での値が不明なので、宣言の`str | None`の判定になる。

## Noneの値とキーの欠如を区別する

`None`自体が有効な値の場合、`None`を値の欠如の表現に利用すると、2つの状態の区別が不可能になる。
値の型が`int | None`の辞書では、値が`None`のキーと、存在しないキーの`get()`の結果がどちらも`None`である。

```python
settings: dict[str, int | None] = {"timeout": None}
print(settings.get("timeout"), settings.get("retries"))  # None None
print("timeout" in settings, "retries" in settings)      # True False
```

`get()`のデフォルト値に専用の値（番兵）を指定すると、実行時には区別できる。
`object()`を番兵にした場合、実行時には区別できても、`is`による比較の後に`value`の型は`int | None`に限定されない。

```python
from typing import assert_type

_MISSING = object()

def show(key: str) -> None:
    value = settings.get(key, _MISSING)
    if value is _MISSING:
        print(key, "missing")
    else:
        assert_type(value, int | None)
# mypy
# error: Expression is of type "object", not "int | None"  [assert-type]
# pyright
# error: "assert_type" mismatch: expected "int | None" but received "int | object | None" (reportAssertTypeFailure)
```

`object()`の値の型は`object`で、`is`による比較では`object`型を除外できないからである。
[PEP 484](https://peps.python.org/pep-0484/#support-for-singleton-types-in-unions) はこの用途の番兵に要素が1つの`Enum`を利用する方法を示している。
`Enum`の要素は、値が1つだけの型として判定され、`is`による比較で除外の対象になる。

```python
from enum import Enum
from typing import Final, assert_type

class Missing(Enum):
    TOKEN = 0

MISSING: Final = Missing.TOKEN

def show(key: str) -> None:
    value = settings.get(key, MISSING)
    if value is MISSING:
        print(key, "missing")
    else:
        assert_type(value, int | None)  # ok
        print(key, value)

show("timeout")  # timeout None
show("retries")  # retries missing
```

## 他の言語の値の欠如の型との違い

| 言語 | 値の欠如の型 | 入れ子の場合 |
|---|---|---|
| Python | `int \| None`（Union型） | `Optional[int]`と同一 |
| Haskell | `Maybe Int`（`Just 1`か`Nothing`） | `Maybe (Maybe Int)`は別の型 |
| Scala | `Option[Int]`（`Some(1)`か`None`） | `Option[Option[Int]]`は別の型 |
| Kotlin | `Int?`（null許容型） | `Int?`と同一 |

HaskellのMaybeとScalaのOptionの値は、`Just`や`Some`の構築子の中に元の値がある構造である。
構築子の有無で、`Nothing`と`Just Nothing`のように値の欠如と、欠如を表現する値の存在を区別できる。
Pythonの`Optional`は構築子のないUnion型なので、前の節の辞書のように区別が必要な場合は番兵を別に用意する。
その代わりに、`str | None`型の引数には`str`の値をそのまま指定でき、値の取り出しの記述も不要である。
