`typing` — 형 힌트 지원¶

Added in version 3.5.

참고

Python 런타임은 함수와 변수의 형 어노테이션을 강제하지 않습니다. 이들은 정적 형 검사기 와 같은 서드파티 도구, IDE, 린터 등에서 사용될 수 있습니다.

이 모듈은 형 힌트에 대한 런타임 지원을 제공합니다.

다음 함수를 고려해 보십시오:

def surface_area_of_cube(edge_length: float) -> str:
    return f"The surface area of the cube is {6 * edge_length ** 2}."

함수 surface_area_of_cube 는 type hint edge_length: float 에 명시된 대로 float 의 인스턴스가 될 것으로 예상되는 인수를 받습니다. 이 함수는 -> str 힌트에 명시된 바와 같이 str 의 인스턴스를 반환할 것으로 예상됩니다.

While type hints can be simple classes like float or str, they can also be more complex. The typing module provides a vocabulary of more advanced type hints.

typing 모듈에는 새로운 기능이 자주 추가됩니다. typing_extensions 패키지는 이러한 새 기능들을 이전 버전의 파이썬에서도 사용할 수 있도록 백포트합니다.

형 힌트 치트 시트: 형 힌트에 대한 빠른 개요 (mypy 문서에서 제공)
mypy 문항(10) 중 형 시스템 참조 섹션: 파이썬 형 시스템은 PEP를 통해 표준화되므로, 이 참조는 대부분의 파이썬 정적 형 검사기에 광범위하게 적용됩니다. (일부 항목은 여전히 mypy 전용일 수 있습니다.)
Python을 사용한 정적 타이핑: 형 시스템 기능, 유용한 형 관련 도구 및 형 관련 모범 사례를 상세히 설명하며 특정 형 검사기에 종속되지 않는 커뮤니티 작성 문서입니다.

파이썬 형 시스템 사양¶

파이썬 형 시스템의 공식적이고 최신화된 사양은 파이썬 형 시스템에 관한 명세 <https://typing.python.org/en/latest/spec/index.html> 에서 확인할 수 있습니다.

형 에일리어스¶

형 에일리어스는 type 문을 사용하여 정의하며, 이는 TypeAliasType 의 인스턴스를 생성합니다. 이 예제에서 Vector 와 list[float] 은 정적 형 검사기에 의해 동일하게 취급됩니다:

type Vector = list[float]

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

# 형 검증 통과; float의 리스트는 Vector로 인정됨.
new_vector = scale(2.0, [1.0, -4.2, 5.4])

형 에일리어스는 복잡한 형 서명을 단순화하는 데 유용합니다. 예를 들면:

from collections.abc import Sequence

type ConnectionOptions = dict[str, str]
type Address = tuple[str, int]
type Server = tuple[Address, ConnectionOptions]

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

# 정적 형 검사기는 이전형 서명을 다음 것과 정확히 동일하게 처리합니다.
def broadcast_message(
    message: str,
    servers: Sequence[tuple[tuple[str, int], dict[str, str]]]
) -> None:
    ...

type 문은 파이썬 3.12에서 새로 도입되었습니다. 하위 호환성을 위해 형 에일리어스는 단순 할당을 통해서도 생성할 수 있습니다:

Vector = list[float]

또는 이것이 일반적인 변수 할당이 아니라 형 에일리어스임을 명시적으로 표시하기 위해 TypeAlias 로 표시할 수 있습니다:

from typing import TypeAlias

Vector: TypeAlias = list[float]

NewType¶

별개의 형을 생성하려면 NewType 헬퍼를 사용하십시오:

from typing import NewType

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

정적 형 검사기는 새 형을 원래 형의 서브 클래스인 것처럼 다룹니다. 논리 에러를 잡는 데 유용합니다:

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

# 형 검증 통과
user_a = get_user_name(UserId(42351))

# 형 검증 실패; int는 UserId가 아님
user_b = get_user_name(-1)

UserId 형의 변수에 대해 모든 int 연산을 여전히 수행할 수 있지만, 결과는 항상 int 형이 됩니다. 이것은 int가 기대되는 모든 곳에 UserId를 전달할 수 있지만, 잘못된 방식으로 의도하지 않게 UserId를 만들지 않도록 합니다:

# 'output'은 'UserId'가 아닌 'int' 형임
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)

# 런타임에서 실패하며 형 검증을 통과하지 못함
class AdminUserId(UserId): pass

However, it is possible to create a NewType based on a ‘derived’ NewType:

from typing import NewType

UserId = NewType('UserId', int)

ProUserId = NewType('ProUserId', UserId)

그리고 ProUserId에 대한 형 검사는 예상대로 작동합니다.

자세한 내용은 PEP 484를 참조하십시오.

참고

형 에일리어스를 사용하면 두 형이 서로 동등함*을 선언하게 됩니다. ``type Alias = Original``을 수행하면 정적 형 검사기가 모든 경우에서 ``Alias``를 ``Original``과 *정확히 동일한 것으로 취급합니다. 이는 복잡한 형 서명을 단순화하고 싶을 때 유용합니다.

반면에, NewType은 한 형을 다른 형의 서브 형으로 선언합니다. Derived = NewType('Derived', Original)은 정적 형 검사기가 Derived를 Original의 서브 클래스로 취급하게 합니다. 이는 Original 형의 값이 Derived 형의 값이 예상되는 위치에서 사용될 수 없음을 의미합니다. 실행 시간 비용을 최소화하면서 논리 에러를 방지하려는 경우에 유용합니다.

Added in version 3.5.2.

버전 3.10에서 변경: NewType 은 이제 함수가 아닌 클래스입니다. 그 결과, NewType 을 호출할 때 일반적인 함수에 비해 약간의 추가적인 런타임 비용이 발생합니다.

버전 3.11에서 변경: NewType 호출 성능이 파이썬 3.9 수준으로 복원되었습니다.

콜러블 객체 어노테이션¶

함수 또는 기타 callable 객체는 collections.abc.Callable 이나 사용이 중단된 typing.Callable 을 사용하여 어노테이션할 수 있습니다. Callable[[int], str] 은 int 타입의 단일 파라미터를 받고 str 을 반환하는 함수를 의미합니다.

예:

from collections.abc import Callable, Awaitable

def feeder(get_next_item: Callable[[], str]) -> None:
    ...  # 본문

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

async def on_update(value: str) -> None:
    ...  # 본문

callback: Callable[[str], Awaitable[None]] = on_update

서브스크립션 구문은 항상 인자 목록과 반환형이라는 정확히 두 개의 값과 함께 사용되어야 합니다. 인자 목록은 타입의 리스트, ParamSpec, Concatenate 또는 생략 부호(...)여야 하며, 반환형은 단일 타입이어야 합니다.

인자 목록으로 리터럴 생략 부호 ... 가 주어지면, 임의의 매개변수 목록을 가진 콜러블이 허용됨을 나타냅니다.

def concat(x: str, y: str) -> str:
    return x + y

x: Callable[..., str]
x = str     # OK
x = concat  # Also OK

Callable 은 가변 수의 인자를 받는 함수, 오버로드된 함수, 또는 키워드 전용 매개변수를 가진 함수와 같은 복잡한 서명을 표현할 수 없습니다. 하지만 이러한 서명은 __call__() 메서드를 가진 Protocol 클래스를 정의함으로써 표현할 수 있습니다.

from collections.abc import Iterable
from typing import Protocol

class Combiner(Protocol):
    def __call__(self, *vals: bytes, maxlen: int | None = None) -> list[bytes]: ...

def batch_proc(data: Iterable[bytes], cb_results: Combiner) -> bytes:
    for item in data:
        ...

def good_cb(*vals: bytes, maxlen: int | None = None) -> list[bytes]:
    ...
def bad_cb(*vals: bytes, maxitems: int | None) -> list[bytes]:
    ...

batch_proc([], good_cb)  # OK
batch_proc([], bad_cb)   # Error! Argument 2 has incompatible type because of
                         # different name and kind in the callback

다른 콜러블을 인자로 받는 콜러블은 ParamSpec 을 사용하여 매개변수 타입이 서로 의존함을 나타낼 수 있습니다. 또한 해당 콜러블이 다른 콜러블로부터 인자를 추가하거나 제거하는 경우 Concatenate 연산자를 사용할 수 있습니다. 이들은 각각 Callable[ParamSpecVariable, ReturnType] 및 Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType] 형식을 취합니다.

버전 3.10에서 변경: Callable 이 이제 ParamSpec 과 Concatenate 를 지원합니다. 자세한 내용은 PEP 612 을 참조하십시오.

ParamSpec 및 Concatenate 의 문서는 Callable 에서의 사용 예시를 제공합니다.

제네릭¶

컨테이너에 포함된 객체에 대한 형 정보를 일반적인 방식으로 정적으로 추론할 수 없으므로, 표준 라이브러리의 많은 컨테이너 클래스들은 컨테이너 요소의 예상 형을 나타내기 위해 서브스크립션을 지원합니다.

from collections.abc import Mapping, Sequence

class Employee: ...

# Sequence[Employee]는 시퀀스의 모든 요소가
# "Employee"의 인스턴스여야 함을 나타냅니다.
# Mapping[str, str]은 매핑의 모든 키와 값이
# 문자열이어야 함을 나타냅니다.
def notify_by_email(employees: Sequence[Employee],
                    overrides: Mapping[str, str]) -> None: ...

제네릭 함수와 클래스는 형 매개변수 구문 를 사용하여 매개변수화할 수 있습니다:

from collections.abc import Sequence

def first[T](l: Sequence[T]) -> T:  # 함수가 형 변수 "T"에 대해 제네릭임
    return l[0]

또는 TypeVar 팩토리를 직접 사용하여 구현할 수 있습니다:

from collections.abc import Sequence
from typing import TypeVar

U = TypeVar('U')                  # 형 변수 "U" 선언

def second(l: Sequence[U]) -> U:  # 함수가 형 변수 "U"에 대해 제네릭임
    return l[1]

버전 3.12에서 변경: 제네릭을 위한 구문적 지원은 Python 3.12에서 새로 도입되었습니다.

튜플 어노테이션¶

Python의 대부분 컨테이너에 대해 형 시스템은 컨테이너의 모든 요소가 동일한 형일 것이라고 가정합니다. 예를 들면:

from collections.abc import Mapping

# 형 검사기는 ``x``의 모든 요소가 int임을 추론합니다
x: list[int] = []

# 형 검사기 오류: ``list``는 단일 형 인자만 허용합니다:
y: list[int, str] = [1, 'foo']

# 형 검사기는 ``z``의 모든 키가 문자열이며,
# 모든 값이 문자열 또는 int라고 추론합니다
z: Mapping[str, str | int] = {}

list 은 단 하나의 형 인자만 허용하므로, 위의 y 할당에서 형 검사기가 오류를 발생시킵니다. 마찬가지로, Mapping 은 두 개의 형 인자만 허용하며, 첫 번째는 키의 형을, 두 번째는 값의 형을 나타냅니다.

그러나 다른 대부분의 Python 컨테이너와 달리, 관용적인(idiomatic) Python 코드에서 튜플은 요소들이 모두 동일한 형이 아니어도 되는 경우가 흔합니다. 이러한 이유로 파이썬의 형 시스템에서는 튜플을 특별하게 처리합니다. tuple 은 어떤 수의 형 인자도 허용합니다:

# OK: ``x``가 요소가 하나인(타입이 int) 길이가 1인 튜플에 할당됨
x: tuple[int] = (5,)

# OK: ``y``가 길이가 2인 튜플에 할당됨;
# 첫 번째 요소는 int, 두 번째 요소는 str
y: tuple[int, str] = (5, "foo")

# Error: 타입 어노테이션은 길이가 1인 튜플을 나타내지만,
# ``z``는 길이가 3인 튜플에 할당됨
z: tuple[int] = (1, 2, 3)

모든 요소가 동일한 형 T 이며 길이가 무엇이든 될 수 있는 튜플을 나타내려면 리터럴 생략 부호 ... 를 사용하십시오. 빈 튜플을 나타내려면 tuple[()] 를 사용하십시오. 어노테이션으로 일반적인 tuple 을 사용하는 것은 tuple[Any, ...] 를 사용하는 것과 동일합니다:

x: tuple[int, ...] = (1, 2)
# 다음 재할당은 허용됩니다. ``tuple[int, ...]``는 x가 어떤 길이든 될 수 있음을 나타냅니다.
x = (1, 2, 3)
x = (\)
# 이 재할당은 오류입니다. ``x``의 모든 요소는 int여야 합니다.
x = ("foo", "bar")

# ``y``는 빈 튜플에만 할당될 수 있습니다.
y: tuple[()] = (\)

z: tuple = ("foo", "bar")
# 다음 재할당은 허용됩니다. 일반적인 ``tuple``은 ``tuple[Any, ...]``와 동일합니다.
z = (1, 2, 3)
z = ()

클래스 객체의 형¶

C 로 어노테이션된 변수는 C 형의 값을 수용할 수 있습니다. 반면, type[C] (또는 사용이 권장되지 않는 typing.Type[C])로 어노테이션된 변수는 클래스 자체인 값, 즉 C 의 클래스 객체 를 수용할 수 있습니다. 예를 들면:

a = 3         # 형이 ``int``임
b = int       # 형이 ``type[int]``임
c = type(a)   # 역시 형이 ``type[int]``임

type[C] 가 공변적(covariant)임을 유의하십시오:

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

def make_new_user(user_class: type[User]) -> User:
    # ...
    return user_class()

make_new_user(User)      # OK
make_new_user(ProUser)   # 또한 허용됨: ``type[ProUser]``는 ``type[User]``의 하위 형입니다.
make_new_user(TeamUser)  # 여전히 문제없음
make_new_user(User())    # 오류: ``type[User]``를 기대했지만 ``User``가 전달됨
make_new_user(int)       # 오류: ``type[int]``는 ``type[User]``의 하위 형이 아닙니다.

type 에 허용되는 매개변수는 클래스, Any, 형 변수, 그리고 이러한 형들의 합집합(union)뿐입니다. 예를 들면:

def new_non_team_user(user_class: type[BasicUser | ProUser]): ...

new_non_team_user(BasicUser)  # OK
new_non_team_user(ProUser)    # OK
new_non_team_user(TeamUser)   # 오류: ``type[TeamUser]``이 ``type[BasicUser | ProUser]``의 하위 형이 아님
                              #
new_non_team_user(User)       # 또한 오류임

type[Any] 는 파이썬의 메타클래스 계층 의 루트인 type 과 동일합니다.

제너레이터 및 코루틴 어노테이션¶

제너레이터는 제네릭 형인 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 은 공변적(covariant)이나 불변(invariant)이 아닌 반변적(contravariant)으로 동작합니다.

SendType 및 ReturnType 매개변수의 기본값은 None 입니다:

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

이러한 형들을 명시적으로 설정하는 것도 가능합니다:

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

값만 생성(yield)하는 단순한 제너레이터의 경우, 반환 형을 Iterable[YieldType] 또는 Iterator[YieldType] 로 어노테이션할 수도 있습니다:

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

비동기 제너레이터도 유사한 방식으로 처리되지만, ReturnType 형 인자는 기대되지 않습니다(AsyncGenerator[YieldTye, SendType]). SendType 인자의 기본값은 None 이므로 다음 정의들은 서로 동등합니다:

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

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)

코루틴은 Coroutine[YieldType, SendType, ReturnType] 을 사용하여 어노테이션할 수 있습니다. 제네릭 인자는 다음이 예시입니다: coroutine 의 사례와 동일하게 Generator 의 인수들과 대응합니다:

from collections.abc import Coroutine
c: Coroutine[list[str], str, int]  # 다른 곳에서 정의된 일부 코루틴
x = c.send('hi')                   # 'x'의 추론 형은 list[str]
async def bar() -> None:
    y = await c                    # 'y'의 추론 형은 int

사용자 정의 제네릭 형¶

사용자 정의 클래스는 제네릭 클래스로 정의 할 수 있습니다.

from logging import Logger

class LoggedVar[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)

이 구문은 LoggedVar 클래스가 단일 형 변수 인 T 를 중심으로 매개 변수화되었음을 나타냅니다. 이는 또한 T 가 클래스 내부에서 유효한 유형임을 의미합니다.

제네릭 클래스는 Generic 을 암시적으로 상속합니다. Python 3.11 이하 버전과의 호환성을 위해, 제네릭 클래스임을 나타내기 위해 Generic 을 명시적으로 상속하는 것도 가능합니다:

from typing import TypeVar, Generic

T = TypeVar('T')

class LoggedVar(Generic[T]):
    ...

제네릭 클래스는 __class_getitem__() 메서드를 가지므로, 실행 시점에 매개변수화할 수 있습니다(예: 아래의 LoggedVar[int]):

from collections.abc import Iterable

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

제네릭 형은 임의의 개수의 타입 변수를 가질 수 있습니다. 모든 종류의 TypeVar 를 제네릭 형의 매개변수로 사용할 수 있습니다:

from typing import TypeVar, Generic, Sequence

class WeirdTrio[T, B: Sequence[bytes], S: (int, str)]:
    ...

OldT = TypeVar('OldT', contravariant=True)
OldB = TypeVar('OldB', bound=Sequence[bytes], covariant=True)
OldS = TypeVar('OldS', int, str)

class OldWeirdTrio(Generic[OldT, OldB, OldS]):
    ...

Generic에 대한 각 형 변수 인자는 달라야 합니다. 그래서 이것은 잘못되었습니다:

from typing import TypeVar, Generic
...

class Pair[M, M]:  # SyntaxError
    ...

T = TypeVar('T')

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

제네릭 클래스는 다른 클래스도 상속할 수 있습니다:

from collections.abc import Sized

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

