タイピング—タイプヒントのサポート—Pythonドキュメント

提供：Dev Guides
< PythonPython/docs/3.8/library/typing
移動先:案内、検索

タイピング —タイプヒントのサポート

バージョン3.5の新機能。


ソースコード： ：source： `Lib / typing.py`

ノート

Pythonランタイムは、関数と変数の型注釈を強制しません。 これらは、タイプチェッカー、IDE、リンターなどのサードパーティツールで使用できます。


このモジュールは、 PEP 484 、 PEP 526 、 で指定されたタイプヒントのランタイムサポートを提供します。 PEP 544 、 PEP 586 、 PEP 589 、および PEP 591 [X230X ]。 最も基本的なサポートは、タイプ Any 、 Union 、 Tuple 、 Callable 、 TypeVar 、および[ X148X]汎用。 完全な仕様については、 PEP 484 を参照してください。 タイプヒントの簡単な紹介については、 PEP 483 を参照してください。

以下の関数は文字列を受け取り、返し、次のように注釈が付けられます。 

def greeting(name: str) -> str:
    return 'Hello ' + name

関数greetingでは、引数nameはタイプ str であり、戻りタイプは str であると想定されています。 サブタイプは引数として受け入れられます。

タイプエイリアス

タイプエイリアスは、タイプをエイリアスに割り当てることによって定義されます。 この例では、VectorとList[float]は交換可能な同義語として扱われます。 

from typing import List
Vector = List[float]

def scale(scalar: float, vector: Vector) -> Vector:
    return [scalar * num for num in vector]

# typechecks; a list of floats qualifies as a Vector.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

型エイリアスは、複雑な型シグネチャを単純化するのに役立ちます。 例えば： 

from typing import Dict, Tuple, Sequence

ConnectionOptions = Dict[str, str]
Address = Tuple[str, int]
Server = Tuple[Address, ConnectionOptions]

def broadcast_message(message: str, servers: Sequence[Server]) -> None:
    ...

# The static type checker will treat the previous type signature as
# being exactly equivalent to this one.
def broadcast_message(
        message: str,
        servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:
    ...

タイプヒントとしてのNoneは特殊なケースであり、type(None)に置き換えられることに注意してください。


新しいタイプ

NewType（）ヘルパー関数を使用して、個別のタイプを作成します。 

from typing import NewType

UserId = NewType('UserId', int)
some_id = UserId(524313)

静的型チェッカーは、新しい型を元の型のサブクラスであるかのように扱います。 これは、論理エラーをキャッチするのに役立ちます。 

def get_user_name(user_id: UserId) -> str:
    ...

# typechecks
user_a = get_user_name(UserId(42351))

# does not typecheck; an int is not a UserId
user_b = get_user_name(-1)

タイプUserIdの変数に対してすべてのint操作を実行することはできますが、結果は常にタイプintになります。 これにより、intが予想される場所であればどこでも、UserIdを渡すことができますが、誤ってUserIdを無効な方法で作成することはありません。 

# 'output' is of type 'int', not 'UserId'
output = UserId(23413) + UserId(54341)

これらのチェックは、静的型チェッカーによってのみ実施されることに注意してください。 実行時に、ステートメントDerived = NewType('Derived', Base)は、Derivedを、渡したパラメーターをすぐに返す関数にします。 つまり、式Derived(some_value)は、新しいクラスを作成したり、通常の関数呼び出しのオーバーヘッドを超えるオーバーヘッドを導入したりすることはありません。

より正確には、式some_value is Derived(some_value)は実行時に常に真です。

これは、Derivedのサブタイプを作成できないことも意味します。これは、実行時の恒等関数であり、実際のタイプではないためです。 

from typing import NewType

UserId = NewType('UserId', int)

# Fails at runtime and does not typecheck
class AdminUserId(UserId): pass

ただし、「派生」NewTypeに基づいて NewType（）を作成することは可能です。 

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

ProUserIdのタイプチェックは期待どおりに機能します。

詳細については、 PEP 484 を参照してください。

ノート

タイプエイリアスを使用すると、2つのタイプが互いに同等であると宣言されることを思い出してください。 Alias = Originalを実行すると、静的型チェッカーはAliasをとOriginalとまったく同じとして扱います。 これは、複雑な型の署名を単純化したい場合に役立ちます。

対照的に、NewTypeは、あるタイプを別のタイプのサブタイプとして宣言します。 Derived = NewType('Derived', Original)を実行すると、静的型チェッカーはDerivedをOriginalのサブクラスとして扱います。つまり、型Originalの値は処理できません。タイプDerivedの値が予想される場所で使用されます。 これは、最小限のランタイムコストでロジックエラーを防止したい場合に役立ちます。


バージョン3.5.2の新機能。


呼び出し可能

特定のシグニチャのコールバック関数を期待するフレームワークは、Callable[[Arg1Type, Arg2Type], ReturnType]を使用して型ヒントされる場合があります。

例えば： 

from typing import Callable

def feeder(get_next_item: Callable[[], str]) -> None:
    # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    # Body

タイプヒントCallable[..., ReturnType]の引数のリストをリテラルの省略記号に置き換えることにより、呼び出しシグネチャを指定せずに呼び出し可能オブジェクトの戻り型を宣言できます。


ジェネリック

コンテナに保持されているオブジェクトに関する型情報を一般的な方法で静的に推測することはできないため、抽象基本クラスが拡張され、コンテナ要素の予想される型を示すサブスクリプションがサポートされるようになりました。 

from typing import Mapping, Sequence

def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

ジェネリックスは、 TypeVar と呼ばれるタイピングで利用可能な新しいファクトリを使用してパラメータ化できます。 

from typing import Sequence, TypeVar

T = TypeVar('T')      # Declare type variable

def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

ユーザー定義のジェネリック型

ユーザー定義クラスは、ジェネリッククラスとして定義できます。 

from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic[T]):
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new

    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value

    def log(self, message: str) -> None:
        self.logger.info('%s: %s', self.name, message)

