콘텐츠로 이동

타입 어댑터

데이터의 유효성을 검사하려는 BaseModel 이 아닌 유형이 있을 수 있습니다. 또는 List[SomeModel] 의 유효성을 검사하거나 JSON에 덤프할 수도 있습니다.

??? api "API 문서" pydantic.type_adapter.TypeAdapter

이와 같은 사용 사례를 위해 Pydantic은 BaseModel을 생성할 필요 없이 유형 유효성 검사, 직렬화 및 JSON 스키마 생성에 사용할 수 있는 TypeAdapter를 제공합니다.

TypeAdapter 인스턴스는 해당 메서드가 없는 유형(예: 데이터 클래스, 기본 유형 등)에 대해 BaseModel 인스턴스 메서드의 일부 기능을 노출합니다.

from typing import List

from typing_extensions import TypedDict

from pydantic import TypeAdapter, ValidationError


class User(TypedDict):
    name: str
    id: int


user_list_adapter = TypeAdapter(List[User])
user_list = user_list_adapter.validate_python([{'name': 'Fred', 'id': '3'}])
print(repr(user_list))
#> [{'name': 'Fred', 'id': 3}]

try:
    user_list_adapter.validate_python(
        [{'name': 'Fred', 'id': 'wrong', 'other': 'no'}]
    )
except ValidationError as e:
    print(e)
    """
    1 validation error for list[typed-dict]
    0.id
      Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='wrong', input_type=str]
    """

print(repr(user_list_adapter.dump_json(user_list)))
#> b'[{"name":"Fred","id":3}]'

!!! info " dump_json bytes 반환합니다 " TypeAdapter 의 dump_json 메서드는 str 을 반환하는 BaseModel 의 해당 메서드인 model_dump_json 과 달리 bytes 객체를 반환합니다. 이러한 불일치가 발생하는 이유는 V1에서 모델 덤프가 str 유형을 반환했기 때문입니다. 따라서 이 동작은 이전 버전과의 호환성을 위해 V2에서도 유지됩니다. BaseModel 의 경우 bytes str 유형으로 강제 변환되지만 bytes 종종 원하는 끝 유형입니다. 따라서 V2의 새로운 TypeAdapter 클래스의 경우 반환 유형은 단순히 bytes 이며 원하는 경우 쉽게 str 유형으로 강제 변환될 수 있습니다.

!!! note RootModel과 사용 사례가 일부 겹치더라도, TypeAdapter는 BaseModel 등의 필드를 지정하기 위한 유형 주석으로 사용하면 안 됩니다.

데이터를 지정된 유형으로 구문 분석

TypeAdapter는 보다 임시적인 방식으로 Pydantic 모델을 채우기 위해 구문 분석 논리를 적용하는 데 사용할 수 있습니다. 이 함수는 BaseModel.model_validate와 유사하게 동작하지만 임의의 Pydantic 호환 유형에서 작동합니다.

이는 결과를 BaseModel의 직접적인 하위 클래스가 아닌 유형으로 구문 분석하려는 경우에 특히 유용합니다. 예를 들어:

from typing import List

from pydantic import BaseModel, TypeAdapter


class Item(BaseModel):
    id: int
    name: str


# `item_data` could come from an API call, eg., via something like:
# item_data = requests.get('https://my-api.com/items').json()
item_data = [{'id': 1, 'name': 'My Item'}]

items = TypeAdapter(List[Item]).validate_python(item_data)
print(items)
#> [Item(id=1, name='My Item')]

TypeAdapter는 Pydantic이 BaseModel의 필드로 처리할 수 있는 모든 유형으로 데이터를 구문 분석할 수 있습니다.

!!! info "성능 고려 사항" TypeAdapter 인스턴스를 생성할 때 제공된 유형을 분석하고 pydantic-core 스키마로 변환해야 합니다. 여기에는 약간의 오버헤드가 발생하므로 특정 유형에 대한 TypeAdapter 를 한 번만 생성하고 루프나 기타 성능에 중요한 코드에서 재사용하는 것이 좋습니다.

本文总阅读量次