제네릭 클래스를 상속할 때, 일부 타입 매개변수를 고정할 수도 있습니다:

from collections.abc import Mapping

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

이 경우 MyDict는 단일 매개 변수 T를 갖습니다.

제네릭 클래스를 사용하면서 타입 매개변수를 지정하지 않으면 각 위치를 Any 로 가정합니다. 다음 예제에서 MyIterable 은 제네릭이 아니지만 Iterable[Any] 를 암시적으로 상속합니다:

from collections.abc import Iterable

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

사용자가 정의한 제네릭 타입 에일리어스도 지원됩니다. 예시:

from collections.abc import Iterable

type Response[S] = Iterable[S] | int

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

type Vec[T] = Iterable[tuple[T, T]]

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

하위 호환성을 위해 단순 할당을 통해 제네릭 타입 에일리어스를 생성할 수도 있습니다:

from collections.abc import Iterable
from typing import TypeVar

S = TypeVar("S")
Response = Iterable[S] | int

버전 3.7에서 변경: Generic에는 더는 사용자 정의 메타 클래스가 없습니다.

버전 3.12에서 변경: 제네릭 및 타입 에일리어스에 대한 구문 지원은 3.12 버전부터 도입되었습니다. 이전에는 제네릭 클래스가 Generic 을 명시적으로 상속하거나 기본 클래스 중 하나에 타입 변수를 포함해야 했습니다.

매개변수 표현을 위한 사용자 정의 제네릭은 [**P] 형태의 매개변수 지정 변수를 통해 지원됩니다. 이 동작은 앞서 설명한 타입 변수의 동작과 일치합니다. 해당 매개변수들은 typing 모듈에서 특수한 타입 변수로 취급되기 때문입니다. 유일한 예외는 타입 리스트가 ParamSpec 을 대체하는 데 사용될 수 있다는 점입니다:

>>> class Z[T, **P]: ...  # T is a TypeVar; P is a ParamSpec
...
>>> Z[int, [dict, float]]
__main__.Z[int, [dict, float]]

ParamSpec 에 대한 제네릭 클래스는 Generic 을 명시적으로 상속하여 생성할 수도 있습니다. 이 경우 ** 는 사용되지 않습니다:

from typing import ParamSpec, Generic

P = ParamSpec('P')

class Z(Generic[P]):
    ...

TypeVar 와 ParamSpec 의 또 다른 차이점은, 단 하나의 매개변수 지정 변수만 가진 제네릭의 경우 미관상의 이유로 X[[Type1, Type2, ...]] 및 X[Type1, Type2, ...] 형태의 매개변수 리스트를 모두 수용한다는 점입니다. 내부적으로 후자는 전자로 변환되므로 다음은 동일하게 처리됩니다:

>>> class X[**P]: ...
...
>>> X[int, str]
__main__.X[[int, str]]
>>> X[[int, str]]
__main__.X[[int, str]]

ParamSpec 을 사용하는 제네릭은 주로 정적 타입 검사를 목적으로 하기에, 어떤 경우에는 치환 후에도 올바른 __parameters__ 를 가지지 않을 수 있음에 유의하십시오.

버전 3.10에서 변경: Generic 은 이제 매개변수 표현에 대해 매개변수화될 수 있습니다. 자세한 내용은 ParamSpec 과 PEP 612 를 참조하십시오.

사용자 정의 제네릭 클래스는 메타클래스 충돌 없이 ABC를 베이스 클래스로 가질 수 있습니다. 제네릭 메타클래스는 지원되지 않습니다. 제네릭 매개변수화 결과는 캐시되며, typing 모듈의 대부분 타입은 hashable 이며 동등성 비교가 가능합니다.

`Any` 형¶

특별한 종류의 형으로 Any 가 있습니다. 정적 타입 검사기는 모든 형을 Any 로 할당 가능한 것으로 처리하며, Any 를 모든 형에 할당 가능한 것으로 취급합니다.

이것은 Any 형의 값에 대해 어떤 연산이나 메서드 호출을 수행하고, 그것을 임의의 변수에 대입할 수 있다는 것을 의미합니다:

from typing import Any

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

s: str = ''
s = a           # OK

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

Any 유형의 값을 더 구체적인 타입으로 할당할 때는 타입 검사가 수행되지 않음에 유의하십시오. 예를 들어, 정적 타입 검사기는 s 가 str 로 선언되고 런타임에서 int 값을 받음에도 불구하고 a 를 s 에 할당할 때 오류를 보고하지 않았습니다.

또한, 반환형이나 매개 변수 형이 없는 모든 함수는 묵시적으로 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 type checking; an object does not have a 'magic' method.
    item.magic()
    ...

def hash_b(item: Any) -> int:
    # Passes type checking
    item.magic()
    ...

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

# Passes type checking, since Any is assignable to all types
hash_b(42)
hash_b("foo")

값이 형 안전한 방식으로 모든 형이 될 수 있음을 표시하려면 object를 사용하십시오. 값이 동적으로 형이 지정됨을 표시하려면 Any를 사용하십시오.

명목적 대 구조적 서브 타이핑¶

초기에 PEP 484 는 파이썬 정적 타입 시스템이 명칭 기반 서브타이핑(nominal subtyping) 을 사용하도록 정의했습니다. 이는 클래스 A 가 클래스 B 를 대신할 수 있는 조건이 오직 A 가 B 의 서브클래스일 때만 성립함을 의미합니다.

이 요구 사항은 이전에 Iterable과 같은 추상 베이스 클래스에도 적용되었습니다. 이 접근 방식의 문제점은 이것을 지원하려면 클래스를 명시적으로 표시해야만 한다는 점입니다. 이는 파이썬답지 않고 관용적인 동적으로 형이 지정된 파이썬 코드에서 일반적으로 수행하는 것과는 다릅니다. 예를 들어, 이것은 PEP 484를 만족합니다:

from collections.abc import Sized, Iterable, Iterator

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

PEP 544 는 사용자가 클래스 정의에 명시적인 베이스 클래스 없이 위와 같은 코드를 작성할 수 있게 함으로써 이 문제를 해결하며, 이를 통해 정적 타입 검사기가 Bucket 을 Sized 및 Iterable[int] 의 서브 타입으로 묵시적으로 간주하게 합니다. 이는 구조적 서브타이핑(structural subtyping) (또는 정적 덕 타이핑)으로 알려져 있습니다:

from collections.abc 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을 서브 클래싱 함으로써, 사용자는 새로운 사용자 정의 프로토콜을 정의하여 구조적 서브 타이핑을 완전히 누릴 수 있습니다 (아래 예를 참조하십시오).

모듈 내용¶

typing 모듈은 다음 클래스, 함수 및 데코레이터를 정의합니다.

특수 타이핑 프리미티브¶

특수형¶

이들은 어노테이션에서 형으로 사용될 수 있습니다. [] 를 이용한 인덱싱은 지원하지 않습니다.

typing.Any¶

제한되지 않는 형을 나타내는 특수형.

모든 형은 Any 에 할당 가능합니다.
Any 는 모든 형에 할당 가능합니다.

버전 3.11에서 변경: Any 를 베이스 클래스로 사용할 수 있습니다. 이는 어디에서나 덕 타이핑이 가능하거나 매우 동적인 클래스에서 타입 검사기 오류를 피하는 데 유용할 수 있습니다.

typing.AnyStr¶

A constrained type variable.

정의:

AnyStr = TypeVar('AnyStr', str, bytes)

AnyStr 는 str 또는 bytes 인자를 수용할 수 있지만 두 형을 섞어서 사용할 수는 없는 함수에서 사용하기 위해 만들어졌습니다.

예를 들면:

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

concat("foo", "bar")    # OK, output has type 'str'
concat(b"foo", b"bar")  # OK, output has type 'bytes'
concat("foo", b"bar")   # Error, cannot mix str and bytes

이름에도 불구하고 AnyStr 은 Any 형과 아무런 관련이 없으며, “모든 문자열”을 의미하지도 않습니다. 특히, AnyStr 과 str | bytes 는 서로 다르며 서로 다른 사용 사례를 가집니다:

잘못된 AnyStr 사용 사례:
# 함수 시그니처에서 형 변수가 단 한 번만 사용되므로,
# 타입 검사기에 의해 "해결"될 수 없습니다
def greet_bad(cond: bool) -> AnyStr:
    return "hi there!" if cond else b"greetings!"

# 이 함수를 어노테이션하는 더 나은 방법:
def greet_proper(cond: bool) -> str | bytes:
    return "hi there!" if cond else b"greetings!"

버전 3.13부터 사용 지원 중단(deprecated), 버전 3.18에서 제거 예정: 새로운 형 매개변수 문법 을 위해 Deprecated되었습니다. AnyStr 을 임포트하는 대신 class A[T: (str, bytes)]: ... 를 사용하십시오. 자세한 내용은 PEP 695 를 참조하십시오.

파이썬 3.16에서 AnyStr 은 typing.__all__ 에서 제거되며, typing 에서 접근하거나 임포트할 때 런타임에 경고가 발생합니다. AnyStr 은 파이썬 3.18에서 typing 에서 완전히 제거됩니다.

typing.LiteralString¶

리터럴 문자열만 포함하는 특수 형입니다.

어떤 문자열 리터럴도 LiteralString 과 호환되며, 다른 LiteralString 도 마찬가지입니다. 그러나 단지 str 로만 타입이 지정된 객체는 호환되지 않습니다. LiteralString 유형의 객체들을 결합하여 생성된 문자열 또한 LiteralString 으로 허용됩니다.

예제:

def run_query(sql: LiteralString) -> None:
    ...

def caller(arbitrary_string: str, literal_string: LiteralString) -> None:
    run_query("SELECT * FROM students")  # OK
    run_query(literal_string)  # OK
    run_query("SELECT * FROM " + literal_string)  # OK
    run_query(arbitrary_string)  # type checker error
    run_query(  # type checker error
        f"SELECT * FROM students WHERE name = {arbitrary_string}"
    )

LiteralString 은 사용자가 생성한 임의의 문자열이 문제를 일으킬 수 있는 민감한 API에 유용합니다. 예를 들어, 위에서 타입 검사 오류를 발생시킨 두 사례는 SQL 인젝션 공격에 취약할 수 있습니다.

자세한 내용은 PEP 675 를 참조하십시오.

Added in version 3.11.

typing.Never¶

typing.NoReturn¶

Never 와 NoReturn 은 어떤 멤버도 가지지 않는 형인 bottom type <https://en.wikipedia.org/wiki/Bottom_type> 를 나타냅니다.

이들은 sys.exit() 과 같이 함수가 절대 반환되지 않음을 나타낼 때 사용될 수 있습니다:

from typing import Never  # 또는 NoReturn

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

또는 유효한 인자가 없어 결코 호출되어서는 안 되는 함수를 정의할 때 사용할 수 있습니다. 예: assert_never():

from typing import Never  # 또는 NoReturn

def never_call_me(arg: Never) -> None:
    pass

def int_or_str(arg: int | str) -> None:
    never_call_me(arg)  # type checker error
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _:
            never_call_me(arg)  # OK, arg는 Never (또는 NoReturn) 형입니다

Never`와 :data:!NoReturn`은 타입 시스템에서 동일한 의미를 가지며 정적 타입 검사기에서도 동일하게 취급됩니다.

Added in version 3.6.2: NoReturn 이 추가되었습니다.

Added in version 3.11: Never 이 추가되었습니다.

typing.Self¶

현재 감싸고 있는 클래스를 나타내는 특수 형입니다.

예를 들면:

from typing import Self, reveal_type

class Foo:
    def return_self(self) -> Self:
        ...
        return self

class SubclassOfFoo(Foo): pass

reveal_type(Foo().return_self())  # Revealed type is "Foo"
reveal_type(SubclassOfFoo().return_self())  # Revealed type is "SubclassOfFoo"

이 어노테이션은 의미상 다음과 동일하지만, 더 간결한 표현 방식입니다:

from typing import TypeVar

Self = TypeVar("Self", bound="Foo")

class Foo:
    def return_self(self: Self) -> Self:
        ...
        return self

일반적으로 위 예시와 같이 무언가가 self``를 반환하는 경우, 반환 어노테이션으로 ``Self``를 사용해야 합니다. 만약 ``Foo.return_self``가 ``"Foo"``를 반환하는 것으로 어노테이션되었다면, 타입 검사기는 ``SubclassOfFoo.return_self``에서 반환되는 객체를 ``SubclassOfFoo 대신 Foo 유형으로 추론할 것입니다.

기타 일반적인 사용 사례는 다음과 같습니다:

대체 생성자로 사용되고 cls 매개변수의 인스턴스를 반환하는 classmethod.
self를 반환하는 __enter__() 메서드를 어노테이션할 때.

클래스가 하위 클래스로 확장될 때 해당 메서드가 반드시 하위 클래스의 인스턴스를 반환한다는 보장이 없는 경우 Self 를 반환 어노테이션으로 사용해서는 안 됩니다:

class Eggs:
    # 여기서는 ``Self``가 잘못된 반환 어노테이션입니다.
    # 왜냐하면 하위 클래스에서도 결과 객체는 항상 Eggs의 인스턴스이기 때문입니다.
    def returns_eggs(self) -> "Eggs":
        return Eggs()

자세한 내용은 PEP 673 을 참조하십시오.

Added in version 3.11.

typing.TypeAlias¶

Special annotation for explicitly declaring a type alias.

예를 들면:

from typing import TypeAlias

Factors: TypeAlias = list[int]

TypeAlias 는 이전 버전의 Python에서 포워드 참조(forward reference)를 사용하는 에일리어스를 어노테이션할 때 특히 유용합니다. 타입 검사기가 이를 일반적인 변수 할당과 구분하기 어려울 수 있기 때문입니다.

from typing import Generic, TypeAlias, TypeVar

T = TypeVar("T")

# "Box"가 아직 존재하지 않으므로,
# Python 3.12 미만 버전에서는 포워드 참조를 위해 따옴표를 사용해야 합니다.
# ``TypeAlias``를 사용하면 타입 검사기에게 이것이 변수 할당이 아니라
# 타입 에일리어스 선언임을 알릴 수 있습니다.
BoxOfStrings: TypeAlias = "Box[str]"

class Box(Generic[T]):
    @classmethod
    def make_box_of_strings(cls) -> BoxOfStrings: ...

자세한 내용은 PEP 613 을 참조하십시오.

Added in version 3.10.

버전 3.12부터 폐지됨: TypeAlias 는 TypeAliasType 의 인스턴스를 생성하고 포워드 참조를 네이티브로 지원하는 type 문으로 대체되어 더 이상 권장되지 않습니다. TypeAlias 와 TypeAliasType 은 목적과 이름이 유사하지만 서로 다른 것이며, 후자는 전자의 타입이 아닙니다. TypeAlias 의 제거는 현재 계획되어 있지 않으나, 사용자는 type 문으로 마이그레이션하는 것을 권장합니다.

특수 형태¶

이것들은 어노테이션에서 타입으로 사용될 수 있습니다. 모두 [] 를 사용하여 인덱싱(subscription)을 지원하지만 각각 고유한 구문을 가집니다.

class typing.Union¶

Union 타입; Union[X, Y] 는 X | Y 와 동일하며 X 또는 Y 중 하나임을 의미합니다.

유니언을 정의하려면 예로 Union[int, str] 또는 약어인 int | str 를 사용하십시오. 약어 사용이 권장됩니다. 세부 사항:

인자는 형이어야 하며 적어도 하나 있어야 합니다.
공용체의 공용체는 펼쳐집니다, 예를 들어:
```
Union[Union[int, str], float] == Union[int, str, float]
```
그러나 이는 기반이 되는 TypeAliasType 의 평가를 강제하지 않기 위해 타입 에일리어스를 통해 참조되는 유니언에는 적용되지 않습니다:
```
type A = Union[int, str]
Union[A, float] != Union[int, str, float]
```

단일 인자의 공용체는 사라집니다. 예를 들어:

Union[int] == int  # 생성자는 실제로 int를 반환합니다

중복 인자는 건너뜁니다. 예를 들어:

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

공용체를 비교할 때, 인자 순서가 무시됩니다, 예를 들어:
```
Union[int, str] == Union[str, int]
```
Union 을 서브 클래싱하거나 인스턴스화할 수 없습니다.
Union[X][Y]라고 쓸 수 없습니다.

버전 3.7에서 변경: 실행 시간에 공용체의 명시적 서브 클래스를 제거하지 않습니다.

버전 3.10에서 변경: 유니언을 이제 X | Y 로 작성할 수 있습니다. union type expressions 를 참조하십시오.

버전 3.14에서 변경: types.UnionType is now an alias for Union, and both Union[int, str] and int | str create instances of the same class. To check whether an object is a Union at runtime, use isinstance(obj, Union). For compatibility with earlier versions of Python, use get_origin(obj) is typing.Union or get_origin(obj) is types.UnionType.

typing.Optional¶

Optional[X]``는 ``X | None``(또는 ``Union[X, None])와 동일합니다.

이는 기본값을 갖는 선택적 인자와 같은 개념이 아님에 유의하십시오. 단지 선택적이기 때문에 기본값을 갖는 선택적 인자가 형 어노테이션에 Optional 한정자가 필요하지는 않습니다. 예를 들면:

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

한편, 명시적인 None 값이 허용되면, 인자가 선택적인지와 관계없이 Optional을 사용하는 것이 적합합니다. 예를 들면:

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

버전 3.10에서 변경: Optional을 이제 X | None 으로 작성할 수 있습니다. union type expressions 를 참조하십시오.

typing.Concatenate¶

고차 함수(higher-order functions)를 어노테이션하기 위한 특수 형태입니다.