基本クラスとしてのGeneric[T]は、クラスLoggedVarが単一の型パラメーターTを取ることを定義します。 これにより、Tがクラス本体内の型として有効になります。

Generic 基本クラスは__class_getitem__()を定義し、LoggedVar[t]がタイプとして有効になるようにします。 

from typing import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

ジェネリック型は任意の数の型変数を持つことができ、型変数は制約される可能性があります。 

from typing import TypeVar, Generic
...

T = TypeVar('T')
S = TypeVar('S', int, str)

class StrangePair(Generic[T, S]):
    ...

Generic への各型変数引数は別個でなければなりません。 したがって、これは無効です。 

from typing import TypeVar, Generic
...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...

Generic で多重継承を使用できます。 

from typing import TypeVar, Generic, Sized

T = TypeVar('T')

class LinkedList(Sized, Generic[T]):
    ...

ジェネリッククラスから継承する場合、いくつかの型変数を修正できます。 

from typing import TypeVar, Mapping

T = TypeVar('T')

class MyDict(Mapping[str, T]):
    ...

この場合、MyDictにはTという単一のパラメーターがあります。

タイプパラメータを指定せずにジェネリッククラスを使用すると、各位置に Any が想定されます。 次の例では、MyIterableはジェネリックではありませんが、Iterable[Any]から暗黙的に継承します。 

from typing import Iterable

class MyIterable(Iterable): # Same as Iterable[Any]

ユーザー定義のジェネリック型エイリアスもサポートされています。 例： 

from typing import TypeVar, Iterable, Tuple, Union
S = TypeVar('S')
Response = Union[Iterable[S], int]

# Return type here is same as Union[Iterable[str], int]
def response(query: str) -> Response[str]:
    ...

T = TypeVar('T', int, float, complex)
Vec = Iterable[Tuple[T, T]]

def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]]
    return sum(x*y for x, y in v)

バージョン3.7で変更： Generic にカスタムメタクラスがなくなりました。


ユーザー定義のジェネリッククラスは、メタクラスの競合なしに基本クラスとしてABCを持つことができます。 汎用メタクラスはサポートされていません。 ジェネリックスのパラメーター化の結果はキャッシュされ、タイピングモジュールのほとんどのタイプはハッシュ可能であり、同等性について比較可能です。


Any タイプ

特別な種類のタイプは Any です。 静的型チェッカーは、すべての型を Any と互換性があるものとして扱います。 Any はすべての型と互換性があるものとして扱います。

これは、タイプ Any の値に対して任意の操作またはメソッド呼び出しを実行し、それを任意の変数に割り当てることができることを意味します。 

from typing import Any

a = None    # type: Any
a = []      # OK
a = 2       # OK

s = ''      # type: str
s = a       # OK

def foo(item: Any) -> int:
    # Typechecks; 'item' could be any type,
    # and that type might have a 'bar' method
    item.bar()
    ...

タイプ Any の値をより正確なタイプに割り当てる場合、タイプチェックは実行されないことに注意してください。 たとえば、sが str 型であると宣言され、実行時の int 値！

さらに、戻り型またはパラメーター型のないすべての関数は、暗黙的にデフォルトで Any を使用します。 

def legacy_parser(text):
    ...
    return data

# A static type checker will treat the above
# as having the same signature as:
def legacy_parser(text: Any) -> Any:
    ...
    return data

この動作により、動的および静的に型指定されたコードを混合する必要がある場合に、 Any をエスケープハッチとして使用できます。

Any の動作と object の動作を比較してください。 Any と同様に、すべてのタイプは object のサブタイプです。 ただし、 Any とは異なり、その逆は当てはまりません。 object は not 他のすべてのタイプのサブタイプです。

つまり、値の型が object の場合、型チェッカーはその値に対するほとんどすべての操作を拒否し、より特殊な型の変数に割り当てる（または戻り値として使用する）ことはタイプエラー。 例えば： 

