feat!: AudioQueryのJSON表現をENGINEと同じにする

[qryxip]

内容

#261 が行われた理由は次の2点である。

1. jsonフィールドのcaseを揃えたほうが良いのではないか voicevox_engine#460 もやろうとしていた
2. （少なくとも正攻法では）pydantic.dataclassesの対応ができない (PyO3を使ってクレートからwhlを作る #239 (comment))

1.は中止、2.もこの度 ダーティハックであるがなんとかする方法を発見したため、 pydantic.TypeAdapterを利用および推奨すればよいことがわかったため、 #261 の取り消しを行う。これでENGINEとCOREでAudioQueryを使い回せるようになる。

BREAKING-CHANGE: AudioQueryのJSON表現がENGINEと同じになる。
See-also: https://docs.python.org/3.13/library/dataclasses.html#dataclasses.Field
See-also: https://docs.pydantic.dev/2.10/api/type_adapter/

関連 Issue

その他

[qryxip]

Alias - Pydantic

なんか幸いなことに、特に設定しない場合の挙動はエイリアスというよりはリネームっぽい。snake_caseなやつを受け付けなくなった。
(ただしこれはdataclassとしてのフィールド名には影響しないので、そっちの対処はこの下の__post_init__で行う。)

[qryxip]

よく考えてみれば別にそんなにハックじゃないような気がしてきた。問題はdataclasses.Field.nameを外から書き換えていいのかといったところか。駄目とは書かれていない。

[qryxip]

多分こういう書き方もあるが、どっちが良いかどうか正直わからない。

Suggested change

	if true_name := self.__attr_true_names.get(name):
	return getattr(self, true_name)
	# 普通の`AttributeError`と同じ文面
	raise AttributeError(f"{type(self).__name__!r} has no attribute {name!r}")
	try:
	true_name = self.__attr_true_names[name]
	except KeyError:
	# 普通の`AttributeError`と同じ文面
	raise AttributeError(f"{type(self).__name__!r} has no attribute {name!r}")
	return getattr(self, true_name)

[qryxip]

この二つをSphinxがそのまま出すため、docstringをちゃんと書いたという流れ。なのでこれらはユーザー向けの説明である。

[Hiroshiba]

すみません、確認です！

AudioQuery jsonとコード内でのデータ形式どちらともキャメルケースとスネークケースが入り混じる形になるようになった、という感じでしょうか？（違いそう）

そもそもエンジンと同じにすべきなのかを少し迷っています。同じにした方が良い気もしつつ、スネークケース統一だった方が良い気もしつつ………難しいですね。。。

[qryxip]

あ、コード内はsnake_caseのまま、JSON表現だけをENGINEと同じにしています。

よく考えたらPRのタイトルはよくありませんね。変えておきます。

[Hiroshiba]

なるほどです！！

あとはこの点かなぁ

そもそもエンジンと同じにすべきなのかを少し迷っています。同じにした方が良い気もしつつ、スネークケース統一だった方が良い気もしつつ………難しいですね。。。

うーーーーーん。
少なくともエンジン側のAPIの互換性は、データ構造置き換えれば良いだけなので考慮しなくても良さそう。

エンジンとAudioQueryのデータ構造を合わせるべきか、ということだよなぁ。
合わせるとどんな感じで良さそうでしょうか？👀
（合わせたくないのではなく、合わせた方が良いのかどっちかわからないという視点です）

[qryxip]

#943 (comment)でも書いたのですが、ENGINEとCOREを両方使うケースはあるかなと思ってます。両者を比較検討しているときとか。またユーザーが見るのがドキュメントではなくZennやChatGPTに寄るということも起こりうることを考えると、「ENGINEを使う知識」と「COREを使う知識」の違いは、可能な範囲において小さくした方がよいのではないかと思った次第です。

[Hiroshiba]

ENGINEとCOREを両方使うケースはあるかなと思ってます

個人的にはこれはかなりレアケースかなと思ってます！
自分の目的に合う段階で片方になることがとても多いのと、あとそれに比べて圧倒的に片方だけ利用する人が多いかなと。

ユーザーが見るのがドキュメントではなくZennやChatGPTに寄るということも起こりうること

こちらは同感です！

となると、シリアライズされるものというか、エンジンが出力するjsonが既存である場合は合わせる形が良さそう。
多分このプルリクエストはその形になっているので、良さそう！！

[Hiroshiba]

LGTM！！

２点だけコメントしてます！

[Hiroshiba]

JSON化（シリアライズ化）するためにdataclass.asdictを使っていますが、ここがユーザーに露出するとdataclass（のasdict）に依存したAPIになってしまうので、数年後に不便になるだろうなと感じました！

たぶん良いのはserializeメソッドを作るか、あるいはserialize関数を別で実装するかだろうなと思いました。
たぶんjsonという文字列も出さない方が良さそう。（jsonをサポートしてるわけではなく、僕たちにとって都合のいいのがたまたまjsonだったというスタンス）

けどまあこうするとRust側のAPIと乖離してしまうし、ちょっと考えないといけないこと多いので大変な気もします。
とりあえず今はasdictで実装し、APIとしてはサポートせず（ドキュメントに書かず）、後回しにするとかもありだと思います！

[qryxip]

5f8e4aa (#946)

ちょっと調べたのですが、PydanticのdataclassからJSONを吐き出す経路としてはpydantic.TypeAdapter.dump_jsonがあることがわかりました。こっちの経路ではfieldsの書き換えは効果は発揮せず、必ず呼ぶたびにby_alias=Trueを付けなければなりません。dump_pythonやjson_schemaというのもありますが、これらも同様です。by_alias=Trueを付けないとsnake_caseのJSON Schemaをお出ししてきます。クラス自体について設定する項目は見つかりませんでした。

# snake_caseのまま吐き出されてしまう！（当然、JSON → dataclass → JSONと変換したら元のJSONから変化してしまう）
_ = TypeAdapter(AudioQuery).dump_json(query).decode()

# `by_alias`（デフォルトは`False`）を`True`にするとちゃんとcamelCaseで出る
_ = TypeAdapter(AudioQuery).dump_json(query, by_alias=True).decode()

これを受け、最早asdictのサポートはしなくていいなと思ったため、関連のハックを取り消した上でTypeAdapterを使う方法に切り替えてドキュメントの注意書きも書きました。お手数をおかけするのですが、もう一度レビューをお願いできればと…

[Hiroshiba]

LGTM！！

ちなみに目標とする0.16リリースの機能の中にシリアライズは含まれていないので、本線進めた方が良いのではとかちょっと思いました･･･！！

あとこれはただの共有ですが、今のバージョンでシリアライズしたものが読み込めることを今後ずっと確認するテストもあると嬉しいかもですね！
まあデータ構造は変わったタイミングで良いはず･･･！

[qryxip]

とりあえずapprove頂いてたのでマージ！