Concatenate 는 Callable 및 ParamSpec 과 함께 사용하여 다른 호출 가능(callable) 객체의 파라미터를 추가, 제거 또는 변환하는 고차 호출 가능 객체를 어노테이션하는 데 사용될 수 있습니다. 사용 형태는 Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable] 입니다. Concatenate 는 Callable 타입 힌트에서 사용하거나, ParamSpec 파라미터를 가진 사용자 정의 제네릭 클래스를 인스턴스화할 때 사용할 수 있습니다. Concatenate 의 마지막 매개변수는 반드시 ParamSpec 또는 생략 부호(...)여야 합니다.

예를 들어, 데코레이션된 함수에 threading.Lock 을 제공하는 데코레이터 with_lock 을 어노테이션할 때, Concatenate 를 사용하여 with_lock 이 첫 번째 인자로 Lock 을 받는 호출 가능 객체를 기대하며 다른 타입 시그니처를 가진 호출 가능 객체를 반환함을 나타낼 수 있습니다. 이 경우 ParamSpec 은 반환된 호출 가능 객체의 매개변수 유형이 전달된 callable의 매개변수 유형에 의존함을 나타냅니다:

from collections.abc import Callable
from threading import Lock
from typing import Concatenate

# 이 락을 사용하여 한 번에 하나의 스레드만
# 함수를 실행하도록 보장합니다.
my_lock = Lock()