def hash_a(item: object) -> int:
    # Fails; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Typechecks
    item.magic()
    ...

# Typechecks, since ints and strs are subclasses of object
hash_a(42)
hash_a("foo")

# Typechecks, since Any is compatible with all types
hash_b(42)
hash_b("foo")

object を使用して、値がタイプセーフな方法で任意のタイプになり得ることを示します。 Any を使用して、値が動的に型指定されることを示します。


名目上のサブタイピングと構造的なサブタイピング

当初、 PEP 484 は、Python静的型システムを名義サブタイピングを使用するものとして定義していました。 これは、AがBのサブクラスである場合にのみ、クラスBが期待されるクラスAが許可されることを意味します。

この要件は、以前は Iterable などの抽象基本クラスにも適用されていました。 このアプローチの問題は、クラスをサポートするために明示的にマークを付ける必要があることです。これは非Pythonであり、慣用的な動的型付けPythonコードで通常行うこととは異なります。 たとえば、これは PEP 484 に準拠しています。 

from typing import Sized, Iterable, Iterator

class Bucket(Sized, Iterable[int]):
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

PEP 544 は、ユーザーがクラス定義に明示的な基本クラスなしで上記のコードを記述できるようにすることでこの問題を解決し、Bucketが暗黙的にのサブタイプと見なされるようにします。静的型チェッカーによるSizedとIterable[int]の両方。 これは、構造サブタイピング（または静的ダックタイピング）として知られています。 

from typing import Iterator, Iterable

class Bucket:  # Note: no base classes
    ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[int]: ...

def collect(items: Iterable[int]) -> int: ...
result = collect(Bucket())  # Passes type check

さらに、特別なクラス Protocol をサブクラス化することにより、ユーザーは新しいカスタムプロトコルを定義して、構造的なサブタイピングを十分に楽しむことができます（以下の例を参照）。


クラス、関数、およびデコレータ

このモジュールは、次のクラス、関数、およびデコレータを定義します。

class typing.TypeVar

変数を入力します。

使用法：

T = TypeVar('T')  # Can be anything
A = TypeVar('A', str, bytes)  # Must be str or bytes

型変数は、主に静的型チェッカーの利益のために存在します。 これらは、ジェネリック型およびジェネリック関数定義のパラメーターとして機能します。 ジェネリック型の詳細については、クラスGenericを参照してください。 ジェネリック関数は次のように機能します。

def repeat(x: T, n: int) -> Sequence[T]:
    """Return a list containing n references to x."""
    return [x]*n

def longest(x: A, y: A) -> A:
    """Return the longest of two strings."""
    return x if len(x) >= len(y) else y

後者の例の署名は、本質的に(str, str) -> strと(bytes, bytes) -> bytesのオーバーロードです。 また、引数が str のサブクラスのインスタンスである場合、戻り値の型はプレーン str のままであることに注意してください。

実行時に、isinstance(x, T)は TypeError を発生させます。 一般に、 isinstance（）および issubclass（）は型と一緒に使用しないでください。

型変数は、covariant=Trueまたはcontravariant=Trueを渡すことにより、共変または反変としてマークできます。 詳細については、 PEP 484 を参照してください。 デフォルトでは、型変数は不変です。 あるいは、型変数はbound=<type>を使用して上限を指定することもできます。 これは、型変数の代わりに（明示的または暗黙的に）実際の型が境界型のサブクラスでなければならないことを意味します。 PEP484 を参照してください。

class typing.Generic

ジェネリック型の抽象基本クラス。

ジェネリック型は通常、1つ以上の型変数を使用してこのクラスのインスタンス化から継承することによって宣言されます。 たとえば、一般的なマッピングタイプは次のように定義されます。

class Mapping(Generic[KT, VT]):
    def __getitem__(self, key: KT) -> VT:
        ...
        # Etc.

このクラスは、次のように使用できます。

X = TypeVar('X')
Y = TypeVar('Y')

def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y:
    try:
        return mapping[key]
    except KeyError:
        return default
class typing.Protocol(Generic)

プロトコルクラスの基本クラス。 プロトコルクラスは次のように定義されます。

class Proto(Protocol):
    def meth(self) -> int:
        ...

このようなクラスは主に、構造サブタイピング（静的ダックタイピング）を認識する静的型チェッカーで使用されます。次に例を示します。

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

詳細については、 PEP 544 を参照してください。 runtime_checkable（）（後述）で装飾されたプロトコルクラスは、型シグネチャを無視して、指定された属性の存在のみをチェックする単純なランタイムプロトコルとして機能します。

プロトコルクラスは、次のように汎用にすることができます。

class GenProto(Protocol[T]):
    def meth(self) -> T:
        ...

バージョン3.8の新機能。

class typing.Type(Generic[CT_co])

Cで注釈が付けられた変数は、タイプCの値を受け入れることができます。 対照的に、Type[C]で注釈が付けられた変数は、それ自体がクラスである値を受け入れる場合があります。具体的には、Cのクラスオブジェクトを受け入れます。 例えば：

