# PythonのTypeVarの変性の指定とPEP 695の推論

## TypeVarの変性の指定とは

PythonのTypeVarの変性の指定とは、型変数の定義での`covariant=True`か`contravariant=True`の指定である。
この指定で、ジェネリックなクラスの間の部分型の関係を型チェッカーに通知する。
Python 3.12の型パラメータの構文（`class Box[T]:`）には指定の手段がなく、型チェッカーがクラス内での型変数の用途から変性を推論する。

- 無指定の`TypeVar`は不変で、値の取得だけのクラスでも、引数の型が`Box[Animal]`の関数に`Box[Dog]`の値を指定した呼び出しが、実行時には失敗しないのに型エラーになる
- 共変と反変の指定で、型引数が異なる値も、クラスの用途に対応した向きなら引数として有効になる
  - 共変の`Box[Dog]`は`Box[Animal]`型の引数として有効になる
  - 反変の`Handler[Animal]`は`Handler[Dog]`型の引数として有効になり、`Animal`用の処理を`Dog`用の処理として再利用できる
- 型変数の直接の用途がメソッドの戻り値の型に限られるクラスは共変（`covariant=True`）、引数の型に限られるクラスは反変を指定できる
  - コンストラクタ（`__init__`）の引数は判定の対象外である
  - 指定とメソッドでの用途の矛盾は、mypyとpyrightが定義の時点でエラーにする
- 型パラメータの構文では型チェッカーがメソッドと属性での用途から共変・反変・不変を推論する
  - `covariant=True`などの明示の指定と、`_co`などの型変数の定義が不要になる
  - 型変数を型にした公開の属性は、書き込み可能なら推論の結果を不変にする
  - 従来の構文の共変の指定では検出されない書き込み可能な属性も、推論では不変の原因になり、`Box[Animal]`型の引数への`Box[Dog]`の指定が型エラーになる
  - 引数や戻り値が`list[T]`なら、`list`の変性も推論の結果に影響する
- 変性の指定の誤りの一部は型チェッカーで検出されず、実行時にも確認されない

## 前提となる変性の用語

### 型変数と型引数

`class Box(Generic[T])`の`T`は型変数で、`Box`の定義の中で後から`Dog`などのクラスに置換される。
`Box[Dog]`の`Dog`は型引数で、`T`の置換先である。
変性の指定の場所は型変数の定義で、その効果は`Box[Dog]`と`Box[Animal]`の互換性に反映される。

### 部分型

型Aの値を型Bの値の代わりに使用できるとき、AをBの部分型と呼ぶ。
以降の例では説明用に定義した`Animal`と、そのサブクラスの`Dog`を使用し、`Dog`は`Animal`の部分型である。

### 変性