def with_lock[**P, R](f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]:
    '''락을 제공하는 타입 안전한 데코레이터.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
        # 첫 번째 인자로 락을 제공합니다.
        return f(my_lock, *args, **kwargs)
    return inner

@with_lock
def sum_threadsafe(lock: Lock, numbers: list[float]) -> float:
    '''스레드 안전한 방식으로 숫자 리스트를 합산합니다.'''
    with lock:
        return sum(numbers)

# 데코레이터 덕분에 락을 직접 전달할 필요가 없습니다.
sum_threadsafe([1.1, 2.2, 3.3])

Added in version 3.10.

PEP 612 – Parameter Specification Variables (ParamSpec 및 Concatenate 를 도입한 PEP)
ParamSpec
콜러블 객체 어노테이션

typing.Literal¶

“리터럴 형(literal types)”을 정의하기 위한 특별한 타이핑 형태입니다.

Literal 은 어노테이션된 객체가 제공된 리터럴 중 하나와 동일한 값을 가짐을 타입 검사기에게 알리는 데 사용될 수 있습니다.

예를 들면:

def validate_simple(data: Any) -> Literal[True]:  # 항상 True를 반환함
    ...

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

open_helper('/some/path', 'r')      # 타입 검과 통과
open_helper('/other/path', 'typo')  # 타입 검사기에서 오류 발생

Literal[...]은 서브 클래싱 될 수 없습니다. 실행 시간에는, 임의의 값이 Literal[...]에 대한 형 인자로 허용되지만, 형 검사기는 제한을 부과할 수 있습니다. 리터럴 형에 대한 자세한 내용은 PEP 586을 참조하십시오.

추가 세부 사항:

인자는 리터럴 값이어야 하며 최소 하나 이상이 포함되어야 합니다.
중첩된 Literal 형은 평탄화(flattened)됩니다. 예:
```
assert Literal[Literal[1, 2], 3] == Literal[1, 2, 3]
```
그러나 이는 기반이 되는 TypeAliasType`의 평가를 강제하지 않기 위해 타입 에일리어스를 통해 참조되는 ``Literal` 형에는 적용되지 않습니다:
```
type A = Literal[1, 2]
assert Literal[A, 3] != Literal[1, 2, 3]
```

중복 인자는 건너뜁니다. 예를 들어:

assert Literal[1, 2, 1] == Literal[1, 2]

리터럴을 비교할 때 인자 순서는 무시됩니다. 예:
```
assert Literal[1, 2] == Literal[2, 1]
```
Literal 을 서브 클래싱하거나 인스턴스화할 수 없습니다.
Literal[X][Y] 를 작성할 수 없습니다.

Added in version 3.8.

버전 3.9.1에서 변경: Literal now de-duplicates parameters. Equality comparisons of Literal objects are no longer order dependent. Literal objects will now raise a TypeError exception during equality comparisons if one of their parameters are not hashable.

typing.ClassVar¶

클래스 변수를 표시하기 위한 특수 형 구조물.

PEP 526에서 소개된 것처럼, ClassVar로 감싼 변수 어노테이션은 주어진 어트리뷰트가 클래스 변수로 사용되도록 의도되었으며 해당 클래스의 인스턴스에 설정되어서는 안 됨을 나타냅니다. 용법:

class Starship:
    stats: ClassVar[dict[str, int]] = {} # 클래스 변수
    damage: int = 10                     # 인스턴스 변수

ClassVar는 형만 받아들이며 더는 서브 스크립트 할 수 없습니다.

ClassVar 는 클래스 자체가 아니므로 isinstance() 나 issubclass() 와 함께 사용할 수 없습니다. ClassVar 은 Python 실행 시 동작을 변경하지 않지만, 정적 타입 검사기에서 사용될 수 있습니다. 예를 들어, 타입 검사기는 다음 코드를 오류로 표시할 수 있습니다:

enterprise_d = Starship(3000)
enterprise_d.stats = {} # 오류, 인스턴스에서 클래스 변수 설정
Starship.stats = {}     # 이것은 괜찮음

Added in version 3.5.3.

버전 3.13에서 변경: ClassVar 를 Final 에 중첩하거나 그 반대의 경우도 가능합니다.

typing.Final¶

타입 검사기에게 최종(final) 이름을 알리기 위한 특수한 타이핑 구조입니다.

Final 이름은 어떤 범위에서도 재할당될 수 없습니다. 클래스 범위에서 선언된 Final 이름은 서브 클래스에서 재정의될 수 없습니다.

예를 들면:

MAX_SIZE: Final = 9000
MAX_SIZE += 1  # 타입 검사기에서 보고된 오류

class Connection:
    TIMEOUT: Final[int] = 10

class FastConnector(Connection):
    TIMEOUT = 1  # 타입 검사기에서 보고된 오류

이러한 속성에 대한 실행 시간 검사는 없습니다. 자세한 내용은 PEP 591을 참조하십시오.

Added in version 3.8.

버전 3.13에서 변경: Final 을 ClassVar 에 중첩하거나 그 반대의 경우도 가능합니다.

typing.Required¶

TypedDict 키를 필수 항목으로 표시하기 위한 특수한 타이핑 구조입니다.

이것은 주로 total=False 인 TypedDict에서 유용합니다. 자세한 내용은 TypedDict 및 PEP 655 를 참조하십시오.

Added in version 3.11.

typing.NotRequired¶

TypedDict 키가 누락될 수 있음을 표시하기 위한 특수한 타이핑 구조입니다.

자세한 내용은 TypedDict 및 PEP 655 를 참조하십시오.

Added in version 3.11.

typing.ReadOnly¶

TypedDict 의 항목을 읽기 전용으로 표시하기 위한 특수한 타이핑 구조입니다.

예를 들면:

class Movie(TypedDict):
   title: ReadOnly[str]
   year: int

def mutate_movie(m: Movie) -> None:
   m["year"] = 1999  # 허용됨
   m["title"] = "The Matrix"  # 타입 검사 오류

이 속성에 대한 실행 시간 체크는 없습니다.

자세한 내용은 TypedDict 및 PEP 705 를 참조하십시오.

Added in version 3.13.

typing.Annotated¶

어노테이션에 문맥별 메타데이터를 추가하기 위한 특별한 타이핑 형태입니다.

Annotated[T, x] 어노테이션을 사용하여 특정 타입 T 에 메타데이터 x 를 추가합니다. Annotated 로 추가된 메타데이터는 정적 분석 도구에서 사용하거나 실행 시간에 사용할 수 있습니다. 실행 시 메타데이터는 __metadata__ 속성에 저장됩니다.

라이브러리나 도구가 Annotated[T, x] 어노테이션을 만나고 메타데이터에 대한 특별한 로직이 없는 경우, 해당 메타데이터를 무시하고 단순히 이를 T 로 취급해야 합니다. 따라서 Annotated 는 Python의 정적 타이핑 시스템 이외의 목적으로 어노테이션을 사용하고자 하는 코드에서 유용할 수 있습니다.

Annotated[T, x] 를 어노테이션으로 사용하더라도 타입 검사기가 메타데이터 x 를 무시하기 때문에 T 에 대한 정적 타입 검사가 가능합니다. 이런 점에서 Annotated 는 타이핑 시스템 범위 밖의 어노테이션을 추가할 때 사용할 수 있지만 함수나 클래스에 대한 타입 검사를 완전히 비활성화하는 @no_type_check 데코레이터와는 다릅니다.

Annotated 어노테이션을 해석하는 방법의 책임은 해당 어노테이션을 처리하는 도구나 라이브러리에 있습니다. Annotated 타입을 마주치는 도구나 라이브러리는 메타데이터 요소들을 훑어보며 관심 있는 항목인지 판단할 수 있습니다(예: isinstance() 사용).

Annotated[<type>, <metadata>]

범위 분석을 수행할 때 Annotated 를 사용하여 타입 어노테이션에 메타데이터를 추가하는 예시입니다:

@dataclass
class ValueRange:
    lo: int
    hi: int

T1 = Annotated[int, ValueRange(-10, 5)]
T2 = Annotated[T1, ValueRange(-20, 3)]

Annotated 의 첫 번째 인자는 유효한 형이어야 합니다. Annotated 는 가변 인자를 지원하므로 여러 메타데이터 요소가 제공될 수 있습니다. 메타데이터 요소의 순서는 유지되며 동등성 확인 시에 중요하게 작용합니다:

@dataclass
class ctype:
     kind: str

a1 = Annotated[int, ValueRange(3, 10), ctype("char")]
a2 = Annotated[int, ctype("char"), ValueRange(3, 10)]

assert a1 != a2  # 순서가 중요함

어노테이션을 소비하는 도구가 클라이언트가 하나의 어노테이션에 여러 메타데이터 요소를 추가할 수 있는지 여부와 이를 어떻게 병합할지를 결정합니다.

중첩된 Annotated 형은 평탄화됩니다. 메타데이터 요소의 순서는 가장 안쪽의 어노테이션부터 시작합니다:

assert Annotated[Annotated[int, ValueRange(3, 10)], ctype("char")] == Annotated[
    int, ValueRange(3, 10), ctype("char")
]

그러나 이는 기반이 되는 TypeAliasType`의 평가를 강제하는 것을 방지하기 위해 형 별칭(type alias)을 통해 참조되는 ``Annotated` 형에는 적용되지 않습니다:

type From3To10[T] = Annotated[T, ValueRange(3, 10)]
assert Annotated[From3To10[int], ctype("char")] != Annotated[
   int, ValueRange(3, 10), ctype("char")
]

중복된 메타데이터 요소는 제거되지 않습니다:

assert Annotated[int, ValueRange(3, 10)] != Annotated[
    int, ValueRange(3, 10), ValueRange(3, 10)
]

Annotated 는 중첩된 어노테이션 및 제네릭 별칭과 함께 사용될 수 있습니다:

@dataclass
class MaxLen:
    value: int

type Vec[T] = Annotated[list[tuple[T, T]], MaxLen(10)]

# 형 어노테이션에서 사용될 때, 형 검사기는 "V"를 다음 것과 동일하게 취급합니다:
# ``Annotated[list[tuple[int, int]], MaxLen(10)]``:
type V = Vec[int]

Annotated 는 언팩된 TypeVarTuple 과 함께 사용할 수 없습니다:

type Variadic[*Ts] = Annotated[*Ts, Ann1] = Annotated[T1, T2, T3, ..., Ann1]  # 유효하지 않음

여기서 T1, T2 등은 TypeVars 입니다. Annotated에는 하나의 형만 전달되어야 하므로 이는 유효하지 않습니다.

기본적으로 get_type_hints() 는 어노테이션에서 메타데이터를 제거합니다. 메타데이터를 유지하려면 include_extras=True 를 전달하십시오:

>>> from typing import Annotated, get_type_hints
>>> def func(x: Annotated[int, "metadata"]) -> None: pass
...
>>> get_type_hints(func)
{'x': <class 'int'>, 'return': <class 'NoneType'>}
>>> get_type_hints(func, include_extras=True)
{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

실행 시에 Annotated 형과 연관된 메타데이터는 __metadata__ 속성을 통해 가져올 수 있습니다:

>>> from typing import Annotated
>>> X = Annotated[int, "very", "important", "metadata"]
>>> X
typing.Annotated[int, 'very', 'important', 'metadata']
>>> X.__metadata__
('very', 'important', 'metadata')

Annotated 로 래핑된 원래 형을 가져오려면 __origin__ 속성을 사용하십시오:

>>> from typing import Annotated, get_origin
>>> Password = Annotated[str, "secret"]
>>> Password.__origin__
<class 'str'>

get_origin`을 사용하면 ``Annotated`() 자체가 반환됨에 유의하십시오:

>>> get_origin(Password)
typing.Annotated

PEP 593 - 유연한 함수 및 변수 어노테이션: 표준 라이브러리에 Annotated 를 도입한 PEP입니다.

Added in version 3.9.

typing.TypeForm¶

형 표현을 평가하여 얻은 값을 나타내는 특수 형(special form)입니다.

이 값은 형 표현에 제공된 정보를 인코딩하며, 해당 형 표현으로 설명되는 형을 나타냅니다.

형 표현에서 사용될 때, TypeForm 은 형 형성(type form) 객체들의 집합을 기술합니다. 이는 단일 형 인자를 수용하며, 해당 인자는 유효한 형 표현이어야 합니다. TypeForm[T] 는 형 T 또는 T 에 할당 가능한 모든 형을 나타내는 형 형성 객체들의 집합을 기술합니다.

TypeForm(obj) 는 obj 를 변경하지 않고 그대로 반환합니다. 이는 정적 형 검사기(static type checker)를 위해 특정 값을 명시적으로 형 형성으로 표시하는 데 유용합니다.

예제:

from typing import Any, TypeForm

def cast[T](typ: TypeForm[T], value: Any) -> T: ...

reveal_type(cast(int, "x"))  # 드러나는 형은 "int"

자세한 내용은 PEP 747 을 참조하십시오.

Added in version 3.15.

typing.TypeIs¶

사용자 정의 형 예측(type predicate) 함수를 표시하기 위한 특별한 타이핑 구조입니다.

TypeIs 는 사용자 정의 형 예측 함수의 반환형을 어노테이션하는 데 사용될 수 있습니다. TypeIs 는 단일 형 인자만 허용합니다. 실행 시에 이와 같이 표시된 함수는 불리언(boolean) 값을 반환해야 하며, 최소 하나 이상의 위치 인수를 받아야 합니다.

TypeIs 는 프로그램의 코드 흐름 내에서 표현식의 더 정확한 형을 결정하기 위해 정적 형 검사기가 사용하는 기법인 형 축소(type narrowing) 를 돕기 위한 것입니다. 일반적으로 형 축소는 조건부 코드 흐름을 분석하여 특정 코드 블록에 축소를 적용함으로써 이루어집니다. 여기서의 조건부 표현은 때때로 “형 예측(type predicate)”이라 불리기도 합니다:

def is_str(val: str | float):
    # "isinstance" 형 예측
    if isinstance(val, str):
        # ``val``의 형이 ``str``으로 축소됨
        ...
    else:
        # 그 외의 경우, ``val``의 형이 ``float``으로 축소됨
        ...

Sometimes it would be convenient to use a user-defined boolean function as a type predicate. Such a function should use TypeIs[...] or TypeGuard as its return type to alert static type checkers to this intention. TypeIs usually has more intuitive behavior than TypeGuard, but it cannot be used when the input and output types are incompatible (e.g., list[object] to list[int]) or when the function does not return True for all instances of the narrowed type.

-> TypeIs[NarrowedType] 을 사용하면 정적 형 검사기에게 주어진 함수에 대해 다음을 알립니다:

반환 값이 불리언입니다.
반환 값이 True 이면, 인수의 형은 해당 인자의 원래 형과 NarrowedType 의 교집합입니다.
반환 값이 False 이면, 인수의 형은 NarrowedType 을 제외하도록 축소됩니다.

예를 들면:

from typing import assert_type, final, TypeIs

class Parent: pass
class Child(Parent): pass
@final
class Unrelated: pass

def is_parent(val: object) -> TypeIs[Parent]:
    return isinstance(val, Parent)

def run(arg: Child | Unrelated):
    if is_parent(arg):
        # ``arg``의 형이 ``Parent``와 ``Child``의 교집합으로
        # 축소되며, 이는 ``Child``와 동일합니다.
        assert_type(arg, Child)
    else:
        # ``arg``의 형이 ``Parent``를 제외하도록 축소되어
        # 오직 ``Unrelated``만 남습니다.
        assert_type(arg, Unrelated)

TypeIs 내부의 형은 함수의 인자 형과 일치해야 합니다. 그렇지 않을 경우 정적 형 검사기에서 오류가 발생합니다. 잘못 작성된 TypeIs 함수는 타입 시스템 내에서 부적절한 동작을 초래할 수 있으므로, 사용자는 이러한 함수를 타입 안전(type-safe)하게 작성할 책임이 있습니다.

TypeIs 함수가 클래스 또는 인스턴스 메서드인 경우, TypeIs``의 형은 두 번째 매개변수(``cls 또는 self 이후)의 형에 매핑됩니다.

요약하면, def foo(arg: TypeA) -> TypeIs[TypeB]: ... 형식은 foo(arg) 가 True 를 반환하면 arg 가 TypeB 의 인스턴스임을 의미하고, False 를 반환하면 TypeB 의 인스턴스가 아님을 의미합니다.

TypeIs 는 형 변수와도 함께 작동합니다. 자세한 내용은 PEP 742 (TypeIs 를 이용한 형 축소)를 참조하십시오.

Added in version 3.13.

typing.TypeGuard¶

사용자 정의 형 예측(type predicate) 함수를 표시하기 위한 특별한 타이핑 구조입니다.

형 예측(type predicate) 함수는 인자가 특정 형의 인스턴스인지 여부를 반환하는 사용자 정의 함수입니다. TypeGuard 는 TypeIs 와 유사하게 작동하지만, 형 검사 동작에 미치는 영향이 미세하게 다릅니다(아래 참조).

-> TypeGuard 를 사용하면 정적 형 검사기에게 주어진 함수에 대해 다음을 알립니다:

반환 값이 불리언입니다.
반환 값이 True``인 경우, 인수의 형은 ``TypeGuard 내부의 형이 됩니다.

TypeGuard 역시 형 변수와 함께 작동합니다. 자세한 내용은 PEP 647 을 참조하십시오.

예를 들면:

def is_str_list(val: list[object]) -> TypeGuard[list[str]]:
    '''리스트 내의 모든 객체가 문자열인지 확인'''
    return all(isinstance(x, str) for x in val)

def func1(val: list[object]):
    if is_str_list(val):
        # ``val``의 형이 ``list[str]``로 축소됨
        print(" ".join(val))
    else:
        # ``val``의 형은 ``list[object]``로 유지됨
        print("Not a list of strings!")

TypeIs 와 TypeGuard 는 다음과 같은 점에서 차이가 있습니다:

TypeIs 는 축소된 형이 입력형의 하위 형이어야 하지만, TypeGuard 는 그렇지 않습니다. 주요 이유는 list 가 불변(invariant)이므로 후자가 전자의 하위 형이 아님에도 불구하고 list[object] 를 list[str] 로 축소하는 것과 같은 상황을 허용하기 위함입니다.
TypeGuard 함수가 True``를 반환할 때, 형 검사기는 변수의 형을 정확히 ``TypeGuard 형으로 축소합니다. TypeIs 함수가 True``를 반환할 때, 형 검사기는 기존에 알려진 변수의 형과 ``TypeIs 형을 결합하여 더 정밀한 형을 추론할 수 있습니다. (기술적으로 이는 교차형(intersection type)이라고 합니다.)
TypeGuard 함수가 False``를 반환할 때, 형 검사기는 변수의 형을 전혀 축소하지 못합니다. ``TypeIs 함수가 False``를 반환할 때, 형 검사기는 변수의 형에서 ``TypeIs 형을 제외하도록 축소할 수 있습니다.

Added in version 3.10.

typing.Unpack¶

객체가 언팩(unpack)되었음을 개념적으로 표시하는 타이핑 연산자입니다.

예를 들어, 형 변수 튜플 에 언팩 연산자 * 를 사용하는 것은 Unpack 을 사용하여 해당 형 변수 튜플이 언팩되었음을 표시하는 것과 동일합니다:

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]
# 사실상 다음을 수행합니다:
tup: tuple[Unpack[Ts]]

실제로 Unpack 은 typing.TypeVarTuple 및 builtins.tuple 유형의 문맥에서 *``와 상호 대체하여 사용할 수 있습니다. ``* `를 특정 위치에 사용할 수 없었던 이전 버전의 Python에서는 ``Unpack` 이 명시적으로 사용되는 것을 볼 수 있습니다:

# 이전 버전의 Python에서는 TypeVarTuple과 Unpack이
# `typing_extensions` 백포트 패키지에 위치합니다.
from typing_extensions import TypeVarTuple, Unpack

Ts = TypeVarTuple('Ts')
tup: tuple[*Ts]         # Python <= 3.10에서 구문 오류!
tup: tuple[Unpack[Ts]]  # 의미론적으로 동등하며, 후방 호환성이 있습니다.

Unpack 은 함수 시그니처에서 **kwargs 를 타이핑할 때 typing.TypedDict 와 함께 사용할 수 있습니다:

from typing import TypedDict, Unpack

class Movie(TypedDict):
    name: str
    year: int

# 이 함수는 두 개의 키워드 인자 - 타입이 `str`인 `name`과
# 타입이 `int`인 `year`를 기대합니다.
def foo(**kwargs: Unpack[Movie]): ...

**kwargs 타이핑을 위해 Unpack 을 사용하는 방법에 대한 자세한 내용은 PEP 692 를 참조하십시오.

Added in version 3.11.

제네릭 형 및 형 별칭 구축¶

다음 클래스들은 어노테이션으로 직접 사용해서는 안 됩니다. 이들의 본래 목적은 제네릭 형과 형 별칭을 생성하기 위한 빌딩 블록이 되는 것입니다.

이 객체들은 특별한 구문(형 매개변수 목록 및 type 문)을 통해 생성될 수 있습니다. Python 3.11 이전 버전과의 호환성을 위해 아래에 설명된 대로 전용 구문 없이도 생성할 수 있습니다.

class typing.Generic¶

제네릭 형을 위한 추상 베이스 클래스.

제네릭 형은 일반적으로 클래스 이름 뒤에 형 매개변수 목록을 추가하여 선언합니다:

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

이러한 클래스는 Generic 을 암시적으로 상속합니다. 이 구문의 실행 시 의미는 언어 참조 에서 다룹니다.

이 클래스는 다음과 같이 사용할 수 있습니다:

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

여기 함수 이름 뒤의 대괄호는 제네릭 함수 를 나타냅니다.

하위 호환성을 위해 제네릭 클래스를 Generic 을 명시적으로 상속하여 선언할 수도 있습니다. 이 경우 형 매개변수는 별도로 선언해야 합니다:

KT = TypeVar('KT')
VT = TypeVar('VT')

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

class typing.TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)¶

형 변수.

형 변수를 구성하는 권장되는 방법은 제네릭 함수, 제네릭 클래스, 그리고 제네릭 형 별칭 을 위한 전용 구문을 사용하는 것입니다:

class Sequence[T]:  # T는 형 변수(TypeVar)
    ...

이 구문은 제한된(bounded) 및 제약 조건이 있는(constrained) 형 변수를 생성하는 데도 사용될 수 있습니다:

class StrSequence[S: str]:  # S는 \"str\" 상한을 가진 TypeVar입니다;
    ...                     # S가 \"str\에 의해 제한됨\이라고 말할 수 있습니다"


class StrOrBytesSequence[A: (str, bytes)]:  # A는 str 또는 bytes로 제한된 TypeVar입니다
    ...

하지만 필요한 경우, 다음과 같이 재사용 가능한 형 변수를 수동으로 생성할 수도 있습니다:

T = TypeVar('T')  # 무엇이든 가능
S = TypeVar('S', bound=str)  # str의 모든 서브타입 가능
A = TypeVar('A', str, bytes)  # 반드시 str 또는 bytes여야 함

형 변수는 주로 정적 형 검사기의 편의를 위해 존재합니다. 이들은 제네릭 함수 및 형 별칭 정의뿐만 아니라 제네릭 형의 매개변수로도 사용됩니다. 제네릭 형에 대한 자세한 정보는 Generic 을 참조하십시오. 제네릭 함수는 다음과 같이 작동합니다:

def repeat[T](x: T, n: int) -> Sequence[T]:
    """x에 대한 참조를 n개 포함하는 리스트를 반환합니다."""
    return [x]*n


def print_capitalized[S: str](x: S) -> S:
    """x를 대문자로 출력하고 x를 반환합니다."""
    print(x.capitalize())
    return x


def concatenate[A: (str, bytes)](x: A, y: A) -> A:
    """두 개의 문자열 또는 bytes 객체를 합칩니다."""
    return x + y

형 변수는 제한적(bounded) 이거나 제약(constrained) 을 받거나, 둘 다 해당하지 않을 수 있지만, 제약과 제한을 동시에 모두 가질 수는 없습니다.

형 변수의 변량(variance)은 type parameter syntax 를 통해 생성되거나 infer_variance=True 가 전달될 때 형 검사기에 의해 추론됩니다. 수동으로 생성된 형 변수는 covariant=True 또는 contravariant=True 를 전달하여 명시적으로 공변(covariant) 또는 반변(contravariant)으로 표시할 수 있습니다. 기본적으로 수동으로 생성된 형 변수는 불변(invariant)입니다. 자세한 내용은 PEP 484 및 PEP 695 를 참조하십시오.

제한된(bounded) 형 변수와 제약이 있는(constrained) 형 변수는 여러 중요한 측면에서 서로 다른 의미를 가집니다. 제한된 형 변수를 사용하는 것은 TypeVar 가 가능한 가장 구체적인 형으로 해결됨을 의미합니다:

x = print_capitalized('a string')
reveal_type(x)  # 확인된 형은 str

class StringSubclass(str):
    pass

y = print_capitalized(StringSubclass('another string'))
reveal_type(y)  # 확인된 형은 StringSubclass

z = print_capitalized(45)  # 오류: int는 str의 서브타입이 아님

형 변수의 상한(upper bound)은 구체적인 형, 추상형(ABC 또는 Protocol), 혹은 형들의 공용체(union)일 수도 있습니다:

# \_abs\_ 메서드가 있는 모든 형이 가능
def print_abs[T: SupportsAbs](arg: T) -> None:
    print("Absolute value:", abs(arg))

U = TypeVar('U', bound=str|bytes)  # str|bytes 공용체의 모든 서브타입 가능
V = TypeVar('V', bound=SupportsAbs)  # \_abs\_ 메서드가 있는 모든 형 가능

반면, 제약된(constrained) 형 변수를 사용하는 것은 TypeVar 가 주어진 제약 사항 중 정확히 하나로만 해결될 수 있음을 의미합니다:

a = concatenate('one', 'two')
reveal_type(a)  # 확인된 형은 str

b = concatenate(StringSubclass('one'), StringSubclass('two'))
reveal_type(b)  # StringSubclass가 전달되었음에도 확인된 형은 str

c = concatenate('one', b'two')  # 오류: 함수 호출에서 형 변수 'A'는 str 또는 bytes 중 하나일 수는 있지만, 동시에 두 형이 될 수는 없음

실행 시에 isinstance(x, T) 는 TypeError 를 발생시킵니다.

__name__¶: 형 변수의 이름.

__covariant__¶: 형 변수가 명시적으로 공변(covariant)으로 표시되었는지 여부.

__contravariant__¶: 형 변수가 명시적으로 반변(contravariant)으로 표시되었는지 여부.

__infer_variance__¶: 형 변수의 변량이 형 검사기에 의해 추론되어야 하는지 여부.

Added in version 3.12.

__bound__¶: 형 변수의 상한(upper bound), 존재하는 경우.

버전 3.12에서 변경: type parameter syntax 를 통해 생성된 형 변수의 경우, 상한은 형 변수가 생성될 때가 아니라 속성에 접근할 때만 평가됩니다(참고: 지연 평가).

evaluate_bound()¶: An evaluate function corresponding to the __bound__ attribute. When called directly, this method supports only the VALUE format, which is equivalent to accessing the __bound__ attribute directly, but the method object can be passed to annotationlib.call_evaluate_function() to evaluate the value in a different format.

Added in version 3.14.

__constraints__¶: 형 변수의 제약(constraints)이 있는 경우 이를 포함하는 튜플입니다.

버전 3.12에서 변경: type parameter syntax 를 통해 생성된 형 변수의 경우, 제약은 형 변수가 생성될 때가 아니라 속성에 접근할 때만 평가됩니다(참고: 지연 평가).

evaluate_constraints()¶: An evaluate function corresponding to the __constraints__ attribute. When called directly, this method supports only the VALUE format, which is equivalent to accessing the __constraints__ attribute directly, but the method object can be passed to annotationlib.call_evaluate_function() to evaluate the value in a different format.

Added in version 3.14.

__default__¶: 형 변수의 기본값, 기본값이 없는 경우 typing.NoDefault 입니다.

Added in version 3.13.

evaluate_default()¶: An evaluate function corresponding to the __default__ attribute. When called directly, this method supports only the VALUE format, which is equivalent to accessing the __default__ attribute directly, but the method object can be passed to annotationlib.call_evaluate_function() to evaluate the value in a different format.

Added in version 3.14.

has_default()¶: Return whether or not the type variable has a default value. This is equivalent to checking whether __default__ is not the typing.NoDefault singleton, except that it does not force evaluation of the lazily evaluated default value.

Added in version 3.13.

버전 3.12에서 변경: 이제 형 변수를 PEP 695 에서 도입된 type parameter 구문을 사용하여 선언할 수 있습니다. infer_variance 매개변수가 추가되었습니다.

버전 3.13에서 변경: 기본값에 대한 지원이 추가되었습니다.

class typing.TypeVarTuple(name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)¶

유형 변수 튜플입니다. 가변적 제네릭을 활성화하는 특화된 type variable 형태입니다.

형 변수 튜플은 이름 앞에 단일 별표(*)를 사용하여 type parameter lists 에서 선언할 수 있습니다:

def move_first_element_to_last[T, *Ts](tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

또는 TypeVarTuple 생성자를 명시적으로 호출하여 선언할 수 있습니다:

T = TypeVar("T")
Ts = TypeVarTuple("Ts")

def move_first_element_to_last(tup: tuple[T, *Ts]) -> tuple[*Ts, T]:
    return (*tup[1:], tup[0])

일반적인 형 변수는 단일 형으로 매개변수화할 수 있습니다. 반면에 형 변수 튜플은 튜플에 감싸인 임의의 수의 형 변수처럼 작동하여 임의의 수의 형으로 매개변수화할 수 있습니다. 예를 들어:

# T는 int로 제한됨, Ts는 ()로 제한됨
move_first_element_to_last(tup=(1,))

# T는 int로 제한됨, Ts는 (str,)로 제한됨
move_first_element_to_last(tup=(1, 'spam'))

# T는 int로 제한됨, Ts는 (str, float)로 제한됨
move_first_element_to_last(tup=(1, 'spam', 3.0))

# 다음은 형 검사를 통과하지 못하며(실행 시에도 실패함)
# tuple[()]이 tuple[T, *Ts]와 호환되지 않기 때문입니다.
# (최소 하나의 요소가 필요합니다)
move_first_element_to_last(tup=())

tuple[T, *Ts] 에서 언패킹 연산자 * 의 사용에 주목하십시오. 개념적으로 Ts 를 형 변수들의 튜플인 (T1, T2, ...) 로 생각할 수 있습니다. 그러면 tuple[T, *Ts] 는 tuple[T, *(T1, T2, ...)] 가 되며, 이는 tuple[T, T1, T2, ...] 와 동일합니다. (참고: 이전 버전의 파이썬에서는 이것이 Unpack[Ts] 와 같이 Unpack 를 사용하여 표기된 것을 볼 수 있습니다.)

형 변수 튜플은 항상 언패킹되어야 합니다. 이는 형 변수 튜플과 일반적인 형 변수를 구분하는 데 도움이 됩니다:

x: Ts          # 유효하지 않음
x: tuple[Ts]   # 유효하지 않음
x: tuple[*Ts]  # 올바른 방법

형 변수 튜플은 일반 형 변수와 동일한 맥락에서 사용될 수 있습니다. 예를 들어 클래스 정의, 인자 및 반환 형 등에서 사용할 수 있습니다:

class Array[*Shape]:
    def __getitem__(self, key: tuple[*Shape]) -> float: ...
    def __abs__(self) -> "Array[*Shape]": ...
    def get_shape(self) -> tuple[*Shape]: ...

형 변수 튜플을 일반 형 변수와 결합하여 사용할 수 있습니다:

class Array[DType, *Shape]:  # 문제없음
    pass

class Array2[*Shape, DType]:  # 이 또한 문제없음
    pass

class Height: ...
class Width: ...

float_array_1d: Array[float, Height] = Array()     # 전혀 문제없음
int_array_2d: Array[int, Height, Width] = Array()  # 네, 이것도 괜찮습니다

하지만 단일 유형 인자 또는 유형 매개변수 목록에 형 변수 튜플은 최대 하나만 나타날 수 있음에 유의하십시오:

x: tuple[*Ts, *Ts]            # 유효하지 않음
class Array[*Shape, *Shape]:  # 유효하지 않음
    pass

마지막으로, 언패킹된 형 변수 튜플은 *args 의 형 주석으로 사용될 수 있습니다:

def call_soon[*Ts](
    callback: Callable[[*Ts], None],
    *args: *Ts
) -> None:
    ...
    callback(*args)

모든 인자가 int 임을 명시하는 *args: int 와 같은 언패킹되지 않은 *args 주석과 달리, *args: *Ts 는 *args 내의 개별 인자들의 형을 참조할 수 있게 합니다. 여기서 이는 call_soon 에 전달되는 *args 의 형이 callback 의 (위치) 인자들과 일치하는지 보장할 수 있게 해줍니다.

형 변수 튜플에 대한 자세한 내용은 PEP 646 을 참조하십시오.

__name__¶: 형 변수 튜플의 이름.

__covariant__¶: 형 변수 튜플이 명시적으로 공변(covariant)으로 표시되었는지 여부.

Added in version 3.15.

__contravariant__¶: 형 변수 튜플이 명시적으로 반변(contravariant)으로 표시되었는지 여부.

Added in version 3.15.

__infer_variance__¶: 형 변수 튜플의 변량이 형 검사기에 의해 추론되어야 하는지 여부.

Added in version 3.15.

__default__¶: 형 변수 튜플의 기본값 또는 기본값이 없는 경우 typing.NoDefault 입니다.

Added in version 3.13.

evaluate_default()¶: An evaluate function corresponding to the __default__ attribute. When called directly, this method supports only the VALUE format, which is equivalent to accessing the __default__ attribute directly, but the method object can be passed to annotationlib.call_evaluate_function() to evaluate the value in a different format.

Added in version 3.14.

has_default()¶: Return whether or not the type variable tuple has a default value. This is equivalent to checking whether __default__ is not the typing.NoDefault singleton, except that it does not force evaluation of the lazily evaluated default value.

Added in version 3.13.

covariant=True 또는 contravariant=True 로 생성된 형 변수 튜플은 공변(covariant) 또는 반변(contravariant) 제네릭 형을 선언하는 데 사용될 수 있습니다. bound 인자도 TypeVar 와 유사하게 허용되지만, 실제 의미는 아직 결정되지 않았습니다.

Added in version 3.11.

버전 3.12에서 변경: 이제 형 변수 튜플을 PEP 695 에서 도입된 type parameter 구문을 사용하여 선언할 수 있습니다.

버전 3.13에서 변경: 기본값에 대한 지원이 추가되었습니다.

버전 3.15에서 변경: bound, covariant, contravariant, infer_variance 매개변수에 대한 지원이 추가되었습니다.

class typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=typing.NoDefault)¶

매개 변수 사양(specification) 변수입니다. type variables 의 특수 형태입니다.

type parameter lists 에서 매개 변수 사양은 두 개의 별표(**)를 사용하여 선언할 수 있습니다:

type IntFunc[**P] = Callable[P, int]

Python 3.11 및 이전 버전과의 호환성을 위해 ParamSpec 객체를 다음과 같이 생성할 수도 있습니다:

P = ParamSpec('P')

매개 변수 사양 변수는 주로 정적 형 검사기의 편의를 위해 존재합니다. 이들은 하나의 콜러블(callable)의 매개 변수 형을 다른 콜러블로 전달하는 데 사용되며, 이는 고차 함수 및 데코레이터에서 흔히 발견되는 패턴입니다. 이 변수들은 Concatenate 에서 사용되거나, Callable 의 첫 번째 인자로 사용되거나, 사용자 정의 제네릭(Generics)의 매개 변수로 사용될 때만 유효합니다. 제네릭 형에 대한 자세한 정보는 Generic 을 참조하십시오.

예를 들어, 함수에 기본적인 로깅을 추가하려면 함수 호출을 기록하는 데코레이터 add_logging 을 만들 수 있습니다. 매개변수 사양(parameter specification) 변수는 데코레이터에 전달된 호출 가능 객체와 해당 데코레이터에 의해 반환되는 새로운 호출 가능 객체가 서로 의존적인 형 매개변수를 가짐을 형 검사기에게 알립니다:

from collections.abc import Callable
import logging

def add_logging[T, **P](f: Callable[P, T]) -> Callable[P, T]:
    '''함수에 로깅을 추가하는 형 안전한 데코레이터.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