a = 3         # Has type 'int'
b = int       # Has type 'Type[int]'
c = type(a)   # Also has type 'Type[int]'

Type[C]は共変であることに注意してください。

class User: ...
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

# Accepts User, BasicUser, ProUser, TeamUser, ...
def make_new_user(user_class: Type[User]) -> User:
    # ...
    return user_class()

Type[C]が共変であるという事実は、CのすべてのサブクラスがCと同じコンストラクターシグネチャーとクラスメソッドシグネチャーを実装する必要があることを意味します。 タイプチェッカーは、この違反にフラグを立てる必要がありますが、指定された基本クラスのコンストラクター呼び出しと一致するサブクラスのコンストラクター呼び出しも許可する必要があります。 この特定のケースを処理するためにタイプチェッカーがどのように必要とされるかは、 PEP 484 の将来のリビジョンで変更される可能性があります。

Type の唯一の有効なパラメーターは、クラス、 Any 、 type変数、およびこれらのタイプの和集合です。 例えば：

def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...

Type[Any]はTypeと同等であり、typeはPythonのメタクラス階層のルートです。

バージョン3.5.2の新機能。

class typing.Iterable(Generic[T_co])
collections.abc.Iterable の汎用バージョン。
class typing.Iterator(Iterable[T_co])
collections.abc.Iterator の汎用バージョン。
class typing.Reversible(Iterable[T_co])
collections.abc.Reversible の汎用バージョン。
class typing.SupportsInt
1つの抽象メソッド__int__を持つABC。
class typing.SupportsFloat
1つの抽象メソッド__float__を持つABC。
class typing.SupportsComplex
1つの抽象メソッド__complex__を持つABC。
class typing.SupportsBytes
1つの抽象メソッド__bytes__を持つABC。
class typing.SupportsIndex

1つの抽象メソッド__index__を持つABC。

バージョン3.8の新機能。

class typing.SupportsAbs
戻り型が共変である1つの抽象メソッド__abs__を持つABC。
class typing.SupportsRound
戻り型が共変である1つの抽象メソッド__round__を持つABC。
class typing.Container(Generic[T_co])
collections.abc.Container の汎用バージョン。
class typing.Hashable
collections.abc.Hashable のエイリアス
class typing.Sized
collections.abc.Sized のエイリアス
class typing.Collection(Sized, Iterable[T_co], Container[T_co])

collections.abc.Collection の汎用バージョン

バージョン3.6.0の新機能。

class typing.AbstractSet(Sized, Collection[T_co])
collections.abc.Set の汎用バージョン。
class typing.MutableSet(AbstractSet[T])
collections.abc.MutableSet の汎用バージョン。
class typing.Mapping(Sized, Collection[KT], Generic[VT_co])

collections.abc.Mapping の汎用バージョン。 このタイプは次のように使用できます。

def get_position_in_index(word_list: Mapping[str, int], word: str) -> int:
    return word_list[word]
class typing.MutableMapping(Mapping[KT, VT])
collections.abc.MutableMapping の汎用バージョン。
class typing.Sequence(Reversible[T_co], Collection[T_co])
collections.abc.Sequence の汎用バージョン。
class typing.MutableSequence(Sequence[T])
collections.abc.MutableSequence の汎用バージョン。
class typing.ByteString(Sequence[int])

collections.abc.ByteString の汎用バージョン。

このタイプは、バイトシーケンスのタイプ bytes 、 bytearray 、および memoryview を表します。

このタイプの省略形として、 bytes を使用して、上記のタイプの引数に注釈を付けることができます。

class typing.Deque(deque, MutableSequence[T])

collections.deque の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.1の新機能。

class typing.List(list, MutableSequence[T])

リストの汎用バージョン。 リターンタイプに注釈を付けるのに便利です。 引数に注釈を付けるには、 Sequence や Iterable などの抽象コレクションタイプを使用することをお勧めします。

このタイプは次のように使用できます。

T = TypeVar('T', int, float)

def vec2(x: T, y: T) -> List[T]:
    return [x, y]

def keep_positives(vector: Sequence[T]) -> List[T]:
    return [item for item in vector if item > 0]
class typing.Set(set, MutableSet[T])
builtins.set の汎用バージョン。 リターンタイプに注釈を付けるのに便利です。 引数に注釈を付けるには、 AbstractSet などの抽象コレクションタイプを使用することをお勧めします。
class typing.FrozenSet(frozenset, AbstractSet[T_co])
builtins.frozenset の汎用バージョン。
class typing.MappingView(Sized, Iterable[T_co])
collections.abc.MappingView の汎用バージョン。
class typing.KeysView(MappingView[KT_co], AbstractSet[KT_co])
collections.abc.KeysView の汎用バージョン。
class typing.ItemsView(MappingView, Generic[KT_co, VT_co])
collections.abc.ItemsView の汎用バージョン。
class typing.ValuesView(MappingView[VT_co])
collections.abc.ValuesView の汎用バージョン。
class typing.Awaitable(Generic[T_co])

