26.1. `typing` — 型ヒントのサポート¶

バージョン 3.5 で追加.

ソースコード: Lib/typing.py

注釈

typing モジュールは暫定的に標準ライブラリに追加されました。マイナーリリースの間でもコアデベロッパーが必要だと判断した場合は、新機能の追加や API の変更がなされることがあります。

このモジュールは PEP 484 と PEP 526 によって規定された型ヒントをサポートします。最も基本的なサポートとして Any、 Union、 Tuple、 Callable、 TypeVar および Generic 型を含みます。完全な仕様は PEP 484 を参照してください。型ヒントの簡単な導入は PEP 483 を参照してください。

以下の関数は文字列を受け取って文字列を返す関数で、次のようにアノテーションがつけられます:

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

関数 greeting で、実引数 name の型は str であり、返り値の型は str であることが期待されます。サブタイプも実引数として許容されます。

26.1.1. 型エイリアス¶

型エイリアスは型をエイリアスに代入することで定義されます。この例では 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, List

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

def broadcast_message(message: str, servers: List[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: List[Tuple[Tuple[str, int], Dict[str, str]]]) -> None:
    ...

型ヒントとしての None は特別なケースであり、 type(None) によって置き換えられます。

26.1.2. NewType¶

異なる型を作るためには 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 のサブタイプを作ることが出来ないということも意味しています。Derived は実行時には恒等関数であり、実際の型ではないからです:

from typing import NewType

UserId = NewType('UserId', int)

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

しかし、 'derived' である NewType をもとにした NewType() は作ることが出来ます:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

そして ProUserId に対する型検査は期待通りに動作します。

詳細は PEP 484 を参照。

注釈

型エイリアスの使用は二つの型が互いに等価だと宣言している、ということを思い出してください。 Alias = Original とすると、静的型検査器は Alias をすべての場合において Original と 完全に等価 なものとして扱います。これは複雑な型シグネチャを単純化したい時に有用です。

これに対し、 NewType はある型をもう一方の型の サブタイプ として宣言します。 Derived = NewType('Derived', Original) とすると静的型検査器は Derived を Original の サブクラス として扱います。つまり Original 型の値は Derived 型の値が期待される場所で使うことが出来ないということです。これは論理的な誤りを最小の実行時のコストで防ぎたい時に有用です。

バージョン 3.5.2 で追加.

26.1.3. 呼び出し可能オブジェクト¶

特定のシグネチャのコールバック関数であることが期待されるフレームワークでは 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

型ヒントの実引数の型を ellipsis で置き換えることで呼び出しシグニチャを指定せずに callable の戻り値の型を宣言することができます: Callable[..., ReturnType]。

26.1.4. ジェネリクス¶

コンテナ内のオブジェクトについての型情報は一般的な方法では静的に推論出来ないため、抽象基底クラスが拡張され、コンテナの要素に対して期待される型を示すために添字表記をサポートするようになりました。

from typing import Mapping, Sequence

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

ジェネリクスは TypeVar と呼ばれる typing で利用できる新しいファクトリを使ってパラメータ化することができます。

from typing import Sequence, TypeVar

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

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

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

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

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 は LoggedVar[t] が型として有効になるように __getitem__() を定義したメタクラスを利用します。

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)

Generic に用いられているメタクラスは abc.ABCMeta のサブクラスです。ジェネリッククラスは抽象メソッドや抽象プロパティを含めることで抽象基底クラスになれ、ジェネリッククラスはメタクラスの衝突を起こすことなく基底クラスに抽象基底クラスをとれます。ジェネリックメタクラスはサポートされません。パラメータ化を行うジェネリクスの結果はキャッシュされていて、 typing モジュールのほとんどの型はハッシュ化でき、等価比較できます。

