Protobuf-py: 妥協なきPython用Protobuf
Protobuf-py: Protobuf for Python, without compromises (buf.build)
要約
Bufは、Pythonのためにゼロから完全に書き直された新しいProtocol Buffersライブラリ「protobuf-py」を発表しました。このライブラリは、既存のPython Protobuf実装の欠点を克服し、完全な仕様カバレッジ、読みやすい生成コード、そして高いパフォーマンスを両立させています。Rustアクセラレータを併用することで、本番環境のワークロードにおいてGoogleのupb(Cエンジン)と同等の速度を実現します。
全文翻訳
protobuf-py: PythonのためのProtobuf、妥協なし
本日、私たちはprotobuf-pyを発表します。これは、完全にスクラッチで書かれたPython用のProtocol Buffersライブラリです。proto2、proto3、およびエディションすべてにおいて、Protobuf適合性スイートのバイナリおよびJSONの全ケースをパスし、拡張機能、カスタムオプション、未知のフィールド、動的メッセージ、およびよく知られた型をサポートします。読みやすく型付けされたPythonコードを生成し、ランタイム依存関係はなく、純粋なPython 3.10+で動作します。Rustアクセラレータをインストールすると、GoogleのPythonパッケージが依存しているCエンジンであるupbと同等の、本番ワークロード向けの速度が得られます。
Python開発者にとって、歴史的に完全なProtobuf実装か、Pythonらしいライブラリかの選択肢しかありませんでした。Googleのパッケージは完全ですが、C++やJavaに由来するAPIを持っています。betterprotoは使いやすいですが、仕様の多くを犠牲にしています。protobuf-pyは、Python開発者に両方を提供します。
なぜ別のProtobufランタイムを構築するのか?
PythonはProtobufにとって、後回しにされて良いほど重要でない言語ではありません。データパイプライン、MLシステム、AIエージェント、インフラスクリプト、RPCサービス、開発者ツールなどに使われています。それにもかかわらず、PythonでProtobufを使用する体験は、この人気の言語に期待されるものとは一致していません。Googleのパッケージは完全で実証済みですが、APIと生成コードは依然として他者のランタイムのバインディングのように感じられます。betterprotoはPython開発者がより良いものを求めていることを証明しましたが、仕様全体を実装することはありませんでした。grpcioは同じ問題をRPCにもたらしました。強力で広く使われていますが、その上に構築するのは困難です。
当初、私たちはconnect-py(ConnectとgRPCの両方を話すConnectRPCの実装)でRPCレイヤーを修正することを目指していました。しかし、トランスポートレイヤーだけでは不十分でした。優れたRPCスタックは、その下のメッセージに依存しており、Pythonには基盤となるProtobufランタイムがありませんでした。私たちは、実際のスキーマに対して十分な完全性、日常的なPythonでの使用に十分な読みやすさ、そして誰もが選択を後悔しないほどの速度を持つものを求めていました。
protobuf-pyは、これらの制約がすべて同時に満たされるかどうかを問うことから生まれました。Pythonのために構築された完全な実装であり、Googleのランタイムをラップしたり仕様を切り詰めたりすることなく、connect-pyが依存できる仕様カバレッジ、生成コード、およびパフォーマンスプロファイルを提供します。
Googleのパッケージがそのように感じる理由
PyPIからprotobufをインストールすると、通常得られるエンジンはCで書かれたupbです。あなたのメッセージはCのアリーナに存在し、Pythonオブジェクトはそのアリーナへのハンドルとなります。フィールドを読み取ることはCに渡り、値を検索し、戻る際にPythonオブジェクトを具体化します。
これは、複数の言語間でエンジンを共有する良い方法ですが、あらゆる場所にその痕跡を残します。
- 生成される
_pb2.pyファイルは、Pythonコードがあまりにも少なく、読みにくいです。クラスはインポート時にCエンジンを設定するために組み立てられるため、go-to-definitionはシリアライズされたディスクリプタバイトの壁に突き当たります。 SerializeToString、HasField、WhichOneof、CopyFromなどは、C++のエルゴノミクスに合わせて設計されたPython APIを構成します。HasFieldはproto3スカラーに対して呼び出すと例外が発生します。WhichOneofは、値を取得するためにgetattrに渡す文字列を返しますが、その値はすでに配置されています。- 生成されるインポートは絶対パスであり、パッケージ内にネストするとすぐに壊れます。PyPIには
fix-protobuf-importsという別のツールが存在し、Googleの出力を書き換えるためだけにあります。 - 型は1つのプロセス全体で共有されるプールに登録されるため、同じ
.protoファイルの2つのビルドをインポートすると、実行時にエラーが発生します。
これらのいずれも、バインディングにおけるランダムな欠陥ではありません。これらは、Python APIが主にC++/Javaのコードベースで一貫性を保つために設計された結果であり、慣用的なPythonパッケージとして設計されたわけではありません。不格好なAPIと速度はセットで提供され、長年、あなたはそれらを受け入れるか、あるいは全く使わないかのどちらかでした。
私たちが代わりに構築したもの
protobuf-pyは、メッセージをPython内に保持します。これは__slots__を持つプレーンなオブジェクトであり、そのフィールドは通常のPython値(int、string、list、submessage)です。Rustアクセラレータは、主にパースとシリアライズが必要な操作を高速化し、結果を直接オブジェクトに書き込みます。パースが完了すると、フィールドの読み取りはPython属性へのアクセスと同じになります。
データがPythonであるため、生成されるコードは実際のコードです。protoc-gen-pyは、あなたが読むことができるクラスを出力します。
class User(Message[_UserFields]):
__slots__ = ("first_name", "last_name", "active", "manager", "locations", "projects", "contact")
if TYPE_CHECKING:
def __init__(
self,
*,
first_name: str = "",
last_name: str = "",
active: bool = False,
manager: User | None = None,
locations: list[str] | None = None,
projects: dict[str, str] | None = None,
contact: Oneof[Literal["email"], str] | Oneof[Literal["phone"], str] | None = None,
) -> None: ...
first_name: str
last_name: str
active: bool
manager: User | None
locations: list[str]
projects: dict[str, str]
contact: Oneof[Literal["email"], str] | Oneof[Literal["phone"], str] | None
これの操作は、言語内の他のものと同様に行えます。
import copy
from gen.user_pb import User
from protobuf import Oneof
user = User(first_name="Alice", active=True, locations=["NYC", "LDN"])
user.last_name = "Smith"
wire = user.to_binary()
parsed = User.from_binary(wire)
match parsed.contact:
case Oneof(field="email", value=email):
send(email)
case Oneof(field="phone", value=phone):
call(phone)
inactive = copy.replace(parsed, active=False) # Python 3.13+以降
Oneofはパターンマッチング可能な値になり、型チェッカーは各ブランチを絞り込みます。Enumは実際のIntEnumメンバーです。pyright、mypy、tyは、スタブパッケージなしで生成された出力を読み取ります。生成されたファイルは相対インポートを使用し、どこに配置しても機能します。型は、グローバルプールではなく、明示的なRegistryを通じて解決されます。これらすべては、メッセージデータをPython内に保持することから来ています。
完全であり、フレンドリーなサブセットではない
他のProtobufライブラリはGoogleのものより使いやすいですが、通常は仕様の半分を切り捨ててそれを実現しています。betterprotoは現在最も使いやすい選択肢ですが、proto3のみをサポートし、proto2、エディション、拡張機能、カスタムオプションはありません。
protobuf-pyは仕様全体をカバーします。proto2、proto3、エディション、拡張機能、カスタムオプション、グループ、ラウンドトリップをまたいだ未知フィールドの保持、パックおよび展開された繰り返しフィールド、およびよく知られた型の完全なProtoJSONエンコーディングを扱います。Googleが自身のランタイムを認定するために使用する適合性スイートを、バイナリおよびJSONで一切の失敗なくパスします。リポジトリには失敗リストが空でチェックインされており、それが空でなくなるとCIは失敗します。
重要な部分で高速
メッセージをパースして破棄するだけのベンチマークでは、upbは作業を遅延させるため、無敵に見えます。本番コードはメッセージを一度パースし、フィールドで分岐し、いくつかの値を取り出し、メッセージをコピーし、変更されたバージョンを再シリアライズします。
upbは、これらの読み取りごとにPythonへの変換コストを支払います。protobuf-pyは、最初の読み取り後、パースがすでに通常のPythonオブジェクトを生成しているため、そのコストをゼロ回支払います。コストは境界の反対側にかかります。データをPython内に保持することは、protobuf-pyがより多くの作業を事前に行うことを意味します。これは、コードがメッセージに対して十分な作業を行い、時間を回収できる場合に効果を発揮します。
ここでは、両方のパッケージを、ソーシャルメディアサイトのユーザーのホームページ応答を構築する実際の例と、それらの独自の生のマーシャリング手順と比較します。数値はupbに対するスループット(操作/秒)であり、高いほど高速です。
| ワークロード | upb | protobuf-py |
|---|---|---|
| ホームページ応答の構築(エンドツーエンド) | 1.0x | 1.06x |
| └ パース(単独) | 1.0x | 0.22x |
| └ シリアライズ(単独) | 1.0x | 0.60x |
単独では、予想通りupbがマーシャリングで勝利します。エンドツーエンドでは、サービスが本番環境で実際に実行するコードでは、protobuf-pyが優位に立ちます。upbがPythonに翻訳し直す必要がある各フィールドの読み取りは、protobuf-pyがすでに持っているものであり、完全なリクエスト全体で、Cのものよりも高速なランタイムにつながります。
ここでのペイロードはテキスト中心(Redditの投稿本文全体、複数文のバイオ、通知)であり、ソーシャル、ドキュメント、LLM/エージェントトラフィックの現実的な形状です。これは、文字列をPythonオブジェクトとして保持することから最も利益が得られるケースです。ハーネスはtest_bench.pyで自分で実行できます。
Rustアクセラレータはオプションであり、自動です。protobuf-pyを使用するためにRustツールチェーンは必要ありませんし、コントリビューターも必要ありません。プリビルドされたホイールは、それが存在する場合にロードし、純粋なPythonパスはそれが存在しない場合に同じように動作します。これは無料スレッドの3.14ビルドで動作し、パッケージにはランタイム依存関係はありません。
私たちはこれを以前にもやったことがある
Bufは、チームがツールを中心にスクリプトを構築する原因となるProtobufの部分を修正するために長年を費やしてきました。Buf CLI、Buf Schema Registry、ConnectRPC、Protovalidate、そしてTypeScript用のprotobuf-esなどです。BufのエンジニアはProtobufエディションにも携わっており、protobuf-pyは仕様の執筆に関わった人々によって書かれています。それは同じ伝統に属しています。
試してみてください
# 既存のUVプロジェクトで
uv add protobuf-py
uv add --dev protoc-gen-py buf-bin
buf.gen.yamlを.protoファイルに向けます。
version: v2
inputs:
- directory: proto
plugins:
- local: protoc-gen-py
out: gen
そして生成します。
uv run buf generate
あなたは開いて読める型付けされた_pb.pyファイルを取得します。ドキュメントは公開されており、ソースとベンチマークハーネスはGitHubにあり、イシューは公開されています。どのように進んだか教えてください!