collections.abc.Awaitable の汎用バージョン。

バージョン3.5.2の新機能。

class typing.Coroutine(Awaitable[V_co], Generic[T_co, T_contra, V_co])

collections.abc.Coroutine の汎用バージョン。 型変数の分散と順序は、 Generator のものに対応します。次に例を示します。

from typing import List, Coroutine
c = None # type: Coroutine[List[str], str, int]
...
x = c.send('hi') # type: List[str]
async def bar() -> None:
    x = await c # type: int

バージョン3.5.3の新機能。

class typing.AsyncIterable(Generic[T_co])

collections.abc.AsyncIterable の汎用バージョン。

バージョン3.5.2の新機能。

class typing.AsyncIterator(AsyncIterable[T_co])

collections.abc.AsyncIterator の汎用バージョン。

バージョン3.5.2の新機能。

class typing.ContextManager(Generic[T_co])

contextlib.AbstractContextManager の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.0の新機能。

class typing.AsyncContextManager(Generic[T_co])

contextlib.AbstractAsyncContextManager の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.2の新機能。

class typing.Dict(dict, MutableMapping[KT, VT])

dict の汎用バージョン。 リターンタイプに注釈を付けるのに便利です。 引数に注釈を付けるには、 Mapping などの抽象コレクションタイプを使用することをお勧めします。

このタイプは次のように使用できます。

def count_words(text: str) -> Dict[str, int]:
    ...
class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])

collections.defaultdict の汎用バージョン。

バージョン3.5.2の新機能。

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])

collections.OrderedDict の汎用バージョン。

バージョン3.7.2の新機能。

class typing.Counter(collections.Counter, Dict[T, int])

collections.Counter の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.1の新機能。

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])

collections.ChainMap の汎用バージョン。

バージョン3.5.4の新機能。

バージョン3.6.1の新機能。

class typing.Generator(Iterator[T_co], Generic[T_co, T_contra, V_co])

ジェネレーターには、汎用タイプGenerator[YieldType, SendType, ReturnType]の注釈を付けることができます。 例えば：

def echo_round() -> Generator[int, float, str]:
    sent = yield 0
    while sent >= 0:
        sent = yield round(sent)
    return 'Done'

タイピングモジュールの他の多くのジェネリックとは異なり、 Generator のSendTypeは、共変または不変ではなく、反変的に動作することに注意してください。

ジェネレーターが値のみを生成する場合は、SendTypeおよびReturnTypeをNoneに設定します。

def infinite_stream(start: int) -> Generator[int, None, None]:
    while True:
        yield start
        start += 1

または、Iterable[YieldType]またはIterator[YieldType]のいずれかのリターンタイプを持つようにジェネレーターに注釈を付けます。

def infinite_stream(start: int) -> Iterator[int]:
    while True:
        yield start
        start += 1
class typing.AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra])

非同期ジェネレーターには、汎用タイプAsyncGenerator[YieldType, SendType]の注釈を付けることができます。 例えば：

async def echo_round() -> AsyncGenerator[int, float]:
    sent = yield 0
    while sent >= 0.0:
        rounded = await round(sent)
        sent = yield rounded

通常のジェネレーターとは異なり、非同期ジェネレーターは値を返すことができないため、ReturnTypeタイプのパラメーターはありません。 Generator と同様に、SendTypeは逆に動作します。

ジェネレーターが値のみを生成する場合は、SendTypeをNoneに設定します。

async def infinite_stream(start: int) -> AsyncGenerator[int, None]:
    while True:
        yield start
        start = await increment(start)

または、AsyncIterable[YieldType]またはAsyncIterator[YieldType]のいずれかのリターンタイプを持つようにジェネレーターに注釈を付けます。

async def infinite_stream(start: int) -> AsyncIterator[int]:
    while True:
        yield start
        start = await increment(start)

バージョン3.6.1の新機能。

class typing.Text

Textは、strのエイリアスです。 Python 2コードの上位互換パスを提供するために提供されています。Python2では、Textはunicodeのエイリアスです。

Textを使用して、Python2とPython3の両方と互換性のある方法で値にUnicode文字列が含まれている必要があることを示します。

def add_unicode_checkmark(text: Text) -> Text:
    return text + u' \u2713'

バージョン3.5.2の新機能。

class typing.IO

class typing.TextIO
class typing.BinaryIO

ジェネリック型IO[AnyStr]とそのサブクラスTextIO(IO[str])およびBinaryIO(IO[bytes])は、 open（）によって返されるようなI / Oストリームの型を表します。
class typing.Pattern

class typing.Match

これらのタイプエイリアスは、 re.compile（）および re.match（）からの戻りタイプに対応します。 これらのタイプ（および対応する関数）はAnyStrでジェネリックであり、Pattern[str]、Pattern[bytes]、Match[str]、または [と書くことで特定できます。 X147X]。
class typing.NamedTuple

collections.namedtuple（）の型付きバージョン。

