Getting Started

インストール

PyPIからpyserdeをインストールしてください。pyserdeにはPython>=3.9が必要です。

pip install pyserde

poetryを使用している場合は、以下のコマンドを実行してください。

poetry add pyserde

JSONとPickle以外のデータ形式を扱う場合は、追加の依存関係をインストールする必要があります。
適切なデータ形式で動作するには、msgpack、toml、yaml の追加パッケージをインストールしてください。
使用しない場合はスキップして構いません。
例えば、TomlとYAMLを使用する場合は以下のようにします。

pip install "pyserde[toml,yaml]"

poetryを使用している場合

poetry add pyserde -E toml -E yaml

一度にすべてをインストールする場合

pip install "pyserde[all]"

poetryを使用している場合

poetry add pyserde -E all

利用可能な追加パッケージ

• all：msgpack、toml、yaml、numpy、orjson、sqlalchemy をインストール
• msgpack：msgpack をインストール
• toml：tomli と tomli-w をインストール
  • 注記：python 3.11以降は tomllib を使用
• yaml：pyyaml をインストール
• numpy：numpy をインストール
• orjson：orjson をインストール
• sqlalchemy：sqlalchemy をインストール

最初のpyserdeクラスを定義

pyserdeの@serdeデコレータを使用してクラスを定義します。
モジュール名が pyserde ではなく serde であることに注意してください。
pyserdeは標準ライブラリのdataclassesモジュールに大きく依存しています。
そのため、dataclassに慣れていない場合はまずdataclassesのドキュメントを読むことをおすすめします。

from serde import serde

@serde
class Foo:
    i: int
    s: str
    f: float
    b: bool

クラスがPythonインタプリタにロードされると、pyserdeは@serdeによって（デ）シリアライズに必要なメソッドを生成します。
コード生成は一度だけ行われ、クラスを使用する際にオーバーヘッドはありません。
これにより、クラスはpyserdeがサポートするすべてのデータ形式でシリアライズおよびデシリアライズ可能になります。

注記： シリアライズまたはデシリアライズの機能のみが必要な場合、@serdeデコレータの代わりに@serializeや@deserializeを使用できます。

例：シリアライズのみを行う場合、@serializeデコレータを使用できます。しかし、FooのデシリアライズAPI（例：from_json）を呼び出すとエラーが発生します。

from serde import serialize

@serialize
class Foo:
    i: int
    s: str
    f: float
    b: bool

PEP585とPEP604

python>=3.9用のPEP585スタイルのアノテーションと、python>=3.10用のPEP604 Unionオペレータがサポートされています。
PEP585とPEP604を使用すると、pyserdeクラスをきれいに書くことができます。

@serde
class Foo:
    a: int
    b: list[str]
    c: tuple[int, float, str, bool]
    d: dict[str, list[tuple[str, int]]]
    e: str | None

pyserdeクラスの使用

次に、pyserdeの（デ）シリアライズAPIをインポートします。
JSONの場合は以下のようにします。

from serde.json import from_json, to_json

to_jsonを使用してオブジェクトをJSONにシリアライズします。

f = Foo(i=10, s='foo', f=100.0, b=True)
print(to_json(f))

from_jsonにFooクラスとJSON文字列を渡して、JSONをオブジェクトにデシリアライズします。

s = '{"i": 10, "s": "foo", "f": 100.0, "b": true}'
print(from_json(Foo, s))

以上です！
pyserdeには他にも多くの機能があります。興味があれば、残りのドキュメントをお読みください。

💡 ヒント：どのタイプチェッカーを使用すべきか？
pyserdeはPEP681 dataclass_transformに依存しています。
2024年1月現在、mypyはdataclass_transformを完全にはサポートしていません。
私の個人的なおすすめはpyrightです。