信じられるのはsetuptoolsだけ ― Stub-only packageを初めて作った話

結論

Stub-only packageを作るときはsetuptoolsを使いましょう。

Stub packageとは？

Stub package は PEP-561で定義されるパッケージの形態です。
主にThird partyのライブラリに対してType hintを与えることを目的としたPEPです。

Type hintがあればVS Codeなどエディタから引数リストやメンバ変数の補完などの支援が得られる他、mypyやpyrightによる静的型チェックの支援を受けることができます。
一方で、歴史的な理由やC++，Cythonを利用しているパッケージでは型ヒントが付けられていない場合があります。
自分が管理するライブラリであれば色々な手段 ¹² で型ヒントを付与すれば非常に便利です。

しかしながら、先述の通りThird partyのライブラリの場合、ライブラリのコードを変更せずに型ヒントを付ける必要があります。
Pythonにはそのための方法が定義されており、それが PEP-561であり、Stub packageになります。

今回作ったもの

まだテストコードを書けていませんが、実用上問題無いため実用優先でとりあえず公開することにしました。³

tensorstoreというN次元配列保存に適したライブラリです。
そのうち、これはこれで記事にしたいと考えていますが、細かい話は一旦おいておきましょう。

tensorstoreは非常に高速かつメモリ効率に優れたライブラリです。
一方で、ほとんどのコードがC++で記述されており、ほとんど全ての関数・クラスメンバなどのType hintは記述されていません。
実際に使おうとすると、苦行か何かと思い、本ライブラリを作るに至りました。

本ライブラリはいわゆるStub-only packageと呼ばれるライブラリです。
PEP484で定義されるpyiファイルのみで構成されるパッケージをStub-only packageと呼びます。
ちなみに、pyファイルとpyiファイルから構成されるパッケージは Partial Stub Packageと言います。

細かい構文については、別の機会に記述しますが、基本的には実装がない関数やクラス、変数を定義していくだけです。
Protocolを使ったクラス実装と同一と言えば分かりやすい人も居るのかもしれません。

ようやく本題

上記のライブラリを作ったは良いが、問題は配布にありました。
最初はじわじわとシェアを伸ばしているryeでプロジェクトを管理していました。
何となくで始めていたのですが、パッケージのbuildをしようとするとエラーになってしまい解決できず。
issueを探すとそれらしいものは見つからず。

なんでやねんと思いつつもあだ若いツールなので仕方がない。
気を取り直してpoetryでプロジェクトを作り直し、ビルドするも同じく撃沈。

流石に面倒くさくなり、setuptoolsで作り直した次第でした。
setuptoolsでパッケージを作ることは苦行としか言いようが無いのですが、Stub-only packageの場合、通常依存パッケージが無いのであまり気にせずにsetuptoolsで作りきりました。

あとから気づいたのでが、意外とpoetryがのpyproject.tomlは癖があるようで、rye→setuptoolsの差分は少ないのですが、poetry→setuptoolsはバチバチにエラーが出て修正が大変でした。
何らか方針の違いがあるのでしょうか。

参考

1. インターネットで見つけた良い例 ↩

2. 私が書いた一例 ↩

3. そもそもStub packageのTestコードの書き方が分からない・・・pandas-stubのTestとかを参考中 ↩