使用法：

class Employee(NamedTuple):
    name: str
    id: int

これは次と同等です。

Employee = collections.namedtuple('Employee', ['name', 'id'])

フィールドにデフォルト値を与えるには、クラス本体でフィールドに割り当てることができます。

class Employee(NamedTuple):
    name: str
    id: int = 3

employee = Employee('Guido')
assert employee.id == 3

デフォルト値のあるフィールドは、デフォルトのないフィールドの後に来る必要があります。

結果のクラスには、フィールド名をフィールドタイプにマップするdictを与える追加の属性__annotations__があります。 （フィールド名は_fields属性にあり、デフォルト値は_field_defaults属性にあり、どちらもnamedtuple APIの一部です。）

NamedTupleサブクラスには、docstringとメソッドを含めることもできます。

class Employee(NamedTuple):
    """Represents an employee."""
    name: str
    id: int = 3

    def __repr__(self) -> str:
        return f'<Employee {self.name}, id={self.id}>'

下位互換性のある使用法：

Employee = NamedTuple('Employee', [('name', str), ('id', int)])

バージョン3.6で変更： PEP 526 変数注釈構文のサポートが追加されました。

バージョン3.6.1で変更：デフォルト値、メソッド、およびdocstringのサポートが追加されました。

バージョン3.8で変更： _field_typesおよび__annotations__属性は、OrderedDictのインスタンスではなく、通常の辞書になりました。

class typing.TypedDict(dict)

単純な型付き名前空間。 実行時には、プレーンな dict と同等です。

TypedDictは、すべてのインスタンスが特定のキーのセットを持つことを期待する辞書タイプを作成します。各キーは、一貫したタイプの値に関連付けられています。 この期待値は実行時にチェックされませんが、タイプチェッカーによってのみ強制されます。 使用法：

class Point2D(TypedDict):
    x: int
    y: int
    label: str

a: Point2D = {'x': 1, 'y': 2, 'label': 'good'}  # OK
b: Point2D = {'z': 3, 'label': 'bad'}           # Fails type check

assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first')

イントロスペクションのタイプ情報には、Point2D.__annotations__およびPoint2D.__total__からアクセスできます。 PEP 526 をサポートしない古いバージョンのPythonでこの機能を使用できるようにするために、TypedDictは2つの同等の構文形式をサポートしています。

Point2D = TypedDict('Point2D', x=int, y=int, label=str)
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})

デフォルトでは、すべてのキーがTypedDictに存在する必要があります。 全体を指定することでこれを上書きすることができます。 使用法：

class point2D(TypedDict, total=False):
    x: int
    y: int

これは、point2DTypedDictで任意のキーを省略できることを意味します。 型チェッカーは、引数の合計の値としてリテラルのFalseまたはTrueのみをサポートすることが期待されています。 Trueがデフォルトであり、クラス本体で定義されているすべての項目が必須になります。

TypedDictの使用に関するその他の例と詳細なルールについては、 PEP 589 を参照してください。

バージョン3.8の新機能。

class typing.ForwardRef

文字列前方参照の内部型付け表現に使用されるクラス。 たとえば、List["SomeClass"]は暗黙的にList[ForwardRef("SomeClass")]に変換されます。 このクラスはユーザーによってインスタンス化されるべきではありませんが、イントロスペクションツールによって使用される可能性があります。

バージョン3.7.4の新機能。

typing.NewType(name, tp)

タイプチェッカーに個別のタイプを示すヘルパー関数。 NewType を参照してください。 実行時に、引数を返す関数を返します。 使用法：

UserId = NewType('UserId', int)
first_user = UserId(1)

バージョン3.5.2の新機能。

typing.cast(typ, val)

タイプに値をキャストします。

これにより、値は変更されずに返されます。 型チェッカーに対して、これは戻り値が指定された型を持っていることを通知しますが、実行時に意図的に何もチェックしません（これをできるだけ速くしたい）。

typing.get_type_hints(obj[, globals[, locals]])

関数、メソッド、モジュール、またはクラスオブジェクトの型ヒントを含むディクショナリを返します。

多くの場合、これはobj.__annotations__と同じです。 さらに、文字列リテラルとしてエンコードされた前方参照は、globalsおよびlocals名前空間で評価することによって処理されます。 必要に応じて、Noneに等しいデフォルト値が設定されている場合、関数およびメソッドのアノテーションにOptional[t]が追加されます。 クラスCの場合、すべての__annotations__をC.__mro__に沿って逆の順序でマージして作成された辞書を返します。

typing.get_origin(tp)
typing.get_args(tp)

ジェネリック型と特殊な型付けフォームの基本的な内省を提供します。

X[Y, Z, ...]の形式の入力オブジェクトの場合、これらの関数はXおよび(Y, Z, ...)を返します。 Xが組み込みクラスまたはコレクションクラスの汎用エイリアスである場合、元のクラスに正規化されます。 サポートされていないオブジェクトの場合、それぞれNoneと()を返します。 例：

