本文へスキップ

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

python-typevar-variance

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の型ヒントと共変・反変・不変 で説明した。

無指定のTypeVarは不変になる

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

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で宣言したジェネリックなクラスを 型の仕様 がすべての型変数について不変と定義していることである。

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

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

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の要素型が不変である。

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

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

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のどちらでもエラーにならない。

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は値の処理を行い、戻り値の型に型変数を使用しない。

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]型の引数として有効である。

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

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 は継承関係ではなく、メソッドや属性などのメンバーの型で適合を判定するクラスである。
ジェネリックなProtocolでは、型チェッカーが型変数の使い方から変性を計算し、指定との不一致を指摘する。
戻り値の型専用の型変数が不変のままなら、mypyはエラー、pyrightは標準の設定で警告である。

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 はProtocolの不変の宣言を有効にする案の不採用の理由を、次の例で説明している。

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はこの呼び出しをエラーにしない。

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 の構文には、型パラメータの変性の指定がない。
代わりに 型の仕様のVariance Inference が、使い方からの推論を型チェッカーに要求している。
型チェッカーは従来からProtocolの変性の検証に適用していた計算を、この構文ではProtocol以外のクラスにも適用する。
mypyは1.12から 、この構文に標準で対応している。

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]への代入だけ 反変
どちらも不可能 不変
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()))の行は従来の構文の不変と同じエラーで拒否される。

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の引数が反変なので向きが反転し、共変になる。

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のように指定する。

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から この引数を推論に含めるので、結果は不変である。
mypyは2.3で この引数を推論から除外し、共変と判定するようになった。
解析対象がPython 3.12なら__replace__が生成されないので、両方とも共変になる。
型チェッカーに依存せず共変にするには、従来の構文で型変数を共変に指定する。
次の定義はmypyとpyrightの両方でエラーにならない。

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

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を格納しても実行時のエラーにならない。

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の著者は変性を指定する構文を検討し、多くの場合は推論が可能なことと、変性の理解を不要にすることを理由に 不採用にした。

関連事例

  • データ分析支援

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

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

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

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

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

お問い合わせ・ご相談

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