@add_logging
def add_two(x: float, y: float) -> float:
    '''두 수를 더합니다.'''
    return x + y

ParamSpec 이 없었다면 이를 어노테이션하는 가장 간단한 방법은 상한이 Callable[..., Any] 인 TypeVar 를 사용하는 것이었습니다. 그러나 이 방식은 두 가지 문제를 야기합니다:

The type checker can’t type check the inner function because *args and **kwargs have to be typed Any.
inner 함수를 반환할 때 add_logging 데코레이터의 본문에서 cast() 가 필요하거나, 정적 타입 검사기에게 return inner 를 무시하도록 알려야 합니다.

args¶

kwargs¶: ParamSpec 은 위치 매개변수와 키워드 매개변수를 모두 캡처하므로, P.args 와 P.kwargs 를 사용하여 ParamSpec 을 구성 요소로 분리할 수 있습니다. P.args 는 특정 호출의 위치 매개변수 튜플을 나타내며 *args 를 어노테이션하는 데에만 사용해야 합니다. P.kwargs 는 특정 호출에서 키워드 매개변수와 해당 값의 매핑을 나타내며 **kwargs 를 어노테이션하는 데에만 사용해야 합니다. 두 어트리뷰트 모두 어노테이션된 매개변수가 범위(scope) 내에 있어야 합니다. 실행 시, P.args 와 P.kwargs 는 각각 ParamSpecArgs 및 ParamSpecKwargs 의 인스턴스입니다.

__name__¶: 매개변수 명세(specification)의 이름.

__covariant__¶: 매개변수 명세가 공변적(covariant)으로 명시적으로 표시되었는지 여부.

__contravariant__¶: 매개변수 명세가 반변적(contravariant)으로 명시적으로 표시되었는지 여부.

__infer_variance__¶: 타입 검사기에 의해 매개변수 명세의 변이성(variance)을 추론해야 하는지 여부.

Added in version 3.12.

__default__¶: 매개변수 명세의 기본값이거나, 기본값이 없는 경우 typing.NoDefault.

Added in version 3.13.

evaluate_default()¶: __default__ 어트리뷰트에 대응하는 evaluate function 입니다. 이 메서드를 직접 호출하면 VALUE 형식만 지원하며, 이는 __default__ 어트리뷰스에 직접 접근하는 것과 동일합니다. 그러나 해당 메서드 객체를 annotationlib.call_evaluate_function() 으로 전달하여 다른 형식으로 값을 평가할 수도 있습니다.

Added in version 3.14.

has_default()¶: 매개변수 명세에 기본값이 있는지 여부를 반환합니다. 이는 __default__ 가 typing.NoDefault 싱글톤이 아닌지 확인하는 것과 같으나, 차이점은 lazily evaluated 으로 평가되는 기본값을 강제로 평가하지 않는다는 점입니다.

Added in version 3.13.

covariant=True 또는 contravariant=True 로 생성된 매개변수 명세 변수는 공변적 또는 반변적 제네릭 타입을 선언하는 데 사용될 수 있습니다. bound 인자도 TypeVar 와 유사하게 허용됩니다. 다만, 이 키워드들의 실제 의미는 아직 결정되지 않았습니다.

Added in version 3.10.

버전 3.12에서 변경: 이제 매개변수 명세를 PEP 695 에서 도입된 type parameter 구문을 사용하여 선언할 수 있습니다.

버전 3.13에서 변경: 기본값에 대한 지원이 추가되었습니다.

참고

전역 범위(global scope)에 정의된 매개변수 명세 변수만 피클링(pickled)될 수 있습니다.

PEP 612 – Parameter Specification Variables (ParamSpec 및 Concatenate 를 도입한 PEP)
Concatenate
콜러블 객체 어노테이션

class typing.ParamSpecArgs¶

class typing.ParamSpecKwargs¶

Arguments and keyword arguments attributes of a ParamSpec. The P.args attribute of a ParamSpec is an instance of ParamSpecArgs, and P.kwargs is an instance of ParamSpecKwargs. They are intended for runtime introspection and have no special meaning to static type checkers.

이 객체 중 어느 것에 대해 get_origin() 을 호출하든 원래의 ParamSpec 이 반환됩니다.

>>> from typing import ParamSpec, get_origin
>>> P = ParamSpec("P")
>>> get_origin(P.args) is P
True
>>> get_origin(P.kwargs) is P
True

Added in version 3.10.

class typing.TypeAliasType(name, value, *, type_params=(), qualname=None)¶

type 문을 통해 생성된 형 에일리어스(type alias)의 타입입니다.

예제:

>>> type Alias = int
>>> type(Alias)
<class 'typing.TypeAliasType'>

Added in version 3.12.

__name__¶

형 에일리어스의 이름:

>>> type Alias = int
>>> Alias.__name__
'Alias'

__qualname__¶

형 에일리어스의 qualified name:

>>> class Class:
...     type Alias = int
...
>>> Class.Alias.__qualname__
'Class.Alias'

Added in version 3.15.

__module__¶

형 에일리어스가 정의된 모듈의 이름입니다:

>>> type Alias = int
>>> Alias.__module__
'__main__'

이 어트리뷰스는 쓰기가 가능합니다.

버전 3.15에서 변경: 이제 해당 어트리뷰스가 쓰기 가능해졌습니다.

__type_params__¶

형 에일리어스의 타입 매개변수이며, 에일리어스가 제네릭이 아닌 경우 빈 튜플을 반환합니다.

>>> type ListOrSet[T] = list[T] | set[T]
>>> ListOrSet.__type_params__
(T,)
>>> type NotGeneric = int
>>> NotGeneric.__type_params__
()

__value__¶

형 에일리어스의 값입니다. 이는 lazily evaluated 이므로, 에일리어스 정의에 사용된 이름들은 __value__ 어트리뷰스에 접근할 때까지 해석되지 않습니다.

>>> type Mutually = Recursive
>>> type Recursive = Mutually
>>> Mutually
Mutually
>>> Recursive
Recursive
>>> Mutually.__value__
Recursive
>>> Recursive.__value__
Mutually

evaluate_value()¶

__value__ 어트리뷰스에 대응하는 evaluate function 입니다. 이 메서드를 직접 호출하면 VALUE 형식만 지원하며, 이는 __value__ 어트리뷰스에 직접 접근하는 것과 동일합니다. 다만, 해당 메서드 객체를 annotationlib.call_evaluate_function() 으로 전달하여 다른 형식으로 값을 평가할 수도 있습니다.

>>> type Alias = undefined
>>> Alias.__value__
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> from annotationlib import Format, call_evaluate_function
>>> Alias.evaluate_value(Format.VALUE)
Traceback (most recent call last):
...
NameError: name 'undefined' is not defined
>>> call_evaluate_function(Alias.evaluate_value, Format.FORWARDREF)
ForwardRef('undefined')

Added in version 3.14.

언패킹(Unpacking)

형 에일리어스는 *Alias 구문을 사용하여 스타 언패킹(star unpacking)을 지원합니다. 이는 Unpack[Alias] 를 직접 사용하는 것과 동일합니다.

>>> type Alias = tuple[int, str]
>>> type Unpacked = tuple[bool, *Alias]
>>> Unpacked.__value__
tuple[bool, typing.Unpack[Alias]]

Added in version 3.14.

기타 특수 지시자¶

이 함수와 클래스들은 어노테이션으로 직접 사용해서는 안 됩니다. 이것들의 목적은 형을 생성하고 선언하기 위한 빌드 블록(building blocks)입니다.

class typing.NamedTuple¶

형 지정된(typed) 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

기본값이 있는 필드는 기본값이 없는 모든 필드 뒤에 와야 합니다.

결과 클래스에 대해 annotationlib.get_annotations`를 호출하여 각 필드 이름의 형을 가져올 수 있습니다. (필드 이름은 ``_fields`() 어트리뷰스에, 기본값은 _field_defaults 어트리뷰스에 있으며, 이 둘은 모두 namedtuple() API의 일부입니다.)

NamedTuple 서브 클래스는 독스트링과 메서드도 가질 수 있습니다:

class Employee(NamedTuple):
    """직원을 나타냅니다."""
    name: str
    id: int = 3

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

NamedTuple 서브 클래스는 제네릭이 될 수 있습니다:

class Group[T](NamedTuple):
    key: T
    group: list[T]

이전 버전과 호환되는 사용법:

# Python 3.11에서 제네릭 NamedTuple을 생성하는 경우
T = TypeVar("T")

class Group(NamedTuple, Generic[T]):
    key: T
    group: list[T]

# 함수형 구문도 지원됩니다
Employee = NamedTuple('Employee', [('name', str), ('id', int)])

버전 3.6에서 변경: PEP 526 변수 어노테이션 문법 지원을 추가했습니다.

버전 3.6.1에서 변경: 기본값, 메서드 및 독스트링에 대한 지원을 추가했습니다.

버전 3.8에서 변경: _field_types와 __annotations__ 어트리뷰트는 이제 OrderedDict 인스턴스가 아닌 일반 딕셔너리입니다.

버전 3.9에서 변경: _field_types 어트리뷰트를 제거하고, 같은 정보를 가지는 더 표준적인 __annotations__ 어트리뷰트로 대체했습니다.

버전 3.9에서 변경: NamedTuple 은 이제 클래스가 아니라 함수입니다. 위에서 설명한 대로 여전히 클래스 기반으로 사용될 수 있습니다.

버전 3.11에서 변경: 제네릭 네임드 튜플(namedtuple)에 대한 지원이 추가되었습니다.

버전 3.14에서 변경: NamedTupel 서브 클래스의 메서드에서 super() (및 __class__ closure variable)를 사용하는 것은 지원되지 않으며 TypeError 를 발생시킵니다.

class typing.NewType(name, tp)¶

낮은 오버헤드로 distinct types 을 생성하기 위한 도우미 클래스입니다.

NewType 은 타입 검사기에서 고유 형(distinct type)으로 간주됩니다. 그러나 실행 시 NewType 을 호출하면 인자를 변경하지 않고 그대로 반환합니다.

용법:

UserId = NewType('UserId', int)  # \*\*UserId\*\*라는 NewType 선언
first_user = UserId(1)  # "UserId"는 실행 시 인자를 변경하지 않고 반환합니다.

__module__¶: 새 형이 정의된 모듈의 이름입니다.

__name__¶: 새 형의 이름입니다.

__supertype__¶: 새 형이 기반으로 하는 형입니다.

Added in version 3.5.2.

버전 3.10에서 변경: NewType 은 이제 함수가 아니라 클래스입니다.

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())  # 정적 타입 검과 통과됨

자세한 내용은 PEP 544 를 참조하십시오. @runtime_checkable 가 적용된 프로토콜 클래스(나중에 설명)는 타입 서명을 무시하고 주어진 속성의 존재 여부만 확인하는 단순한 실행 시간 프로토콜로 작동합니다. 이 데코레이터가 없는 프로토콜 클래스는 isinstance() 또는 issubclass() 의 두 번째 인자로 사용할 수 없습니다.

프로토콜 클래스는 제네릭일 수 있습니다, 예를 들어:

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

Python 3.11 이하 버전과 호환되어야 하는 코드에서 제네릭 프로토콜은 다음과 같이 작성할 수 있습니다:

T = TypeVar("T")

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

Added in version 3.8.

버전 3.15부터 사용 지원 중단(deprecated), 버전 3.20에서 제거 예정: 명시적으로 runtime_checkable() 데코레이터가 붙지 않았으나 실행 가능(runtime-checkable) 프로토콜 클래스를 상속받은 프로토콜 클래스에 대해 isinstance() 및 issubclass() 검사를 수행하는 것은 더 이상 권장되지 않습니다. 이는 Python 3.20에서 TypeError 를 발생시킵니다.

@typing.runtime_checkable¶

프로토콜 클래스를 실행 시간 프로토콜로 표시합니다.

이러한 프로토콜은 isinstance() 및 issubclass() 와 함께 사용할 수 있습니다. 이는 Iterable 과 같은 collections.abc 의 “one-trick ponies”와 매우 유사한 단순 구조 검사를 가능하게 합니다. 예를 들어:

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

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

@runtime_checkable
class Named(Protocol):
    name: str

import threading
assert isinstance(threading.Thread(name='Bob'), Named)

프로토콜의 실행 가능성은 상속되지 않습니다. 실행 가능 프로토콜의 하위 클래스는 클래스 계층 구조와 상관없이 명시적으로 표시된 경우에만 실행 가능합니다:

@runtime_checkable
class Iterable(Protocol):
    def __iter__(self): ...

# @runtime_checkable이 없으면 Reversible은 더 이상 실행 가능하지 않습니다.
@runtime_checkable
class Reversible(Iterable, Protocol):
    def __reversed__(self): ...

이 데코레이터는 프로토콜이 아닌 클래스에 적용될 때 TypeError 를 발생시킵니다.

참고

@runtime_checkable 은 필수 메서드나 속성의 존재 여부만 확인하며 타입 서명이나 형은 검사하지 않습니다. 예를 들어, ssl.SSLObject 는 클래스이므로 Callable 에 대한 issubclass() 검사를 통과합니다. 그러나 ssl.SSLObject.__init__ 메서드는 더 상세한 정보를 포함한 TypeError 를 발생시키기 위해서만 존재하며, 이로 인해 ssl.SSLObject 를 호출(인스턴스화)하는 것이 불가능합니다.

참고

실행 가능 프로토콜에 대한 isinstance() 검사는 비프로토콜 클래스에 대한 isinstance() 검사에 비해 매우 느릴 수 있습니다. 성능이 중요한 코드에서는 구조 검사를 위해 hasattr() 호출과 같은 대안적인 관용구를 사용하는 것을 고려하십시오.

Added in version 3.8.

버전 3.12에서 변경: 실행 가능 프로토콜에 대한 isinstance() 검사의 내부 구현이 이제 속성을 조회할 때 inspect.getattr_static() 을 사용합니다(이전에는 hasattr() 이 사용됨). 결과적으로, 이전에는 실행 가능 프로토콜의 인스턴스로 간주되던 일부 객체가 Python 3.12 이상 버전에서 해당 프로토콜의 인스턴스로 더 이상 인식되지 않거나 그 반대의 경우가 발생할 수 있습니다. 대부분의 사용자는 이 변경으로 인해 영향을 받지 않을 것입니다.

버전 3.12에서 변경: 실행 가능 프로토콜의 멤버는 클래스가 생성되는 즉시 실행 시점에 “동결(frozen)”된 것으로 간주됩니다. 실행 가능 프로토콜에 어트리뷰스를 몽키 패치(Monkey-patching)하는 것은 여전히 작동하지만, 객체를 프로토콜과 비교하는 isinstance() 검사에는 영향을 미치지 않습니다. 자세한 내용은 What’s new in Python 3.12 를 참조하십시오.

class typing.TypedDict(dict)¶

딕셔너리에 형 힌트를 추가하기 위한 특수 구조입니다. 실행 시 “TypedDict 인스턴스”는 단순히 dicts 입니다.

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'}           # 타입 검사 실패

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

TypedDict 를 생성하는 다른 방법은 함수 호출 구문을 사용하는 것입니다. 두 번째 인수는 리터럴 dict 이어야 합니다:

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

