JSON を受け取る API などでは、多くの場合で何らかのバリデーションをしていると思うが、そのバリデーションに Python の TypedDict を使えるようにしてみました。

概要

TypedDict を使って辞書型のデータをバリデーションするユーティリティ。辞書が必要なキーを持っているかや、値が適切な型を持っているかを再帰的にチェックします。 API リクエストや何らかのファイルのような、 JSON や YAML をデシリアライズするシーンで便利です。

現在のところ、一般的な型および Optional を含む Union 型をサポートしています。

要件

Python 3.10 以降

インストール

PyPI からインストールできます。
https://pypi.org/project/typeddict-validator/

pip install typeddict-validator

つかいかた

validate_typeddict が本体です。辞書型のデータと TypedDict の型 (T) を渡します。返り値は TypeGuard[T] なので、辞書が入力された TypedDict の型のオブジェクトであることが保証されます。

>>> from typing import TypedDict
>>> from typeddict_validator import validate_typeddict
>>>
>>> PersonDict = TypedDict("PersonDict", {"name": str, "age": int, "interests": list[str]})
>>>
>>> person = {"name": "Taro Yamada", "age": 30, "interests": ["programming", "painting"]}
>>>
>>> if validate_typeddict(person, PersonDict):
...     print("It's a PersonDict!")

It's a PersonDict!

デフォルトでは、一致しない場合にエラーを投げます。

>>> robot = {"name": "Doraemon"}
>>>
>>> if validate_typeddict(robot, PersonDict):
...     print("It's a PersonDict!")

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/app/typeddict_validator/validate.py", line 37, in validate_typeddict
    raise DictMissingKeyException(key=k)
typeddict_validator.validate.DictMissingKeyException

silent=True オプションを使って黙らせることもできます。この場合、エラーではなく False を返します（ただし第2引数が TypedDict でない時は ValueError を返す）。

>>> if not validate_typeddict(robot, PersonDict, silent=True):
...     print("It's not a PersonDict!!")

It's not a PersonDict!!

ほかのサンプルを見るには validate/validate_test.py をご参照ください。

さいごに

基本的な用途においては十分かと思いますが、まだまだサポートできていない機能やエンハンスの余地は多いと思います。気になった方はぜひ使ってみて、不便なところがありましたら Pull Request などをしていただけますと大変喜びます。

それではよい Python ライフを～。