typing 고급 — Variance, ParamSpec, Self, overload

def add_dog(animals: list[Animal]) -> None:
    animals.append(Dog())

cats: list[Cat] = [Cat(), Cat()]
add_dog(cats)    # ✗ 만약 허용되면, cats 안에 Dog 가 들어감

def feed_animal(a: Animal): ...
def feed_cat(c: Cat): ...

# 'Animal 을 받는 함수' 위치에 'Cat 만 받는 함수' 를 넣을 수 있나?
fn: Callable[[Animal], None] = feed_cat   # ✗ — Dog 가 오면 깨짐

# 반대는?
fn2: Callable[[Cat], None] = feed_animal  # ✅ — Cat 도 Animal 의 일부니 OK

from typing import TypeVar

T_co = TypeVar("T_co", covariant=True)
T_contra = TypeVar("T_contra", contravariant=True)

class Producer(Generic[T_co]):
    def get(self) -> T_co: ...

class Consumer(Generic[T_contra]):
    def put(self, item: T_contra) -> None: ...

def log[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        ...
    return wrapper

from typing import Concatenate, Callable

def with_logger[**P, R](
    fn: Callable[Concatenate[Logger, P], R]
) -> Callable[P, R]:
    logger = make_logger()
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        return fn(logger, *args, **kwargs)
    return wrapper

@with_logger
def do_work(logger: Logger, x: int, y: int) -> int:
    logger.info(f"{x} + {y}")
    return x + y

do_work(2, 3)   # logger 는 자동 주입

from typing import Self

class Builder:
    def add(self, item: str) -> Self:
        ...
        return self

class SubBuilder(Builder):
    def special(self) -> Self:
        ...
        return self

b = SubBuilder().add("x").special()
# b 의 타입이 정확히 SubBuilder 로 추론됨

class Item:
    @classmethod
    def from_dict(cls, data: dict) -> Self:
        return cls(**data)

from typing import overload

@overload
def parse(value: str) -> str: ...
@overload
def parse(value: int) -> int: ...
@overload
def parse(value: list[str]) -> list[str]: ...

def parse(value):
    # 실제 구현 — overload 시그니처 아래
    return value

a = parse("hello")        # str
b = parse(42)              # int
c = parse(["a", "b"])      # list[str]

@overload
def get(key: Literal["count"]) -> int: ...
@overload
def get(key: Literal["name"]) -> str: ...
@overload
def get(key: str) -> object: ...

def get(key): ...

@overload
def get(self, key: K) -> V | None: ...
@overload
def get(self, key: K, default: V) -> V: ...
@overload
def get(self, key: K, default: T) -> V | T: ...

from typing import TypeGuard

def is_str_list(items: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in items)

def process(data: list[object]) -> None:
    if is_str_list(data):
        # 여기서 data 는 list[str] 로 좁혀짐
        print(", ".join(data))

from typing import TypeIs

def is_str(x: object) -> TypeIs[str]:
    return isinstance(x, str)

def handle(x: int | str) -> None:
    if is_str(x):
        print(len(x))     # str
    else:
        print(x + 1)      # int  ← 여기가 다름!

from typing import Annotated

UserId = Annotated[int, "UserID — DB 의 users.id"]
Email = Annotated[str, "이메일 형식"]

def find(id: UserId, email: Email): ...

from typing import Annotated
from fastapi import Depends, Query

def get_db(): ...

def search(
    q: Annotated[str, Query(min_length=3)],
    db: Annotated[Database, Depends(get_db)],
): ...

from typing import LiteralString

def execute(query: LiteralString) -> list[Row]:
    ...

execute("SELECT * FROM users WHERE id = 1")    # OK
execute(f"SELECT * FROM users WHERE id = {user_input}")  # ✗ — f-string 결과는 LiteralString 아님

from typing import NewType

UserId = NewType("UserId", int)
ProductId = NewType("ProductId", int)

def get_user(id: UserId): ...

uid = UserId(123)
pid = ProductId(456)

get_user(uid)    # OK
get_user(pid)    # ✗ — 다른 타입으로 취급
get_user(123)    # ✗ — int 그대로는 못 들어감

class Cache[K, V]:
    def __init__(self):
        self._data: dict[K, V] = {}

    def get(self, key: K) -> V | None: ...
    def put(self, key: K, value: V) -> None: ...

cache: Cache[str, int] = Cache()

class SortedList[T: (int, str)]:    # int 또는 str 만
    ...

class Container[T: Comparable]:     # Comparable 의 서브타입만
    ...

def stack[*Ts](*args: *Ts) -> tuple[*Ts]:
    return args

t = stack(1, "hello", 3.14)
# t 의 타입: tuple[int, str, float]

from typing import cast

raw: object = get_data()
data = cast(dict[str, int], raw)
# 런타임에는 그냥 raw, 타입 체커만 dict[str, int] 로 봄

from typing import assert_type

x = some_function()
assert_type(x, int)    # 체커가 x 를 int 로 추론하지 않으면 에러

from typing import assert_never

def handle(event: Literal["click", "key"]):
    if event == "click": ...
    elif event == "key": ...
    else:
        assert_never(event)    # 새 케이스가 생기면 여기가 깨짐