이 함수형 구문을 사용하면 키워드이거나 하이픈을 포함하는 등 유효한 identifiers 가 아닌 키를 정의할 수 있으며, 일반적인 비공개 이름처럼 키 이름이 mangled 되지 않아야 하는 경우에도 사용할 수 있습니다:

1. # SyntaxError 발생
class Point2D(TypedDict):
    in: int  # 'in'은 키워드임
    x-y: int  # 하이픈이 포함된 이름

class Definition(TypedDict):
    __schema: str  # `_Definition__schema`로 망글링됨

2. # OK, 함수형 구문
Point2D = TypedDict('Point2D', {'in': int, 'x-y': int})
Definition = TypedDict('Definition', {'__schema': str})  # 망글링되지 않음

기본적으로 TypedDict 의 모든 키가 존재해야 합니다. NotRequired 를 사용하여 개별 키를 선택 사항으로 표시할 수 있습니다:

class Point2D(TypedDict):
    x: int
    y: int
    label: NotRequired[str]

# 대체 구문
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': NotRequired[str]})

이는 Point2D TypedDict``에서 ``label 키가 생략될 수 있음을 의미합니다.

False 값을 지정하여 모든 키를 기본적으로 필수 사항이 아닌 것으로 표시할 수도 있습니다:

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

# 대안 구문
Point2D = TypedDict('Point2D', {'x': int, 'y': int}, total=False)

이는 Point2D TypedDict 에서 모든 키를 생략할 수 있음을 의미합니다. 형 검사기는 total 인자의 값으로 리터럴 False 또는 True 만 지원해야 합니다. 기본값은 True 이며, 이 경우 클래스 본문에 정의된 모든 항목이 필수 사항이 됩니다.

total=False 인 TypedDict 의 개별 키는 Required 를 사용하여 필수 사항으로 표시할 수 있습니다:

class Point2D(TypedDict, total=False):
    x: Required[int]
    y: Required[int]
    label: str

# 대안 구문
Point2D = TypedDict('Point2D', {
    'x': Required[int],
    'y': Required[int],
    'label': str
}, total=False)

클래스 기반 구문을 사용하여 TypedDict 형이 하나 이상의 다른 TypedDict 형을 상속받도록 할 수 있습니다. 사용법:

class Point3D(Point2D):
    z: int

Point3D``는 ``x, y, z 세 개의 항목을 가집니다. 이는 다음과 같은 정의와 동일합니다:

class Point3D(TypedDict):
    x: int
    y: int
    z: int

기본적으로 TypedDict 는 open 상태이므로, 실행 시점에 클래스 본문에 정의된 것 외에 추가적인 키를 포함할 수 있습니다. closed 클래스 인자를 사용하여 이를 제어할 수 있으며, closed=True 인 경우 TypedDict 에 추가 키를 포함할 수 없습니다.

class ClosedPoint(TypedDict, closed=True):
    x: int
    y: int

class ClosedPoint3D(ClosedPoint):  # 형 검사기 오류: 닫힌(closed) TypedDict에 키를 추가할 수 없음
    z: int

closed=False 를 설정하면 기본인 open 동작을 명시적으로 요청하게 됩니다. 인자를 전달하지 않으면 이 상태는 부모 클래스로부터 상속됩니다.

open 또는 closed 상태 외에도 TypedDict 가 추가 항목(extra items)을 갖도록 설정할 수 있습니다. extra_items 클래스 인자가 특정 형으로 설정되면 TypedDict 는 임의의 추가 키를 포함할 수 있지만, 해당 키들의 값은 지정된 형이어야 합니다.

class ExtraItemsPoint(TypedDict, extra_items=int):
    x: int
    y: int

point: ExtraItemsPoint = {'x': 1, 'y': 2, 'anything': 3}  # OK

extra_items 인자 또한 서브클래싱을 통해 상속됩니다. 기본값은 설정되지 않았으며, closed 인자와 함께 사용할 수 없습니다.

TypedDict 는 Generic 을 제외한 다른 비(non)-TypedDict 클래스를 상속할 수 없습니다. 예를 들어:

class X(TypedDict):
    x: int

class Y(TypedDict):
    y: int

class Z(object): pass  # TypedDict가 아닌 클래스

class XY(X, Y): pass  # OK

class XZ(X, Z): pass  # TypeError 발생

TypedDict 는 제네릭(generic)이 될 수 있습니다:

class Group[T](TypedDict):
    key: T
    group: list[T]

Python 3.11 이하 버전과 호환되는 제네릭 TypedDict 를 생성하려면 Generic 을 명시적으로 상속하십시오:

T = TypeVar("T")

class Group(TypedDict, Generic[T]):
    key: T
    group: list[T]

TypedDict 는 annotationlib.get_annotations() 및 다음 속성을 통해 내부 구조를 조사할 수 있습니다. (어노테이션 모범 사례에 대한 자세한 내용은 어노테이션 모범 사례 를 참조하십시오.)

__total__¶

Point2D.__total__``은 ``total 인자의 값을 반환합니다. 예제:

>>> from typing import TypedDict
>>> class Point2D(TypedDict): pass
>>> Point2D.__total__
True
>>> class Point2D(TypedDict, total=False): pass
>>> Point2D.__total__
False
>>> class Point3D(Point2D): pass
>>> Point3D.__total__
True

이 속성은 현재 TypedDict 클래스에 대한 total 인자의 값만을 반영하며, 클래스가 의미론적으로 전체(total)인지 여부를 나타내지는 않습니다. 예를 들어, __total__ 이 True 로 설정된 TypedDict 가 NotRequired 로 표시된 키를 가질 수 있으며, total=False 인 다른 TypedDict 로부터 상속받을 수도 있습니다. 따라서 내부 구조 조사 시에는 일반적으로 __required_keys__ 와 __optional_keys__ 를 사용하는 것이 좋습니다.

__required_keys__¶: Added in version 3.9.

__optional_keys__¶

Point2D.__required_keys__ 와 Point2D.__optional_keys__ 는 각각 필수 키와 선택적 키를 포함하는 frozenset 객체를 반환합니다.

Required 로 표시된 키는 항상 __required_keys__ 에 나타나며, NotRequired 로 표시된 키는 항상 __optional_keys__ 에 나타납니다.

Python 3.10 이하 버전과의 하위 호환성을 위해, 상속을 사용하여 동일한 TypedDict 내에 필수 및 선택적 키를 모두 선언하는 것도 가능합니다. 이는 total 인자에 하나의 값을 갖는 TypedDict 를 정의하고, 다른 total 값을 가진 또 다른 TypedDict 에서 이를 상속받음으로써 수행됩니다.

>>> class Point2D(TypedDict, total=False):
...     x: int
...     y: int
...
>>> class Point3D(Point2D):
...     z: int
...
>>> Point3D.__required_keys__ == frozenset({'z'})
True
>>> Point3D.__optional_keys__ == frozenset({'x', 'y'})
True

Added in version 3.9.

참고

from __future__ import annotations 를 사용하거나 어노테이션이 문자열로 제공되는 경우, TypedDict 정의 시점에 어노테이션이 평가되지 않습니다. 따라서 __required_keys__ 와 __optional_keys__ 가 의존하는 실행 시간 기반의 내부 구조 조사가 제대로 작동하지 않을 수 있으며, 속성 값이 정확하지 않을 수 있습니다.

__readonly_keys__¶: 모든 읽기 전용 키의 이름을 포함하는 frozenset 입니다. ReadOnly 한정자가 붙은 키는 읽기 전용으로 간주됩니다.

Added in version 3.13.

__mutable_keys__¶: 모든 가변 키의 이름을 포함하는 frozenset 입니다. ReadOnly 한정자가 없는 키는 가변으로 간주됩니다.

Added in version 3.13.

__closed__¶: closed 클래스 인자의 값입니다. 이 값은 True, False 또는 None 일 수 있습니다.

__extra_items__¶: extra_items 클래스 인자의 값입니다. 이 값은 유효한 형(type)이거나 NoExtraItems 일 수 있습니다.

더 많은 예제와 자세한 규칙은 typing 문서의 TypedDict 섹션을 참조하십시오.

Added in version 3.8.

버전 3.9에서 변경: TypedDict 는 이제 클래스가 아니라 함수입니다. 위에 설명한 것처럼 여전히 클래스 기반으로 사용될 수 있습니다.

버전 3.11에서 변경: 개별 키를 Required 또는 NotRequired 로 표시하는 기능이 추가되었습니다. PEP 655 를 참조하십시오.

버전 3.11에서 변경: 제네릭 TypedDict 지원 기능이 추가되었습니다.

버전 3.13에서 변경: TypedDict 를 생성하는 키워드 인자 방식의 지원을 제거했습니다.

버전 3.13에서 변경: ReadOnly 한정자 지원이 추가되었습니다. PEP 705 를 참조하십시오.

버전 3.15에서 변경: closed 및 extra_items 클래스 인자 지원이 추가되었습니다. PEP 728 을 참조하십시오.

프로토콜¶

다음 프로토콜들이 typing 모듈에서 제공됩니다. 모두 @runtime_checkable 으로 데코레이션되어 있습니다.

class typing.SupportsAbs¶: 반환형이 공변적인(covariant) 하나의 추상 메서드 __abs__ 를 가진 프로토콜입니다.

class typing.SupportsBytes¶: 하나의 추상 메서드 __bytes__ 를 가진 프로토콜입니다.

class typing.SupportsComplex¶: 하나의 추상 메서드 __complex__ 를 가진 프로토콜입니다.

class typing.SupportsFloat¶: 하나의 추상 메서드 __float__ 를 가진 프로토콜입니다.

class typing.SupportsIndex¶: 하나의 추상 메서드 __index__ 를 가진 프로토콜입니다.

Added in version 3.8.

class typing.SupportsInt¶: 하나의 추상 메서드 __int__ 를 가진 프로토콜입니다.

class typing.SupportsRound¶: 반환형이 공변적인(covariant) 하나의 추상 메서드 __round__ 를 가진 프로토콜입니다.

I/O 작업을 위한 ABC 및 Protocol¶

class typing.IO[AnyStr]¶
class typing.TextIO¶
class typing.BinaryIO¶: 제네릭 클래스 IO[AnyStr] 와 그 하위 클래스인 TextIO(IO[str]) 및 BinaryIO(IO[bytes]) 는 open() 이 반환하는 것과 같은 I/O 스트림의 형을 나타냅니다. 이 클래스들은 프로토콜이 아니며 인터페이스가 상당히 넓다는 점에 유의하십시오.

io.Reader 및 io.Writer 프로토콜은 각각 read() 또는 write() 메서드만 접근할 때 더 간단한 인자 형의 대안을 제공합니다:

def read_and_write(reader: Reader[str], writer: Writer[bytes]):
    data = reader.read()
    writer.write(data.encode())

입력 스트림의 라인을 반복할 때는 collections.abc.Iterable 을 사용하는 것도 고려해 보십시오:

def read_config(stream: Iterable[str]):
    for line in stream:
        ...

함수와 데코레이터¶

typing.cast(typ, val)¶

값을 형으로 변환합니다.

값을 변경하지 않고 반환합니다. 형 검사기에서는 반환 값이 지정된 형임을 나타내지만, 실행 시간에는 의도적으로 아무것도 확인하지 않습니다 (우리는 이것이 가능한 한 빠르기를 원합니다).

typing.assert_type(val, typ, /)¶

정적 형 검사기에게 val 의 추론된 형이 typ 인지 확인하도록 요청합니다.

실행 시 이 함수는 아무것도 수행하지 않습니다. 인자의 실제 형에 관계없이 검사나 부수 효과 없이 첫 번째 인자를 그대로 반환합니다.

정적 형 검사기가 assert_type() 호출을 만나면 값이 지정된 형이 아닐 경우 에러를 발생시킵니다:

def greet(name: str) -> None:
    assert_type(name, str)  # 확인됨, `name`의 추론 형이 `str`임
    assert_type(name, int)  # 형 검사기 오류

이 함수는 형 검사기가 스크립트를 이해하는 방식이 개발자의 의도와 일치하는지 확인하는 데 유용합니다:

def complex_function(arg: object):
    # 복잡한 형 축소 로직을 수행하고,
    # 그 이후 추론된 형이 `int`가 되기를 기대함
    ...
    # 형 검사기가 우리의 함수를 올바르게 이해하는지 테스트
    assert_type(arg, int)

Added in version 3.11.

typing.assert_never(arg, /)¶

정적 형 검사기에게 특정 코드 줄에 도달할 수 없음을 확인하도록 요청합니다.

예제:

def int_or_str(arg: int | str) -> None:
    match arg:
        case int():
            print("It's an int")
        case str():
            print("It's a str")
        case _ as unreachable:
            assert_never(unreachable)

여기서는 어노테이션을 통해 형 검사기가 마지막 케이스가 실행될 수 없음을 추론할 수 있게 합니다. 왜냐하면 arg 는 int 또는 str 중 하나이며, 두 경우 모두 이전 케이스에서 처리되기 때문입니다.

형 검사기가 assert_never() 호출이 가능하다고 판단하면 에러를 발생시킵니다. 예를 들어, arg 의 형 어노테이션이 int | str | float 였다면, 형 검사기는 unreachable 이 float 형임을 지적하며 에러를 발생시킬 것입니다. assert_never 호출이 형 검사를 통과하려면 전달된 인자의 추론 형이 반드시 하위 타입인 Never 여야 하며 다른 형이어서는 안 됩니다.

실행 시 이 함수는 호출될 때 예외를 발생시킵니다.

Unreachable Code and Exhaustiveness Checking has more information about exhaustiveness checking with static typing.

Added in version 3.11.

typing.reveal_type(obj, /)¶

정적 형 검사기에게 표현식의 추론된 형을 공개하도록 요청합니다.

정적 형 검사기가 이 함수 호출을 만나면 인자의 추론된 형을 포함한 진단 메시지를 출력합니다. 예제:

x: int = 1
reveal_type(x)  # 공개된 형은 "builtins.int"

형 검사기가 특정 코드 부분을 어떻게 처리하는지 디버깅할 때 유용합니다.

실행 시 이 함수는 인자의 실행 시간 형을 sys.stderr 에 출력하고 인자를 변경 없이 반환합니다(이로 인해 호출이 표현식 내에서 사용될 수 있습니다::)

x = reveal_type(1)  # "Runtime type is int" 출력
print(x)  # "1" 출력

실행 시 형이 형 검사기에 의해 정적으로 추론된 형과 다를 수 있음(더 구체적이거나 덜 구체적일 수 있음)에 유의하십시오.

대부분의 형 검사기는 이름을 typing 에서 가져오지 않더라도 어디에서든 reveal_type() 을 지원합니다. 그러나 이름을 typing 에서 가져오면 코드 실행 시 오류가 발생하지 않으며 의도를 더 명확하게 전달할 수 있습니다.

Added in version 3.11.

@typing.dataclass_transform(*, eq_default=True, order_default=False, kw_only_default=False, frozen_default=False, field_specifiers=(), **kwargs)¶

객체가 dataclass 와 유사한 동작을 제공함을 나타내는 데코레이터입니다.

@dataclass_transform 은 클래스, 메타클래스 또는 데코레이터 역할을 하는 함수를 데코레이트하는 데 사용될 수 있습니다. @dataclass_transform() 의 존재는 정적 형 검사기에게 데코레이트된 객체가 @dataclasses.dataclass 와 유사한 방식으로 클래스를 변환하는 런타임 “매직”을 수행함을 알립니다.

데코레이터 함수를 사용한 예시:

@dataclass_transform()
def create_model[T](cls: type[T]) -> type[T]:
    ...
    return cls

@create_model
class CustomerModel:
    id: int
    name: str

베이스 클래스에서:

@dataclass_transform()
class ModelBase: ...

class CustomerModel(ModelBase):
    id: int
    name: str

메타클래스에서:

@dataclass_transform()
class ModelMeta(type): ...

class ModelBase(metaclass=ModelMeta): ...

class CustomerModel(ModelBase):
    id: int
    name: str

위에서 정의된 CustomerModel 클래스들은 형 검사기에 의해 @dataclasses.dataclass`로 생성된 클래스와 유사하게 취급됩니다. 예를 들어, 형 검사기는 이 클래스들이 ``id``와 ``name``을 수락하는 ``__init__` 메서드를 가지고 있다고 가정합니다.

데코레이트된 클래스, 메타클래스 또는 함수는 다음과 같은 불리언(bool) 인수를 받을 수 있으며, 형 검사기는 이들이 @dataclasses.dataclass 데코레이터에서와 동일한 효과를 가질 것으로 간주합니다: init, eq, order, unsafe_hash, frozen, match_args, kw_only 및 slots. 이러한 인자들의 값(True 또는 False)은 정적으로 평가 가능해야 합니다.

@dataclass_transform 데코레이터의 인자를 사용하여 데코레이트된 클래스, 메타클래스 또는 함수의 기본 동작을 사용자 정의할 수 있습니다:

매개변수:

eq_default (bool) – 호출자가 생략했을 때 eq 매개변수를 True 로 간주할지 False 로 간주할지 여부를 나타냅니다. 기본값은 True 입니다.
order_default (bool) – 호출자가 생략했을 때 order 매개변수를 True 로 간주할지 False 로 간주할지 여부를 나타냅니다. 기본값은 False 입니다.
kw_only_default (bool) – 호출자가 생략했을 때 kw_only 매개변수를 True 로 간주할지 False 로 간주할지 여부를 나타냅니다. 기본값은 False 입니다.
frozen_default (bool) – 호출자가 생략했을 때 frozen 매개변수를 True 로 간주할지 False 로 간주할지 여부를 나타냅니다. 기본값은 False 입니다. .. versionadded:: 3.12
field_specifiers (tuple[Callable[..., Any], ...]) – dataclasses.field() 와 유사하게 필드를 설명하는 지원되는 클래스 또는 함수의 정적 리스트를 지정합니다. 기본값은 () 입니다.
**kwargs (Any) – 향후 확장을 위해 임의의 다른 키워드 인자를 허용합니다.