assert get_origin(Dict[str, int]) is dict
assert get_args(Dict[int, str]) == (int, str)

assert get_origin(Union[int, str]) is Union
assert get_args(Union[int, str]) == (int, str)

バージョン3.8の新機能。

@typing.overload

@overloadデコレータを使用すると、引数タイプの複数の異なる組み合わせをサポートする関数とメソッドを記述できます。 一連の@overloadで装飾された定義の後には、@overloadで装飾されていない定義が1つだけ続く必要があります（同じ関数/メソッドの場合）。 @overloadで装飾された定義は、タイプチェッカー専用です。これは、@overloadで装飾されていない定義によって上書きされるためです。後者は実行時に使用されますが、無視する必要があります。タイプチェッカーによる。 実行時に、@overloadで装飾された関数を直接呼び出すと、 NotImplementedError が発生します。 ユニオンまたは型変数を使用して表現できるよりも正確な型を与えるオーバーロードの例：

@overload
def process(response: None) -> None:
    ...
@overload
def process(response: int) -> Tuple[int, str]:
    ...
@overload
def process(response: bytes) -> str:
    ...
def process(response):
    <actual implementation>

詳細および他のタイピングセマンティクスとの比較については、 PEP 484 を参照してください。

@typing.final

装飾されたメソッドをオーバーライドできず、装飾されたクラスをサブクラス化できないことをタイプチェッカーに示すデコレータ。 例えば：

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # Error reported by type checker
          ...

@final
class Leaf:
    ...
class Other(Leaf):  # Error reported by type checker
    ...

これらのプロパティの実行時チェックはありません。 詳細については、 PEP 591 を参照してください。

バージョン3.8の新機能。

@typing.no_type_check

注釈がタイプヒントではないことを示すデコレータ。

これは、クラスまたは関数デコレータとして機能します。 クラスを使用すると、そのクラスで定義されているすべてのメソッドに再帰的に適用されます（ただし、そのスーパークラスまたはサブクラスで定義されているメソッドには適用されません）。

これにより、機能が適切に変更されます。

@typing.no_type_check_decorator

別のデコレータに no_type_check（）効果を与えるデコレータ。

これは、 no_type_check（）のデコレートされた関数をラップするものでデコレータをラップします。

@typing.type_check_only

クラスまたは関数を実行時に使用不可としてマークするデコレータ。

このデコレータ自体は実行時に使用できません。 これは主に、実装がプライベートクラスのインスタンスを返す場合に、タイプスタブファイルで定義されているクラスをマークすることを目的としています。

@type_check_only
class Response:  # private or not available at runtime
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...

プライベートクラスのインスタンスを返すことは推奨されないことに注意してください。 通常、このようなクラスを公開することをお勧めします。

@typing.runtime_checkable

プロトコルクラスをランタイムプロトコルとしてマークします。

このようなプロトコルは、 isinstance（）および issubclass（）で使用できます。 これにより、非プロトコルクラスに適用されると、 TypeError が発生します。 これにより、 Iterable などの collections.abc の「ワントリックポニー」と非常によく似たシンプルな構造チェックが可能になります。 例えば：

@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

警告：これにより、必要なメソッドの存在のみがチェックされ、型シグネチャはチェックされません。

バージョン3.8の新機能。

typing.Any
拘束されていないタイプを示す特殊タイプ。
  • すべてのタイプは Any と互換性があります。
  • Any はすべてのタイプと互換性があります。
typing.NoReturn

関数が戻らないことを示す特殊なタイプ。 例えば：

from typing import NoReturn

def stop() -> NoReturn:
    raise RuntimeError('no way')

バージョン3.5.4の新機能。

バージョン3.6.2の新機能。

typing.Union

共用体タイプ; Union[X, Y]はXまたはYのいずれかを意味します。

和集合を定義するには、例えば Union[int, str]。 詳細：

  • 引数は型である必要があり、少なくとも1つ存在する必要があります。

  • ユニオンのユニオンはフラット化されます。例：

    Union[Union[int, str], float] == Union[int, str, float]

  • 単一の引数の結合は消えます。例：

    Union[int] == int  # The constructor actually returns int

  • 冗長な引数はスキップされます。例：

    Union[int, str, int] == Union[int, str]

  • ユニオンを比較する場合、引数の順序は無視されます。例：

    Union[int, str] == Union[str, int]

  • ユニオンをサブクラス化またはインスタンス化することはできません。

  • Union[X][Y]は書き込めません。

  • Optional[X]はUnion[X, None]の省略形として使用できます。

バージョン3.7で変更：実行時にユニオンから明示的なサブクラスを削除しないでください。

typing.Optional

オプションタイプ。

Optional[X]はUnion[X, None]と同等です。

これは、デフォルトの引数であるオプションの引数と同じ概念ではないことに注意してください。 デフォルトのオプションの引数は、オプションであるという理由だけで、型注釈にOptional修飾子を必要としません。 例えば：

def foo(arg: int = 0) -> None:
    ...