26.1.6. `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 型の値をより詳細な型に代入する時に型検査が行われないことに注意してください。例えば、静的型検査器は a を s に代入する時、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 はすべての他の型のサブタイプでは ありません。

これは、ある値の型が 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 はある値が動的に型付けられることを示すために使用します。

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

このモジュールでは以下のクラス、関数とデコレータを定義します:

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> を使うことで上界を指定することが出来ます。これは、型変数に (明示的または非明示的に) 代入された実際の型が境界の型のサブクラスでなければならないということを意味します、PEP 484 も参照。

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.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 です。例えば次のようになります:

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

Type[Any] は Type と等価で、同様に Type は 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¶: 抽象メソッド __int__ を備えた ABC です。

class typing.SupportsFloat¶: 抽象メソッド __float__ を備えた ABC です。

class typing.SupportsComplex¶: 抽象メソッド __complex__ を備えた ABC です。

class typing.SupportsBytes¶: 抽象メソッド __bytes__ を備えた ABC です。

class typing.SupportsAbs¶: 返り値の型と共変な抽象メソッド __abs__ を備えた ABC です。

class typing.SupportsRound¶: 返り値の型と共変な抽象メソッド __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 で追加.

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 のジェネリック版です。

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.6.1 で追加.

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

list のジェネリック版です。返り値の型のアノテーションをつけることに便利です。引数にアノテーションをつけるためには、Mapping や Sequence 、 AbstractSet のような抽象コレクション型を使うことが好ましいです。

この型は以下のように使うことが出来ます:

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 のジェネリック版です。

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 のジェネリック版です。

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

class typing.AsyncIterable(Generic[T_co])¶: collections.abc.AsyncIterable のジェネリック版です。

class typing.AsyncIterator(AsyncIterable[T_co])¶: collections.abc.AsyncIterator のジェネリック版です。

class typing.ContextManager(Generic[T_co])¶: contextlib.AbstractContextManager のジェネリック版です。

バージョン 3.6 で追加.

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

dict のジェネリック版です。この型の使い方は以下の通りです:

def get_position_in_index(word_list: Dict[str, int], word: str) -> int:
    return word_list[word]

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])¶: collections.defaultdict のジェネリック版です。

バージョン 3.5.2 で追加.

class typing.Counter(collections.Counter, Dict[T, int])¶: collections.Counter のジェネリック版です。

バージョン 3.6.1 で追加.

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])¶: collections.ChainMap のジェネリック版です。

バージョン 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'

typing モジュールの多くの他のジェネリクスと違い 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 は反変的に振る舞います。

ジェネレータが値を yield するだけなら、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.5.4 で追加.

class typing.Text¶

Text は str のエイリアスです。これは Python 2 のコードの前方互換性を提供するために設けられています: Python 2 では Text は unicode のエイリアスです。

Text は Python 2 と Python 3 の両方と互換性のある方法で値が unicode 文字列を含んでいなければならない場合に使用してください。

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

バージョン 3.5.2 で追加.

class typing.io¶

I/O ストリーム型のためのラッパー名前空間です。

これはジェネリック型 IO[AnyStr] を定義し、そのサブクラス TextIO と BinaryIO をそれぞれ IO[str] と IO[bytes] からの派生型として定義します。これらは open() によって返されるような I/O ストリームの型を表します。

これらの型は typing.IO, typing.TextIO, typing.BinaryIO のように直接アクセスすることもできます。

class typing.re¶

正規表現のマッチング型のための名前空間です。

これは re.compile() と re.match() の返り値の型に対応する型エイリアス Pattern と Match を定義します。これらの型 (と対応する関数) は AnyStr についてジェネリックで、Pattern[str] や Pattern[bytes] 、 Match[str] 、 Match[bytes] のように書くことで具体的にすることが出来ます。

これらの型は typing.Pattern, typing.Match のように直接アクセスすることもできます。

class typing.NamedTuple¶

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

デフォルト値のあるフィールドはデフォルト値のないフィールドの後でなければなりません。

結果としてできるクラスは二つの追加の属性を持ちます。一つは _field_types で、フィールド名を型に結びつける辞書です。もう一つは _field_defaults で、フィールド名をデフォルト値に結びつける辞書です。 (フィールド名は namedtuple API の一つである _fields 属性にあります。)

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 で変更: デフォルト値、メソッド、ドキュメンテーション文字列への対応が追加されました。

typing.NewType(typ)¶

異なる型であることを型チェッカーに教えるためのヘルパー関数です。 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 については、 C.__mro__ の逆順に沿って全ての __annotations__ を合併して構築された辞書を返します。

@typing.overload¶

@overload デコレータを使うと、引数の型の複数の組み合わせをサポートする関数やメソッドを書けるようになります。 @overload 付きの定義を並べた後ろに、(同じ関数やメソッドの) @overload 無しの定義が来なければなりません。 @overload 付きの定義は型チェッカーのためでしかありません。というのも、 @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.no_type_check¶

アノテーションが型ヒントでないことを示すデコレータです。

これはクラス decorator または関数 decorator として動作します。クラス decorator として動作する場合は、そのクラス内に定義されたすべてのメソッドに対して再帰的に適用されます。（ただしスーパークラスやサブクラス内に定義されたメソッドには適用されません。）

これは関数を適切に変更します。

@typing.no_type_check_decorator¶

別のデコレータに no_type_check() の効果を与えるデコレータです。

これは何かの関数をラップするデコレータを no_type_check() でラップします。

typing.Any¶

制約のない型であることを示す特別な型。

任意の型は Any と互換です。
Any は任意の型と互換です。

typing.Union¶

ユニオン型; Union[X, Y] は X または Y を表します。

ユニオン型を定義します、例えば Union[int, str] のように使います。詳細:

引数は型でなければならず、少なくとも一つ必要です。
ユニオン型のユニオン型は平滑化されます。例えば:
```
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[int, object] == object
```
ユニオン型のサブクラスを作成したり、インスタンスを作成することは出来ません。
Union[X][Y] と書くことは出来ません。
Optional[X] を Union[X, None] の略記として利用することが出来ます。

typing.Optional¶

オプショナル型。

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

これがデフォルト値のある引数であるオプショナル引数と同じ概念ではないと言うことに注意してください。デフォルト値のあるオプショナル引数ではその型アノテーションで Optional を使う必要はありません (ただしデフォルトでは None と推論されます)。必須の引数は明示的な値として None が許されるのであれば Optional 型も持つことが出来ます。

typing.Tuple¶

タプル型; Tuple[X, Y] は、最初の要素の型が X で、2つ目の要素の型が Y であるような、2つの要素を持つタプルの型です。

例: Tuple[T1, T2] は型変数 T1 と T2 に対応する2つの要素を持つタプルです。Tuple[int, float, str] は int と float、 string のタプルです。

同じ型の任意の長さのタプルを指定するには ellipsis リテラルを用います。例: Tuple[int, ...]。ただの Tuple は Tuple[Any, ...] と等価で、さらに tuple と等価です。.

typing.Callable¶

呼び出し可能型; Callable[[int], str] は (int) -> str の関数です。

添字表記は常に2つの値とともに使われなければなりません: 実引数のリストと返り値の型です。実引数のリストは型のリストか ellipsis でなければなりません; 返り値の型は単一の型でなければなりません。

オプショナル引数やキーワード引数を表すための文法はありません; そのような関数型はコールバックの型として滅多に使われません。 Callable[..., ReturnType] (リテラルの Ellipsis) は任意の個数の引数をとり ReturnType を返す型ヒントを与えるために使えます。普通の Callable は Callable[..., Any] と同等で、 collections.abc.Callable でも同様です。

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.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()

1つ目の型アノテーションは引用符で囲って "前方参照 (forward reference)" にし、インタプリタのランタイムから expensive_mod への参照を隠さなければなりません。ローカル変数への型アノテーションは評価されないので、2つ目のアノテーションは引用符で囲う必要はありません。

バージョン 3.5.2 で追加.

26.1. `typing` — 型ヒントのサポート¶

26.1.1. 型エイリアス¶

26.1.2. NewType¶

26.1.3. 呼び出し可能オブジェクト¶

26.1.4. ジェネリクス¶

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

26.1.6. `Any` 型¶

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

目次

前のトピックへ

次のトピックへ

このページ

26.1. typing — 型ヒントのサポート¶

26.1.1. 型エイリアス¶

26.1.2. NewType¶

26.1.3. 呼び出し可能オブジェクト¶

26.1.4. ジェネリクス¶

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

26.1.6. Any 型¶

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

26.1. `typing` — 型ヒントのサポート¶

26.1.6. `Any` 型¶