형 검사기는 필드 지정자에서 다음 선택적 매개변수를 인식합니다:

**필드 지정체용 인식된 매개변수**¶
매개변수 이름	설명
`init`	필드가 생성된 `__init__` 메서드에 포함되어야 하는지 여부를 나타냅니다. 지정되지 않은 경우 `init` 은 `True` 를 기본값으로 합니다.
`default`	필드의 기본값을 제공합니다.
`default_factory`	필드의 기본값을 반환하는 런타임 콜백을 제공합니다. `default` 또는 `default_factory` 가 지정되지 않은 경우, 해당 필드는 기본값이 없는 것으로 간주되며 클래스 인스턴스화 시 값이 제공되어야 합니다.
`factory`	필드 지정체에서 `default_factory` 매개변수의 별칭입니다.
`kw_only`	필드가 키워드 전용(keyword-only)으로 표시되어야 하는지 여부를 나타냅니다. True``인 경우 필드는 키워드 전용이 되며, ``False``인 경우 키워드 전용이 되지 않습니다. 지정되지 않은 경우 ``@dataclass_transform``으로 데코레이트된 객체의 ``kw_only 매개변수 값을 사용하며, 해당 값이 지정되지 않은 경우 @dataclass_transform``의 ``kw_only_default 값을 사용합니다.
`alias`	필드의 대체 이름을 제공합니다. 이 대체 이름은 생성된 `__init__` 메서드에서 사용됩니다.

런타임에 이 데코레이터는 데코레이트된 객체의 __dataclass_transform__ 속성에 자신의 인자들을 기록합니다. 그 외에 다른 런타임 효과는 없습니다.

자세한 내용은 PEP 681 을 참조하십시오.

Added in version 3.11.

@typing.overload¶

오버로드된 함수 및 메서드를 생성하기 위한 데코레이터입니다.

@overload 데코레이터는 여러 가지 다른 인자 유형의 조합을 지원하는 함수와 메서드를 설명할 수 있게 해줍니다. @overload 로 데코레이트된 일련의 정의 뒤에는 (동일한 함수/메서드에 대해) 정확히 하나가 아닌 @overload 로 데코레이트되지 않은 정의가 따라야 합니다.

@overload 로 데코레이트된 정의는 비-@overload 로 데코레이트된 정의에 의해 덮어써지기 때문에 형 검사기만을 위한 것입니다. 반면, 비-@overload 로 데코레이트된 정의는 실행 시 사용되지만 형 검사기에서는 무시되어야 합니다. 런타임에 @overload 로 데코레이트된 함수를 직접 호출하면 NotImplementedError 가 발생합니다.

union이나 타입 변수를 사용하여 표현할 수 있는 것보다 더 정밀한 형을 제공하는 오버로드 예시:

@overload
def process(response: None) -> None:
    ...
@overload
def process(response: int) -> tuple[int, str]:
    ...
@overload
def process(response: bytes) -> str:
    ...
def process(response):
    ...  # 실제 구현이 여기에 들어감

자세한 내용 및 다른 타이핑 의미론과의 비교는 PEP 484 를 참조하십시오.

버전 3.11에서 변경: 오버로드된 함수는 이제 get_overloads() 를 사용하여 런타임에 조사할 수 있습니다.

typing.get_overloads(func)¶

func 에 대해 @overload 로 데코레이트된 정의 시퀀스를 반환합니다.

func 은 오버로드된 함수의 구현에 대한 함수 객체입니다. 예를 들어, @overload 문서에 있는 process 정의를 고려할 때 get_overloads(process) 는 정의된 세 개의 오버로드에 대해 세 개의 함수 객체 시퀀스를 반환합니다. 오버로드가 없는 함수에서 호출하면 get_overloads() 는 빈 시퀀스를 반환합니다.

get_overloads() 는 런타임에 오버로드된 함수를 조사하는 데 사용할 수 있습니다.

Added in version 3.11.

typing.clear_overloads()¶

내부 레지스트리에 등록된 모든 오버로드를 삭제합니다.

이것은 레지스트리에서 사용되는 메모리를 회수하는 데 사용될 수 있습니다.

Added in version 3.11.

@typing.final¶

최종(final) 메서드 및 최종 클래스를 나타내는 데코레이터입니다.

메서드를 @final 으로 데코레이트하면 형 검사기에게 해당 메서드가 서브 클래스에서 재정의될 수 없음을 알립니다. 클래스를 @final 로 데코레이트하면 서브 클래스로 확장될 수 없음을 나타냅니다.

예를 들면:

class Base:
    @final
    def done(self) -> None:
        ...
class Sub(Base):
    def done(self) -> None:  # 형 검사기에 의해 오류 보고
        ...

@final
class Leaf:
    ...
class Other(Leaf):  # 형 검사기에 의해 오류 보고
    ...

이러한 속성에 대한 실행 시간 검사는 없습니다. 자세한 내용은 PEP 591을 참조하십시오.

Added in version 3.8.

버전 3.11에서 변경: 데코레이터는 이제 데코레이트된 객체에 __final__ 속성을 True 로 설정하려고 시도합니다. 따라서 런타임에 if getattr(obj, "__final__", False) 와 같은 검사를 통해 객체 obj 가 최종으로 표시되었는지 확인하는 것이 가능합니다. 데코레이트된 객체가 속성 설정을 지원하지 않는 경우, 데코레이터는 예외를 발생시키지 않고 객체를 변경하지 않은 상태로 반환합니다.

@typing.no_type_check¶

어노테이션이 형 힌트가 아님을 나타내는 데코레이터.

This works as a class or function decorator. With a class, it applies recursively to all methods and classes defined in that class (but not to methods defined in its superclasses or subclasses). Type checkers will ignore all annotations in a function or class with this decorator.

@no_type_check 는 데코레이트된 객체를 제자리(in-place)에서 변형합니다.

@typing.override¶

서브클래스의 메서드가 슈퍼클래스의 메서드 또는 속성을 재정의하려는 의도가 있음을 나타내는 데코레이터입니다.

@override 로 데코레이트된 메서드가 실제로 아무것도 재정의하지 않는 경우 형 검사기가 에러를 발생시켜야 합니다. 이는 베이스 클래스가 변경될 때 자식 클래스에 상응하는 변경이 없는 경우 발생할 수 있는 버그를 방지하는 데 도움이 됩니다.

예:

class Base:
    def log_status(self) -> None:
        ...

class Sub(Base):
    @override
    def log_status(self) -> None:  # 확인됨: Base.log_status 재정의
        ...

    @override
    def done(self) -> None:  # 형 검사기에 의해 오류 보고
        ...

이 속성에 대한 실행 시간 검사는 없습니다.

데코레이터는 데코레이트된 객체에 __override__ 속성을 True 로 설정하려고 시도합니다. 따라서 런타임에 if getattr(obj, "__override__", False) 와 같은 검사를 통해 객체 obj 가 재정의로 표시되었는지 확인하는 것이 가능합니다. 데코레이트된 객체가 속성 설정을 지원하지 않는 경우, 데코레이터는 예외를 발생시키지 않고 객체를 변경하지 않은 상태로 반환합니다.

자세한 내용은 PEP 698 을 참조하십시오.

Added in version 3.12.

@typing.disjoint_base¶

클래스를 분리된 베이스(disjoint base)로 표시하는 데코레이터입니다.

형 검사기는 분리된 베이스 C 의 자식 클래스가 C 의 부모 또는 자식 클래스가 아닌 다른 분리된 베이스를 상속받는 것을 허용하지 않습니다.

예를 들면:

@disjoint_base
class Disjoint1: pass

@disjoint_base
class Disjoint2: pass

class Disjoint3(Disjoint1, Disjoint2): pass  # 형 검사기 오류

형 검사기는 분리된 베이스에 대한 정보를 사용하여 도달할 수 없는 코드를 감지하고 두 형이 겹칠 수 있는 시점을 결정할 수 있습니다.

이에 대응하는 런타임 개념은 견고한 베이스(solid base)입니다(참조: 다중 상속). 런타임에서 견고한 베이스인 클래스는 스텁 파일에서 @disjoint_base 로 표시할 수 있습니다. 사용자는 다른 클래스도 분리된 베이스로 표시하여 형 검사기에게 다른 분리된 베이스와의 다중 상속이 허용되지 않음을 알릴 수 있습니다.

견고한 베이스의 개념은 CPython 구현 세부 사항이며, 런타임에서 분리된 베이스인 표준 라이브러리 클래스의 정확한 집합은 향후 파이썬 버전에서 변경될 수 있음에 유의하십시오.

Added in version 3.15.

@typing.type_check_only¶

클래스 또는 함수를 실행 시 사용할 수 없는 것으로 표시하는 데코레이터입니다.

이 데코레이터 자체는 실행 시간에 사용할 수 없습니다. 주로, 구현이 비공개 클래스의 인스턴스를 반환할 때, 형 스텁 파일에 정의된 클래스를 표시하기 위한 용도입니다:

@type_check_only
class Response:  # 비공개 또는 실행 시 사용 불가
    code: int
    def get_header(self, name: str) -> str: ...

def fetch_response() -> Response: ...

비공개 클래스의 인스턴스를 반환하는 것은 좋지 않음에 유의하십시오. 일반적으로 그러한 클래스를 공개로 만드는 것이 바람직합니다.

인트로스펙션 도우미¶

typing.get_type_hints(obj, globalns=None, localns=None, include_extras=False, *, format=Format.VALUE)¶

함수, 메서드, 모듈, 클래스 객체 또는 기타 호출 가능 객체에 대한 형 힌트가 포함된 딕셔너리를 반환합니다.

이것은 종종 annotationlib.get_annotations() 와 같지만, 이 함수는 어노테이션 딕셔너리에 다음과 같은 변경을 가합니다.

문자열 리터럴 또는 ForwardRef 객체로 인코딩된 전방 참조는 globalns, localns, 그리고 (해당하는 경우) obj 의 type parameter 네임스페이스에서 평가하여 처리됩니다. globalns 나 localns 가 제공되지 않은 경우, obj 로부터 적절한 네임스페이스 딕셔너리가 추론됩니다.
None 이 types.NoneType 으로 교체됩니다.
obj 에 @no_type_check 가 적용된 경우, 빈 딕셔너리가 반환됩니다.
obj 이 클래스 C 인 경우, 이 함수는 C 의 베이스 클래스에서 온 어노테이션과 C 에 직접 있는 어노테이션을 병합한 딕셔너리를 반환합니다. 이는 C.__mro__ 를 탐색하고 각 베이스 클래스의 annotations 을 반복적으로 결합함으로써 수행됩니다. method resolution order 에서 더 먼저 나타나는 클래스의 어노테이션은 항상 나중에 나타나는 클래스의 어노테이션보다 우선합니다.
include_extras 가 True 로 설정되지 않은 경우, 이 함수는 Annotated[T, ...], Required[T], NotRequired[T], 그리고 ReadOnly[T] 의 모든 발생 사례를 T 로 재귀적으로 대체합니다. 자세한 내용은 Annotated 를 참조하십시오.

조심

이 함수는 어노테이션에 포함된 임의의 코드를 실행할 수 있습니다. 자세한 내용은 어노테이션 분석 시의 보안 영향 를 참조하십시오.

참고

만약 Format.VALUE 가 사용되는 상황에서 obj 의 어노테이션에 포함된 전방 참조(forward references)를 해결할 수 없는 경우, NameError 예외가 발생합니다. 예를 들어, 이 현상은 if TYPE_CHECKING 블록 아래에서 가져온 이름이 있는 경우 발생할 수 있습니다. 더 일반적으로, 어노테이션에 잘못된 파이썬 코드가 포함되어 있으면 어떤 종류의 예외든 발생할 수 있습니다.

참고

인스턴스에 대해 get_type_hints() 를 호출하는 것은 지원되지 않습니다. 인스턴스의 어노테이션을 가져오려면 대신 해당 인스턴스의 클래스에 대해 get_type_hints() 를 호출하십시오 (예: get_type_hints(type(obj))).

버전 3.9에서 변경: PEP 593 의 일부로 include_extras 매개변수가 추가되었습니다. 자세한 내용은 Annotated 문서를 참조하십시오.

버전 3.11에서 변경: 이전에는 기본값이 None 인 경우 함수 및 메서드 어노테이션에 Optional[t] 가 추가되었으나, 이제는 어노테이션이 변경되지 않은 상태로 반환됩니다.

버전 3.14에서 변경: format 매개변수가 추가되었습니다. 자세한 내용은 annotationlib.get_annotations() 문서를 참조하십시오.

버전 3.14에서 변경: 인스턴스에 대해 get_type_hints() 를 호출하는 기능은 더 이상 지원되지 않습니다. 이전 버전에서는 문서화되지 않은 구현 세부 사항으로 일부 인스턴스가 허용되었습니다.

typing.get_origin(tp)¶

형의 구독되지 않은(unsubscripted) 버전을 가져옵니다. 형이 X[Y, Z, ...] 형태인 경우 X 를 반환합니다.

X 가 내장형 또는 collections 클래스에 대한 typing 모듈의 에일리어스인 경우, 원래의 클래스로 정규화됩니다. X 가 ParamSpecArgs 또는 ParamSpecKwargs 의 인스턴스인 경우, 기반이 되는 ParamSpec 을 반환합니다. 지원되지 않는 객체에 대해서는 None 을 반환합니다.

예제:

assert get_origin(str) is None
assert get_origin(Dict[str, int]) is dict
assert get_origin(Union[int, str]) is Union
assert get_origin(Annotated[str, "metadata"]) is Annotated
P = ParamSpec('P')
assert get_origin(P.args) is P
assert get_origin(P.kwargs) is P

Added in version 3.8.

typing.get_args(tp)¶

모든 치환이 완료된 형 인자들을 가져옵니다. 형이 X[Y, Z, ...] 형태인 경우 (Y, Z, ...) 를 반환합니다.

X 가 다른 제네릭 형에 포함된 union 또는 Literal 인 경우, 형식 캐싱으로 인해 (Y, Z, ...) 의 순서가 원래 인자 [Y, Z, ...] 의 순서와 다를 수 있습니다. 지원되지 않는 객체에 대해서는 () 를 반환합니다.

예제:

assert get_args(int) == ()
assert get_args(Dict[int, str]) == (int, str)
assert get_args(Union[int, str]) == (int, str)

Added in version 3.8.

typing.get_protocol_members(tp)¶

Protocol 에서 정의된 멤버들의 집합을 반환합니다.

>>> from typing import Protocol, get_protocol_members
>>> class P(Protocol):
...     def a(self) -> str: ...
...     b: int
>>> get_protocol_members(P) == frozenset({'a', 'b'})
True

Protocol이 아닌 인자에 대해 TypeError 를 발생시킵니다.

Added in version 3.13.

typing.is_protocol(tp)¶

형이 Protocol 인지 확인합니다.

예:

class P(Protocol):
    def a(self) -> str: ...
    b: int

assert is_protocol(P)
assert not is_protocol(int)

이 함수는 이들의 generic aliases 가 아닌 Protocol 클래스에 대해서만 True를 반환합니다.

class GenericP[T](Protocol):
    def a(self) -> T: ...
    b: int

assert not is_protocol(GenericP[int])

Added in version 3.13.

typing.is_typeddict(tp)¶

형이 TypedDict 인지 확인합니다.

예:

class Film(TypedDict):
    title: str
    year: int

assert is_typeddict(Film)
assert not is_typeddict(list | str)

# TypedDict는 typed dict를 생성하기 위한 팩토리이며,
# 그 자체로 typed dict가 아닙니다
assert not is_typeddict(TypedDict)

이 함수는 이들의 generic aliases <types-genericalias>`가 아닌 ``TypedDict` 클래스에 대해서만 True를 반환합니다.

class GenericFilm[T](TypedDict):
    title: str
    year: T

assert not is_typeddict(GenericFilm[int])

Added in version 3.10.

class typing.ForwardRef¶

문자열 전방 참조의 내부 형 표현을 위해 사용되는 클래스입니다.

예를 들어, List["SomeClass"] 는 명시적으로 List[ForwardRef("SomeClass")] 로 변환됩니다. ForwardRef 는 사용자가 인스턴스화해서는 안 되지만, 내성(introspection) 도구에서 사용될 수 있습니다.

참고

list["SomeClass"] 와 같은 PEP 585 제네릭 형은 list[ForwardRef("SomeClass")] 로 자동 변환되지 않으므로, 자동으로 list[SomeClass] 로 해결되지 않습니다.

Added in version 3.7.4.

버전 3.14에서 변경: 이것은 이제 annotationlib.ForwardRef 의 에일리어스입니다. 이 클래스의 몇 가지 문서화되지 않은 동작이 변경되었습니다. 예를 들어, ForwardRef 가 평가된 후 평가된 값이 더 이상 캐싱되지 않습니다.

typing.evaluate_forward_ref(forward_ref, *, owner=None, globals=None, locals=None, type_params=None, format=annotationlib.Format.VALUE)¶

Evaluate an annotationlib.ForwardRef as a type hint.

이것은 annotationlib.ForwardRef.evaluate`를 호출하는 것과 유사하지만, 해당 메서드와 달리 :func:()!evaluate_forward_ref`는 형 힌트 내에 중첩된 전방 참조도 재귀적으로 평가합니다.

owner, globals, locals, type_params, format 매개변수의 의미는 annotationlib.ForwardRef.evaluate() 문서를 참조하십시오.

조심

이 함수는 어노테이션에 포함된 임의의 코드를 실행할 수 있습니다. 자세한 내용은 어노테이션 분석 시의 보안 영향 를 참조하십시오.