変性とは型引数の部分型の関係とジェネリックなクラスの部分型の関係の対応である。
`Dog`が`Animal`の部分型の場合の変性は、`Box[Dog]`と`Box[Animal]`の関係で3つに分類できる。
`Box[Dog]`が`Box[Animal]`の部分型である関係は共変、逆向きの関係は反変、どちらの関係もない場合は不変である。
概念の詳細と、listが不変である理由は [Pythonの型ヒントと共変・反変・不変](https://kdot.co.jp/kdotdev/python-covariance-contravariance-variance) で説明した。

## 無指定のTypeVarは不変になる

値の取得用のメソッドしかないクラスを、無指定の`TypeVar`で定義する。

```python
from typing import Generic, TypeVar

class Animal:
    pass

class Dog(Animal):
    def bark(self) -> str:
        return "woof"

T = TypeVar("T")

class Box(Generic[T]):
    def __init__(self, value: T) -> None:
        self._value = value

    def get(self) -> T:
        return self._value

def accept(box: Box[Animal]) -> None:
    print(type(box.get()).__name__)

accept(Box[Dog](Dog()))
# mypy
# error: Argument 1 to "accept" has incompatible type "Box[Dog]"; expected "Box[Animal]"  [arg-type]
# pyright
# error: Argument of type "Box[Dog]" cannot be assigned to parameter "box" of type "Box[Animal]" in function "accept"
#   "Box[Dog]" is not assignable to "Box[Animal]"
#     Type parameter "T@Box" is invariant, but "Dog" is not the same as "Animal" (reportArgumentType)
```

実行時は`Dog`が表示され、正常に終了する。
`accept`の処理は`get()`による値の取得なので、`Box[Dog]`を引数にしても失敗しない。
それでもエラーになる理由は、従来の`TypeVar`で宣言したジェネリックなクラスを [型の仕様](https://typing.python.org/en/latest/spec/generics.html#variance) がすべての型変数について不変と定義していることである。

## 戻り値の型専用の型変数はcovariantにする

この節以降の判定の対象はメソッドの引数と戻り値に型変数を直接使うクラスである。
`__init__`の引数は生成済みのオブジェクトへの値の書き込みではないので、判定の対象外になる。
上の`Box`の生成後の操作は`get()`による値の取得に限られるので、型変数を`covariant=True`で宣言できる。
`Box`と`accept`を次のように置換すると、`Box[Dog]`を`Box[Animal]`型の引数にしてもエラーにならない。

```python
T_co = TypeVar("T_co", covariant=True)

class Box(Generic[T_co]):
    def __init__(self, value: T_co) -> None:
        self._value = value

    def get(self) -> T_co:
        return self._value

def accept(box: Box[Animal]) -> None:
    print(type(box.get()).__name__)

accept(Box[Dog](Dog()))  # ok
```

この指定で、引数の型を`Box[Animal]`にした関数1つを、`Box[Dog]`の値にもそのまま適用できる。
無指定の場合の回避の手段は、呼び出し側でのエラーを無視する記述（`# type: ignore`）や、引数の型に型変数を指定した関数の定義などである。

型の仕様は共変の型変数の名前の末尾を`_co`、反変の型変数の名前の末尾を`_contra`にする慣例を推奨している。

標準ライブラリでは`Sequence`の要素型や`Mapping`の値型が共変、書き換えのメソッドがある`list`の要素型が不変である。

### 共変の型変数を引数にした定義はエラーになる

共変の型変数をメソッドの引数の型にすると、定義の時点でエラーになる。

```python
class Box(Generic[T_co]):
    def set(self, value: T_co) -> None: ...
# mypy
# error: Cannot use a covariant type variable as a parameter  [misc]
# pyright
# error: Covariant type variable cannot be used in parameter type (reportGeneralTypeIssues)
```

`Box[Dog]`を`Box[Animal]`と同一視すると、`set(Animal())`で`Dog`の箱に`Animal`が格納されるからである。

### 共変の型変数を書き込み可能な属性の型にした誤りは検出されない

共変の型変数を書き込み可能なインスタンス属性の型にした定義は、mypyとpyrightのどちらでもエラーにならない。

```python
class Box(Generic[T_co]):
    def __init__(self, value: T_co) -> None:
        self.value: T_co = value

def replace(box: Box[Animal]) -> None:
    box.value = Animal()

dogs = Box[Dog](Dog())
replace(dogs)
print(dogs.value.bark())
# mypy: Success: no issues found in 1 source file
# pyright: 0 errors, 0 warnings, 0 informations
# 実行時
# AttributeError: 'Animal' object has no attribute 'bark'
```

型チェックはエラーにならず、実行時は`AttributeError`で異常終了する。
型チェッカーは`covariant=True`を指定したクラスの公開の属性への代入をエラーにしない。
したがって共変のクラスには、外部から代入できる公開の属性を定義しない。

## 引数の型専用の型変数はcontravariantにする

型変数の用途がメソッドの引数の型に限られるクラスには、反変を指定できる。
次の`Handler`は値の処理を行い、戻り値の型に型変数を使用しない。

```python
T_contra = TypeVar("T_contra", contravariant=True)

class Handler(Generic[T_contra]):
    def handle(self, x: T_contra) -> None:
        print(type(x).__name__)

def handle_dog(handler: Handler[Dog]) -> None:
    handler.handle(Dog())

def handle_animal(handler: Handler[Animal]) -> None:
    handler.handle(Animal())

handle_dog(Handler[Animal]())  # ok
handle_animal(Handler[Dog]())
# mypy
# error: Argument 1 to "handle_animal" has incompatible type "Handler[Dog]"; expected "Handler[Animal]"  [arg-type]
```

`Animal`の処理が可能な`Handler[Animal]`は`Dog`も処理できるので、`Handler[Dog]`型の引数として妥当である。
`Handler[Dog]`は`Dog`のメソッドを前提にした実装が可能なので、`Animal`を処理する関数の引数にはならない。
標準ライブラリでは`Callable`の引数が同じ関係で、引数の型が`Animal`の関数は`Callable[[Dog], None]`型の引数として有効である。

反変の型変数を戻り値の型にした定義もエラーになる。

```python
class Handler(Generic[T_contra]):
    def get(self) -> T_contra: ...
# mypy
# error: Cannot use a contravariant type variable as return type  [misc]
# pyright
# error: Contravariant type variable cannot be used in return type (reportGeneralTypeIssues)
```

型変数の用途が引数と戻り値の両方なら、無指定のまま不変にする。

### Protocolでは指定と使い方の不一致が指摘される

[Protocol](https://kdot.co.jp/kdotdev/python-protocol-structural-subtyping) は継承関係ではなく、メソッドや属性などのメンバーの型で適合を判定するクラスである。
ジェネリックなProtocolでは、型チェッカーが型変数の使い方から変性を計算し、指定との不一致を指摘する。
戻り値の型専用の型変数が不変のままなら、mypyはエラー、pyrightは標準の設定で警告である。

```python
from typing import Protocol

class Producer(Protocol[T]):
    def get(self) -> T: ...
# mypy
# error: Invariant type variable "T" used in protocol where covariant one is expected  [misc]
# pyright
# warning: Type variable "T" used in generic Protocol "Producer" should be covariant (reportInvalidTypeVarUse)
```

`Protocol`を継承しない通常のクラスの定義なら、型変数が不変のままでも指摘されない。
通常のクラスの部分型の関係は継承の宣言で定義され、変性の指定もその宣言の一部である。
値の取得だけのクラスを不変のままにすると、安全な代入の一部もエラーになるが、危険な代入がエラーにならない状態は生じない。

Protocolへの適合は、継承の宣言ではなくメンバーの型で判定される。
[PEP 544](https://peps.python.org/pep-0544/#overriding-inferred-variance-of-protocol-classes) はProtocolの不変の宣言を有効にする案の不採用の理由を、次の例で説明している。

```python
class C:
    def get(self) -> float: ...

class D(C):
    def get(self) -> int: ...

c: Producer[float] = C()
d: Producer[float] = D()
```

`D`は`C`のサブクラスで、`C`は`Producer[float]`に適合する。
`D`の`get()`の戻り値の型は`int`なので、`get()`の型で判定すると`D`は`Producer[int]`に適合する。
仮に`Producer`の不変の宣言が有効なら、`D`は`C`の部分型なのに`Producer[float]`に適合しないことになる。
これは部分型の関係の推移性（AがBの部分型で、BがCの部分型なら、AはCの部分型）への違反である。
PEP 544はこの理由で変性の宣言による上書きを認めず、宣言と使い方の不一致を型チェッカーが指摘する仕様にした。
上の例の`D()`の代入がエラーにならないのは、`D`がProtocolではないクラスで、`get()`の型と`Producer[float]`の`get()`の型が直接比較されるからである。
`Producer[int]`型の変数を`Producer[float]`型の引数にすると、mypyは`Producer`の宣言どおりの不変に従ってエラーにする。
pyrightはこの呼び出しをエラーにしない。

```python
def use(p: Producer[float]) -> None: ...

p: Producer[int] = D()
use(p)
# mypy
# error: Argument 1 to "use" has incompatible type "Producer[int]"; expected "Producer[float]"  [arg-type]
# pyright: 0 errors（定義の行の警告だけ）
```

## PEP 695の型パラメータ構文は変性を推論する

Python 3.12で追加された [PEP 695](https://peps.python.org/pep-0695/) の構文には、型パラメータの変性の指定がない。
代わりに [型の仕様のVariance Inference](https://typing.python.org/en/latest/spec/generics.html#variance-inference) が、使い方からの推論を型チェッカーに要求している。
型チェッカーは従来からProtocolの変性の検証に適用していた計算を、この構文ではProtocol以外のクラスにも適用する。
[mypyは1.12から](https://github.com/python/mypy/blob/master/CHANGELOG.md#mypy-112) 、この構文に標準で対応している。

```python
class Box[T]:
    def __init__(self, value: T) -> None:
        self._value = value

    def get(self) -> T:
        return self._value

def accept(box: Box[Animal]) -> None:
    print(type(box.get()).__name__)

accept(Box[Dog](Dog()))  # ok
```

生成後のメソッドでの`T`の使い方は戻り値に限られるので共変と推論され、`covariant=True`の指定と同じくエラーにならない。
推論の手順では`T`を`object`に置換した`Box[object]`と、`T`のままの`Box[T]`の代入可能性を比較する。
比較の結果と変性の対応は次のとおりである。

| 可能な代入 | 変性 |
|---|---|
| `Box[T]`から`Box[object]`への代入だけ | 共変 |
| `Box[object]`から`Box[T]`への代入だけ | 反変 |
| どちらも不可能 | 不変 |

```mermaid
flowchart TD
  start["Tを直接使うメンバー"] --> q0{"公開の書き込み可能な属性の型がT"}
  q0 -->|"はい"| inv["不変"]
  q0 -->|"いいえ"| q1{"メソッドの引数の型がT"}
  q1 -->|"いいえ"| co["共変"]
  q1 -->|"はい"| q2{"戻り値か読み取り専用の属性の型がT"}
  q2 -->|"いいえ"| contra["反変"]
  q2 -->|"はい"| inv
```

図は`__init__`以外のメンバーが`T`を直接使うクラスについて、推論の結果を整理したものである。
型チェッカーの実際の処理は上の代入可能性の比較である。
メンバーの種類ごとの推論の結果は次の表のとおりである。

| クラスのメンバー | 推論の結果 |
|---|---|
| `get(self) -> T` だけ | 共変 |
| setterのないプロパティ `value -> T` だけ | 共変 |
| `Final[T]` の属性だけ | 共変 |
| `handle(self, x: T)` だけ | 反変 |
| `get(self) -> T` と `set(self, value: T)` | 不変 |
| 公開の属性 `value: T` | 不変 |
| 非公開名の属性 `_value: T` と `get()` だけ | 共変 |

`set()`を追加すると、`accept(Box[Dog](Dog()))`の行は従来の構文の不変と同じエラーで拒否される。

```python
class Box[T]:
    def __init__(self, value: T) -> None:
        self._value = value

    def get(self) -> T:
        return self._value

    def set(self, value: T) -> None:
        self._value = value

accept(Box[Dog](Dog()))
# pyright
# error: Argument of type "Box[Dog]" cannot be assigned to parameter "box" of type "Box[Animal]" in function "accept"
#   "Box[Dog]" is not assignable to "Box[Animal]"
#     Type parameter "T@Box" is invariant, but "Dog" is not the same as "Animal" (reportArgumentType)
```

従来の構文の共変の指定で検出されなかった書き込み可能な属性も、推論の対象になる。
`self.value: T`のあるクラスは不変と推論され、同じ`accept`の呼び出しがエラーになる。
`_value`のように名前の先頭が`_`の属性は、型が`T`であっても推論の結果を不変にしない。
その属性を更新するメソッドが引数の型に`T`を使用すると、推論の結果は不変になる。

### 引数や戻り値が`list[T]`や`Callable`の場合

`list[T]`や`Callable[[T], None]`が引数や戻り値の型の場合、変性は型変数の位置と外側の型の変性の両方に依存する。
戻り値が`list[T]`のメソッドしかないクラスは、`list`が不変なので不変になる。
引数が`Callable[[T], None]`のメソッドしかないクラスは、`Callable`の引数が反変なので向きが反転し、共変になる。

```python
from collections.abc import Callable

class Producer[T]:
    def get(self) -> list[T]: ...

class Consumer[T]:
    def handle(self, callback: Callable[[T], None]) -> None: ...

def accept_producer(p: Producer[Animal]) -> None: ...
def accept_consumer(c: Consumer[Animal]) -> None: ...

accept_producer(Producer[Dog]())
# mypy
# error: Argument 1 to "accept_producer" has incompatible type "Producer[Dog]"; expected "Producer[Animal]"  [arg-type]
accept_consumer(Consumer[Dog]())  # ok
```

従来の構文で`covariant=True`などを指定する場合も、判断には外側の型の変性も必要である。


### 凍結したdataclassの推論は型チェッカーで一致しない

`@dataclass(frozen=True)`のフィールドで構成されるクラスでは、推論の結果は型チェッカーと、型チェッカーに指定する解析対象のPythonのバージョンに依存する。
解析対象のバージョンは`mypy --python-version 3.13`、`pyright --pythonversion 3.13`のように指定する。

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class Box[T]:
    value: T

def accept(box: Box[Animal]) -> None:
    print(type(box.value).__name__)

accept(Box[Dog](Dog()))
# Python 3.13以降を対象にした pyright
# error: Argument of type "Box[Dog]" cannot be assigned to parameter "box" of type "Box[Animal]" in function "accept"
#   "Box[Dog]" is not assignable to "Box[Animal]"
#     Type parameter "T@Box" is invariant, but "Dog" is not the same as "Animal" (reportArgumentType)
```

Python 3.13から、dataclassの`copy.replace()`用の`__replace__`メソッドが生成され、そのキーワード引数の型は`T`である。
[pyrightは1.1.373から](https://github.com/microsoft/pyright/releases/tag/1.1.373) この引数を推論に含めるので、結果は不変である。
[mypyは2.3で](https://github.com/python/mypy/blob/master/CHANGELOG.md) この引数を推論から除外し、共変と判定するようになった。
解析対象がPython 3.12なら`__replace__`が生成されないので、両方とも共変になる。
型チェッカーに依存せず共変にするには、従来の構文で型変数を共変に指定する。
次の定義はmypyとpyrightの両方でエラーにならない。

```python
T_co = TypeVar("T_co", covariant=True)

@dataclass(frozen=True)
class Box(Generic[T_co]):
    value: T_co

accept(Box[Dog](Dog()))  # ok
```

## 従来のTypeVarと型パラメータの構文は併用できない

型パラメータの構文のクラスで、従来の`TypeVar`をクラスの型パラメータとして参照すると、両方の型チェッカーがエラーにし、実行時も`TypeError`になる。

```python
K = TypeVar("K")

class Table[V](dict[K, V]):
    pass
# mypy
# error: All type parameters should be declared ("K" not declared)  [valid-type]
# pyright
# error: Type parameter "K" is not included in the type parameter list for "Table" (reportGeneralTypeIssues)
# 実行時
# TypeError: Some type variables (~K) are not listed in Generic[V]
```

型パラメータの順序が不明確になるので、型の仕様はこの併用を禁止している。

従来の構文で推論を利用する手段として`TypeVar("T", infer_variance=True)`がある。
pyrightはこの型変数を推論の対象にするが、mypyは`Unexpected argument to "TypeVar()": "infer_variance"`のエラーにし、`T`を型変数として認識しない。

## 実行時は変性に関係なく動作する

変性は型チェッカー向けの情報で、実行時の動作に影響しない。
指定は型変数の`__covariant__`や`__infer_variance__`の属性に記録されるが、`Box[Dog]`に`Animal`を格納しても実行時のエラーにならない。

```python
class Inferred[U]:
    def get(self) -> U: ...

(u,) = Inferred.__type_params__
print(T_co.__covariant__, T_co.__infer_variance__)  # True False
print(u.__covariant__, u.__infer_variance__)  # False True
```

型パラメータの構文の型パラメータは、`__covariant__`が`False`で`__infer_variance__`が`True`になり、推論の結果は実行時には記録されない。

## 変性の指定の判断基準

| `__init__`以外での型変数の直接の使い方 | 従来のTypeVar | 型パラメータの構文 |
|---|---|---|
| `get() -> T`のような戻り値だけ | `covariant=True` | 無指定（共変と推論） |
| `handle(x: T)`のような引数だけ | `contravariant=True` | 無指定（反変と推論） |
| 引数と戻り値の両方、または公開の`value: T` | 無指定（不変） | 無指定（不変と推論） |
| 凍結したdataclassのフィールドだけ | `covariant=True` | 型チェッカーで結果が不一致 |

型パラメータの構文が利用可能なら、変性の決定は推論が担当する。
PEP 695の著者は変性を指定する構文を検討し、多くの場合は推論が可能なことと、変性の理解を不要にすることを理由に [不採用にした](https://peps.python.org/pep-0695/#explicit-variance)。
