Python プロジェクトをパッケージングする5つの Tips

この文書は Keynote SpeakerのTarek Ziadé氏が自身のブログ Fetchez le Python に書いたものを PyCon JP 運営チームが和訳したものです。

このブログエントリは、 PyCon JP にて氏が行う基調講演の内容に関連したパッケージングに関するもので、文中でも PyCon JP について触れていることから基調講演を聞く前に見ておくと良いかもしれません。

原文: 5 tips for packaging your Python projects

来週、私は PyCon JP で基調講演を行います。そこで講演する話題の1つは、当然 packaging に関するものです。具体的に言うと、昨今の Python プロジェクトをパッケージングするにあたって、参加者の方々へ私からどんなアドバイスができるだろうか？

これは難しい話題です。というのは、いまはその過渡期だからです。

とにかく、私はアドバイスのリストを書き出しました。またリリースしなかったツールに関する内容は削除しました。それは私の基調講演の別の話題になる予定です。

これがそのリストです。ここに書き出したほとんどの内容について異論の余地はありません。もし不足している内容や何かしらツッコミがあればコメントをください。

Tip #1 -- PEP 386 準拠のバージョン体系にする

パッケージ管理のエコシステムにおいて、複数のバージョン体系が混在しているのは、全く馬鹿げたことです。それは相互運用性を破綻させ、バージョンを適切に管理するツールを書くのが不可能になります。いまは PEP 386 に準拠することで、あなたのプロジェクトの将来が保証されます！

PyPI は既に PEP 386 に準拠しない Metadata 1.2 プロジェクトを受け付けないようになっています。これまで Metadata 1.2 対応のパッケージ作成ツールは一つもなかったため、この事実は一般にはあまり知られていません。今後、 Python 3.3 と distutils2 では PEP 386 準拠の Metadata 1.2 対応が標準となります。

"devdevdev123" や "3765-2011-test" といったバージョン表記とはお別れだね！

Tip #2 -- できるだけシンプル且つひとまとめに setup.py を作る

setup.py は、個々人のビルドシステムではありません。私はいくつかのプロジェクトでおかしなものを目の当たりにしました。setup.py はインストーラーから様々な作業のため利用されることに注意してください。例えば、そのプロジェクトのメタデータの項目を取り出すといったことです。

ここで単純なテストをしてみましょう。 " python setup.py --name " は、関数やメソッドを全く呼び出さず、さらに外部依存もなく、名前の項目を返すことを確認してください。

また setup.py は Python 3.3 と distutils2 では不要となり、代わりに setup.cfg に置き換えられるようになることを覚えておいてください。でも心配しないで。これまで通りの複雑な作業もできますからね。

私からのアドバイスとして、今後 setup() へ渡すパラメータは何もありません。ビルドする全てのものは別の場所に置いてあっても、もし setup.py から呼び出す必要があれば、そのときのみ呼び出されることになります。

Tip #3 -- インストーラーが利用することを前提としない

setup.py が普通の Python (== distutils) で実行できることを確認してください。もし setuptools や distribute を使っている場合でも、ほとんどの場合、両方のツールで動作するよう作成できます。必要なら、ユーザーに必要な追加操作を提示することもできます。

ユーザーの確認なしに別のインストーラーを強制的にインストールすることは（例えばsetup.py内部で ez_setup を呼び出すなど）、ユーザーに対してやや不親切です。これはそれ以降エンドユーザーに新しいインストーラーの利用を強制しています。もしあなたが setup.py の内部で同じようなことを行いたいなら、最初にユーザーへ問い合わせるようにしてください！

もしくは、シンプルにユーザーへ次のように伝えてください。「このプロジェクトは XXX インストーラーでのみ動作します。必要に応じてインストールするか中断してください。」

Tip #4 -- pypi へ不安定版 (unstable) をリリースしない

私たちのインストーラーはどれも -まだ- 十分にスマートな方法でPyPI上にあるプロジェクトの安定版リリースを認識して取得する事が出来ません。その理由は PyPI の作りにも関係しています。全てのプロジェクトは、ディレクトリ別に全てのリリースファイルをもっており、インストーラーが各リリースのどれが "最新" であるかを判断します。様々なインストーラの中で唯一、安定版かどうかをちゃんと判定しているのが zc.buildout です。

こういった理由により、アルファ版や RC 版を PyPI に置いた場合、そのパッケージの機能を更新する仕組みがある場合を除いて、PyPI からユーザー環境へインストールされてしまいます。あるいは、単純に PyPI は安定版リリースが置かれる場所だという前提になっています。そのため、ユーザーがパッケージを更新する方法について前提条件を設けないようにしてください。

ベータテスター向けには、明確に分けた別のインストール手順を提示してください。全てのインストーラーは、任意の URL やディレクトリからインストールする機能を備えています。

Tip #5 -- データファイルに気を付ける

Distutils や Distribute または Python そのものは、ドキュメントファイル、メディアファイル、設定ファイルといった、それぞれのファイルの違いを明示的に判別する方法をもっていません。こういったものは、全て データファイル です。さらに悪いことに、OS の違いによってそういったデータファイルの置かれる場所が違うために、パッケージングする人たちは、対象となる各システムで問題なくデータファイルが見つかるように、Python モジュールとしてデータファイルを扱おうとします。

そう、それはおかしな事です。私たちは、この問題を Python 3.3 で修正しました。しかし、この問題を解決できたとしても、最も移植性の高い方法として、データファイルを Python モジュールとして扱う人が多いでしょう。そこでできることは、データファイルとそういったファイルを読み込む関数またはモジュールの操作方法を分かりやすくドキュメントにまとめることです。それがあなたのプロジェクトをメンテナンスしてくれる、後を引き継ぐメンテナたちを助けることになります。