一方、Noneの明示的な値が許可されている場合は、引数がオプションであるかどうかに関係なく、Optionalの使用が適切です。 例えば：

def foo(arg: Optional[int] = None) -> None:
    ...
typing.Tuple

タプルタイプ; Tuple[X, Y]は、タイプXの最初のアイテムとタイプYの2番目のアイテムを持つ2つのアイテムのタプルのタイプです。 空のタプルのタイプは、Tuple[()]と書くことができます。

例：Tuple[T1, T2]は、型変数T1およびT2に対応する2つの要素のタプルです。 Tuple[int, float, str]は、int、float、およびstringのタプルです。

同種タイプの可変長タプルを指定するには、リテラルの省略記号を使用します。 Tuple[int, ...]。 プレーンなタプルはTuple[Any, ...]と同等であり、タプルと同等です。

typing.Callable

呼び出し可能なタイプ。 Callable[[int], str]は（int）-> strの関数です。

サブスクリプション構文は、常に引数リストと戻り型の2つの値で使用する必要があります。 引数リストは、タイプのリストまたは省略記号である必要があります。 戻り型は単一の型である必要があります。

オプションまたはキーワード引数を示す構文はありません。 このような関数型がコールバック型として使用されることはめったにありません。 Callable[..., ReturnType]（リテラル省略記号）を使用して、任意の数の引数を取り、ReturnTypeを返すcallableのヒントを入力できます。 プレーンな Callable は、Callable[..., Any]と同等であり、 collections.abc.Callable と同等です。

typing.Literal

対応する変数または関数パラメーターが、提供されたリテラル（またはいくつかのリテラルの1つ）と同等の値を持っていることを型チェッカーに示すために使用できる型。 例えば：

def validate_simple(data: Any) -> Literal[True]:  # always returns True
    ...

MODE = Literal['r', 'rb', 'w', 'wb']
def open_helper(file: str, mode: MODE) -> str:
    ...

open_helper('/some/path', 'r')  # Passes type check
open_helper('/other/path', 'typo')  # Error in type checker

Literal[...]はサブクラス化できません。 実行時には、Literal[...]の型引数として任意の値を使用できますが、型チェッカーによって制限が課される場合があります。 リテラル型の詳細については、 PEP 586 を参照してください。

バージョン3.8の新機能。

typing.ClassVar

クラス変数をマークするための特別な型コンストラクト。

PEP 526 で紹介されているように、ClassVarでラップされた変数アノテーションは、特定の属性がクラス変数として使用されることを意図しており、そのクラスのインスタンスに設定されるべきではないことを示します。 使用法：

class Starship:
    stats: ClassVar[Dict[str, int]] = {} # class variable
    damage: int = 10                     # instance variable

ClassVar はタイプのみを受け入れ、それ以上サブスクライブすることはできません。

ClassVar はクラス自体ではないため、 isinstance（）または issubclass（）と一緒に使用しないでください。 ClassVar はPythonランタイムの動作を変更しませんが、サードパーティのタイプチェッカーで使用できます。 たとえば、タイプチェッカーは次のコードにエラーのフラグを立てる場合があります。

enterprise_d = Starship(3000)
enterprise_d.stats = {} # Error, setting class variable on instance
Starship.stats = {}     # This is OK

バージョン3.5.3の新機能。

typing.Final

サブクラスで名前を再割り当てまたはオーバーライドできないことをタイプチェッカーに示すための特別なタイピング構造。 例えば：

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # Error reported by type checker

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # Error reported by type checker

これらのプロパティの実行時チェックはありません。 詳細については、 PEP 591 を参照してください。

バージョン3.8の新機能。

typing.AnyStr

AnyStrは、AnyStr = TypeVar('AnyStr', str, bytes)として定義された型変数です。

これは、さまざまな種類の文字列を混在させることなく、任意の種類の文字列を受け入れることができる関数に使用することを目的としています。 例えば：

def concat(a: AnyStr, b: AnyStr) -> AnyStr:
    return a + b

concat(u"foo", u"bar")  # Ok, output has type 'unicode'
concat(b"foo", b"bar")  # Ok, output has type 'bytes'
concat(u"foo", b"bar")  # Error, cannot mix unicode and bytes
typing.TYPE_CHECKING

サードパーティの静的型チェッカーによってTrueと見なされる特別な定数。 実行時はFalseです。 使用法：

if TYPE_CHECKING:
    import expensive_mod

def fun(arg: 'expensive_mod.SomeType') -> None:
    local_var: expensive_mod.AnotherType = other_fun()

expensive_mod参照をインタープリターランタイムから非表示にするには、最初の型注釈を引用符で囲んで「前方参照」にする必要があることに注意してください。 ローカル変数の型注釈は評価されないため、2番目の注釈を引用符で囲む必要はありません。

バージョン3.5.2の新機能。



「https://www.finddevguides.com/index.php?title=Python/docs/3.8/library/typing&oldid=99233」から取得
Powered by MediaWiki