Added in version 3.14.

typing.NoDefault¶

형 파라미터에 기본값이 없음을 나타내는 데 사용되는 감시(sentinel) 객체입니다. 예를 들어:

>>> T = TypeVar("T")
>>> T.__default__ is typing.NoDefault
True
>>> S = TypeVar("S", default=None)
>>> S.__default__ is None
True

Added in version 3.13.

typing.NoExtraItems¶

TypedDict 이 extra_items 클래스 인수를 가지고 있지 않음을 나타내는 데 사용되는 sentinel 객체입니다.

>>> from typing import TypedDict, NoExtraItems
>>> class Point(TypedDict):
...     x: int
...     y: int
...
>>> Point.__extra_items__ is NoExtraItems
True

상수¶

typing.TYPE_CHECKING¶

정적 형 검사기에서 True 로 간주되는 특수 상수입니다. 실행 시에는 False 입니다.

가져오기 비용이 크고 형 어노테이션에 사용되는 형들만 포함하는 모듈은 if TYPE_CHECKING: 블록 내에서 안전하게 가져올 수 있습니다. 이를 통해 런타임 시 실제로 모듈이 로드되는 것을 방지합니다. 어노테이션은 즉시 평가되지 않으므로(참조: PEP 649), 나중에 검사하지 않는 한 어노테이션에 정의되지 않은 심볼을 사용하는 것은 무해합니다. 정적 형 분석 도구는 정적 형 분석 중에 TYPE_CHECKING 을 True 로 설정하며, 이 경우 해당 모듈이 로드되고 형이 제대로 확인됩니다.

용법:

if TYPE_CHECKING:
    import expensive_mod

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

정의되지 않은 심볼을 포함할 수 있는 형 어노테이션을 실행 시에 검사해야 하는 경우, annotationlib.get_annotations() 를 사용하고 format 매개변수에 annotationlib.Format.STRING 또는 annotationlib.Format.FORWARDREF 를 전달하여 NameError 없이 안전하게 어노테이션을 가져오십시오.

Added in version 3.5.2.

폐지된 에일리어스¶

이 모듈은 기존 표준 라이브러리 클래스에 대한 여러 폐지된 에일리어스를 정의합니다. 이들은 원래 [] 를 사용하여 이러한 제네릭 클래스를 매개변수화하기 위해 typing 모듈에 포함되었습니다. 그러나 Python 3.9에서 해당 기존 클래스들이 [] 를 지원하도록 개선되면서(참조: PEP 585) 이 에일리어스들은 불필요해졌습니다.

중복된 형은 Python 3.9부터 폐지되었습니다. 다만 이 에일리어스들이 조만간 제거될 수는 있으나 현재로서는 삭제 계획이 없습니다. 따라서 인터프리터는 현재 이 에일리어스에 대해 폐지 경고를 발생시키지 않습니다.

만약 향후 이러한 폐지된 에일리어스들을 제거하기로 결정될 경우, 인터프리터는 삭제 최소 두 버전 전부터 폐지 경고를 발생시킬 것입니다. 해당 에일리어스들은 최소한 Python 3.14까지는 typing 모듈에 경고 없이 유지됨이 보장됩니다.

검사 대상 프로그램이 최소 Python 3.9 이상 버전을 대상으로 하는 경우, 형 검사기는 폐지된 형의 사용을 표시하도록 권장됩니다.

내장형에 대한 에일리어스¶

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

dict 의 폐지된 에일리어스입니다.

인자를 어노테이션할 때는 dict 또는 typing.Dict 대신 Mapping 과 같은 추상 컬렉션 형을 사용하는 것이 권장됩니다.

버전 3.9부터 폐지됨: builtins.dict 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

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

list 에 대한 사용이 권장되지 않는 에일리어스입니다.

인자를 어노테이트할 때는 list 또는 typing.List 를 사용하는 대신 Sequence 또는 Iterable 와 같은 추상 컬렉션 형을 사용하는 것이 좋습니다.

버전 3.9부터 폐지됨: builtins.list 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Set(set, MutableSet[T])¶

builtins.set 에 대한 사용이 권장되지 않는 에일리어스입니다.

인자를 어노테이트할 때는 set 또는 typing.Set 을 사용하는 대신 collections.abc.Set 과 같은 추상 컬렉션 형을 사용하는 것이 좋습니다.

버전 3.9부터 폐지됨: builtins.set 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.FrozenSet(frozenset, AbstractSet[T_co])¶: builtins.frozenset 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: builtins.frozenset 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

typing.Tuple¶

tuple 에 대한 사용이 권장되지 않는 에일리어스입니다.

tuple 과 Tuple 은 타입 시스템에서 특별하게 처리됩니다. 자세한 내용은 튜플 어노테이션 를 참고하십시오.

버전 3.9부터 폐지됨: builtins.tuple 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Type(Generic[CT_co])¶

type 에 대한 사용이 권장되지 않는 에일리어스입니다.

타입 어노테이션에서 type 또는 typing.Type 을 사용하는 방법에 대한 자세한 내용은 클래스 객체의 형 를 참조하십시오.

Added in version 3.5.2.

버전 3.9부터 폐지됨: builtins.type 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

`collections` 내 타입들의 에일리어스¶

class typing.DefaultDict(collections.defaultdict, MutableMapping[KT, VT])¶: collections.defaultdict 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.5.2.

버전 3.9부터 폐지됨: collections.defaultdict 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.OrderedDict(collections.OrderedDict, MutableMapping[KT, VT])¶: collections.OrderedDict 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.7.2.

버전 3.9부터 폐지됨: collections.OrderedDict 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.ChainMap(collections.ChainMap, MutableMapping[KT, VT])¶: collections.ChainMap 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.6.1.

버전 3.9부터 폐지됨: collections.ChainMap 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Counter(collections.Counter, Dict[T, int])¶: collections.Counter 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.6.1.

버전 3.9부터 폐지됨: collections.Counter 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Deque(deque, MutableSequence[T])¶: collections.deque 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.6.1.

버전 3.9부터 폐지됨: collections.deque 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

기타 구체적인 타입에 대한 에일리어스¶

class typing.Pattern¶

class typing.Match¶

re.compile() 및 re.search() 의 반환형에 해당하는 사용이 권장되지 않는 에일리어스입니다.

이 타입들(및 해당 함수)은 AnyStr 에 대해 제네릭합니다. Pattern 은 Pattern[str] 또는 Pattern[bytes] 로 구체화할 수 있으며, Match 는 Match[str] 또는 Match[bytes] 로 구체화할 수 있습니다.

버전 3.9부터 폐지됨: re의 클래스 Pattern과 Match는 이제 []를 지원합니다. PEP 585와 제네릭 에일리어스 형을 참조하십시오.

class typing.Text¶

str 에 대한 사용이 권장되지 않는 에일리어스입니다.

Text 는 파이썬 2 코드와의 하위 호환성을 제공하기 위해 제공됩니다. 파이썬 2에서 Text 는 unicode 의 에일리어스입니다.

Text를 사용하여 값이 파이썬 2와 파이썬 3 모두와 호환되는 방식으로 유니코드 문자열을 포함해야 함을 나타내십시오:

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

Added in version 3.5.2.

버전 3.11부터 폐지됨: 파이썬 2는 더 이상 지원되지 않으며, 대부분의 타입 검사기 또한 파이썬 2 코드에 대한 타입 검사를 지원하지 않습니다. 에일리어스 삭제는 현재 계획되어 있지 않으나, 사용자는 Text 대신 str 을 사용할 것을 권장합니다.

`collections.abc` 내 컨테이너 ABC에 대한 에일리어스¶

class typing.AbstractSet(Collection[T_co])¶: collections.abc.Set 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Set 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.ByteString(Sequence[int])¶

collections.abc.ByteString 에 대한 사용이 권장되지 않는 에일리어스입니다.

런타임에 obj 가 buffer protocol 을 구현하는지 확인하려면 isinstance(obj, collections.abc.Buffer) 를 사용하십시오. 타입 어노테이션에 사용할 때는 Buffer 를 사용하거나 코드에서 지원하는 유형을 명시적으로 지정하는 유니온(예: bytes | bytearray | memoryview)을 사용하십시오.

ByteString 은 원래 bytes 와 bytearray 모두의 상위 타입 역할을 하는 추상 클래스로 설계되었습니다. 하지만 이 ABC에 메서드가 전혀 없었기 때문에, 어떤 객체가 ByteString 의 인스턴스라는 사실이 객체에 대한 유용한 정보를 제공하지 못했습니다. 또한 memoryview 와 같은 다른 일반적인 버퍼 타입들도 런타임이나 정적 타입 검사에서 ByteString 의 하위 유형으로 인식되지 않았습니다.

자세한 내용은 PEP 688 를 참조하십시오.

버전 3.9부터 사용 지원 중단(deprecated), 버전 3.17에서 제거 예정.

class typing.Collection(Sized, Iterable[T_co], Container[T_co])¶: collections.abc.Collection 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.6.

버전 3.9부터 폐지됨: collections.abc.Collection 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Container(Generic[T_co])¶: collections.abc.Container 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Container 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.ItemsView(MappingView, AbstractSet[tuple[KT_co, VT_co]])¶: collections.abc.ItemsView 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.ItemsView 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.KeysView(MappingView, AbstractSet[KT_co])¶: collections.abc.KeysView 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.KeysView 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Mapping(Collection[KT], Generic[KT, VT_co])¶: collections.abc.Mapping 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Mapping 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.MappingView(Sized)¶: collections.abc.MappingView 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.MappingView 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.MutableMapping(Mapping[KT, VT])¶: collections.abc.MutableMapping 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.MutableMapping 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.MutableSequence(Sequence[T])¶: collections.abc.MutableSequence 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.MutableSequence 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.MutableSet(AbstractSet[T])¶: collections.abc.MutableSet 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.MutableSet 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Sequence(Reversible[T_co], Collection[T_co])¶: collections.abc.Sequence 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Sequence 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.ValuesView(MappingView, Collection[_VT_co])¶: collections.abc.ValuesView 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.ValuesView 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

`collections.abc` 내 비동기 ABC에 대한 에일리어스¶

class typing.Coroutine(Awaitable[ReturnType], Generic[YieldType, SendType, ReturnType])¶

collections.abc.Coroutine 에 대한 사용이 권장되지 않는 에일리어스입니다.

타입 어노테이션에서 collections.abc.Coroutine 및 typing.Coroutine 을 사용하는 방법에 대한 자세한 내용은 제너레이터 및 코루틴 어노테이션 를 참조하십시오.

Added in version 3.5.3.

버전 3.9부터 폐지됨: collections.abc.Coroutine 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.AsyncGenerator(AsyncIterator[YieldType], Generic[YieldType, SendType])¶

collections.abc.AsyncGenerator 에 대한 사용이 권장되지 않는 에일리어스입니다.

타입 어노테이션에서 collections.abc.AsyncGenerator 및 typing.AsyncGenerator 를 사용하는 방법에 대한 자세한 내용은 제너레이터 및 코루틴 어노테이션 를 참조하십시오.

Added in version 3.6.1.

버전 3.9부터 폐지됨: collections.abc.AsyncGenerator 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

버전 3.13에서 변경: SendType 매개변수에 이제 기본값이 설정되었습니다.

class typing.AsyncIterable(Generic[T_co])¶: collections.abc.AsyncIterable 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.5.2.

버전 3.9부터 폐지됨: collections.abc.AsyncIterable 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.AsyncIterator(AsyncIterable[T_co])¶: collections.abc.AsyncIterator 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.5.2.

버전 3.9부터 폐지됨: collections.abc.AsyncIterator 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Awaitable(Generic[T_co])¶: collections.abc.Awaitable 에 대한 사용이 권장되지 않는 에일리어스입니다.

Added in version 3.5.2.

버전 3.9부터 폐지됨: collections.abc.Awaitable 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

`collections.abc` 내 다른 ABC에 대한 에일리어스¶

class typing.Iterable(Generic[T_co])¶: collections.abc.Iterable 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Iterable 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Iterator(Iterable[T_co])¶: collections.abc.Iterator 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Iterator 가 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

typing.Callable¶

collections.abc.Callable 에 대한 사용이 권장되지 않는 에일리어스입니다.

타입 어노테이션에서 collections.abc.Callable 및 typing.Callable 를 사용하는 방법에 대한 자세한 내용은 콜러블 객체 어노테이션 를 참조하십시오.

버전 3.9부터 폐지됨: collections.abc.Callable 이(가) 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

버전 3.10에서 변경: Callable 이 이제 ParamSpec 과 Concatenate 를 지원합니다. 자세한 내용은 PEP 612 을 참조하십시오.

class typing.Generator(Iterator[YieldType], Generic[YieldType, SendType, ReturnType])¶

collections.abc.Generator 에 대한 사용이 권장되지 않는 에일리어스입니다.

타입 주석에서 collections.abc.Generator 및 typing.Generator 를 사용하는 방법에 대한 자세한 내용은 제너레이터 및 코루틴 어노테이션 을 참조하십시오.

버전 3.9부터 폐지됨: collections.abc.Generator 이(가) 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

버전 3.13에서 변경: send 및 return 타입에 대한 기본값이 추가되었습니다.

class typing.Hashable¶: collections.abc.Hashable 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.12부터 폐지됨: 대신 collections.abc.Hashable 을 직접 사용하십시오.

class typing.Reversible(Iterable[T_co])¶: collections.abc.Reversible 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.9부터 폐지됨: collections.abc.Reversible 이(가) 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

class typing.Sized¶: collections.abc.Sized 에 대한 사용이 권장되지 않는 에일리어스입니다.

버전 3.12부터 폐지됨: 대신 collections.abc.Sized 를 직접 사용하십시오.

`contextlib` ABC들에 대한 에일리어스¶

class typing.ContextManager(Generic[T_co, ExitT_co])¶

contextlib.AbstractContextManager 에 대한 사용이 권장되지 않는 에일리어스입니다.

첫 번째 타입 파라미터인 T_co 는 __enter__() 메서드가 반환하는 타입을 나타냅니다. 선택 사항인 두 번째 타입 파라미터 ExitT_co 는 기본값이 bool | None 이며, __exit__() 메서드가 반환하는 타입을 나타냅니다.

Added in version 3.5.4.

버전 3.9부터 폐지됨: contextlib.AbstractContextManager 이(가) 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

버전 3.13에서 변경: 선택 사항인 두 번째 타입 파라미터 ExitT_co 가 추가되었습니다.

class typing.AsyncContextManager(Generic[T_co, AExitT_co])¶

contextlib.AbstractAsyncContextManager 에 대한 사용이 권장되지 않는 에일리어스입니다.

첫 번째 타입 파라미터인 T_co 는 __aenter__() 메서드가 반환하는 타입을 나타냅니다. 선택 사항인 두 번째 타입 파라미터 AExitT_co 는 기본값이 bool | None 이며, __aexit__() 메서드가 반환하는 타입을 나타냅니다.

Added in version 3.6.2.

버전 3.9부터 폐지됨: contextlib.AbstractAsyncContextManager 이(가) 이제 서브스크립팅([])을 지원합니다. 자세한 내용은 PEP 585 및 제네릭 에일리어스 형 를 참조하십시오.

버전 3.13에서 변경: 선택 사항인 두 번째 타입 파라미터 AExitT_co 가 추가되었습니다.

주요 기능의 폐지 일정¶

typing 의 일부 기능은 폐지되었으며 향후 파이썬 버전에서 제거될 수 있습니다. 다음 표는 편의를 위해 주요 폐지 사항을 요약한 것입니다. 이 내용은 변경될 수 있으며 모든 폐지 사항이 나열된 것은 아닙니다.

기능	사용 지원 중단 버전	예정된 제거	PEP/이슈
표준 컬렉션의 `typing` 버전	3.9	미정(자세한 내용은 폐지된 에일리어스 참조)	PEP 585
`typing.ByteString`	3.9	3.17	gh-91896
`typing.Text`	3.11	미정	gh-92332
`typing.Hashable` 및 `typing.Sized`	3.12	미정	gh-94309
`typing.TypeAlias`	3.12	미정	PEP 695
`typing.AnyStr`	3.13	3.18	gh-105578

typing — 형 힌트 지원¶

파이썬 형 시스템 사양¶

형 에일리어스¶

NewType¶

콜러블 객체 어노테이션¶

제네릭¶

튜플 어노테이션¶

클래스 객체의 형¶

제너레이터 및 코루틴 어노테이션¶

사용자 정의 제네릭 형¶

Any 형¶

명목적 대 구조적 서브 타이핑¶

모듈 내용¶

특수 타이핑 프리미티브¶

특수형¶

특수 형태¶

제네릭 형 및 형 별칭 구축¶

기타 특수 지시자¶

프로토콜¶

I/O 작업을 위한 ABC 및 Protocol¶

함수와 데코레이터¶

인트로스펙션 도우미¶

상수¶

폐지된 에일리어스¶

내장형에 대한 에일리어스¶

collections 내 타입들의 에일리어스¶

기타 구체적인 타입에 대한 에일리어스¶

collections.abc 내 컨테이너 ABC에 대한 에일리어스¶

collections.abc 내 비동기 ABC에 대한 에일리어스¶

collections.abc 내 다른 ABC에 대한 에일리어스¶

contextlib ABC들에 대한 에일리어스¶

주요 기능의 폐지 일정¶

분실물 보관소

`typing` — 형 힌트 지원¶

`Any` 형¶

`collections` 내 타입들의 에일리어스¶

`collections.abc` 내 컨테이너 ABC에 대한 에일리어스¶

`collections.abc` 내 비동기 ABC에 대한 에일리어스¶

`collections.abc` 내 다른 ABC에 대한 에일리어스¶

`contextlib` ABC들에 대한 에일리어스¶