はじめの一歩

TwelStuff という新しいプロジェクトを作成してみましょう。

1. プロジェクトのレイアウト

最小のPythonプロジェクトは2つのファイルで構成されます。1つは setup.py ファイルで、このファイルにはプロジェクトのメタデータを記述します。もう一つのファイルには、プロジェクトで提供したい機能をPythonコードで実装します。

このサンプルプロジェクトでは、典型的なプロジェクトを想定した上で最も小さいレイアウトを提供するために、前述の2ファイル構成よりももう少しファイルを追加します。ちゃんとしたPythonパッケージを作成するために、 towelstuff/ ディレクトリに __init__.py ファイルを置いて下さい。プロジェクトのソースコードが1つのファイルから複数のファイルに成長することを見越して、このようにしています。

同様に、 README.txt ファイルにプロジェクトの概要を記述し、 LICENSE.txt ファイルにプロジェクトのライセンス条項を記載しておきましょう。

これで始める準備が整いました。大抵のプロジェクトでは他の種類のファイルもいくつか扱うでしょうから、これについてのは Arranging your file and directory structure を参考にして下さい。

ここまででプロジェクトのレイアウトは以下のようになっているでしょう:

TowelStuff/
    LICENSE.txt
    README.txt
    setup.py
    towelstuff/
        __init__.py

2. プロジェクトの概要記述

setup.py ファイルはPythonプロジェクトの心臓部です。このファイルにはプロジェクトの全てのメタデータが記載されます。ここには多岐にわたるメタデータの種類からいくつかを選んで記載することが出来ます。まず必要になるフィールドは name, version, packages です。 name フィールドは、パッケージを公開するつもりならPython Package Index (PyPI)で公開されている他のパッケージ名と衝突しないものにするべきです。 version フィールドはプロジェクトのリリース物を見分けるために必要です。 packages フィールドには、このプロジェクトに含まれるソースコードの場所を記載します。

最初の setup.py にはライセンス情報と、 README.txt ファイルを再利用して long_description フィールドを設定しましょう。以下のように書きます:

from distutils.core import setup

setup(
    name='TowelStuff',
    version='0.1dev',
    packages=['towelstuff',],
    license='Creative Commons Attribution-Noncommercial-Share Alike license',
    long_description=open('README.txt').read(),
)

3. 最初のリリースを作る

version フィールドを 0.1dev としてください。これは、 0.1 に向けた 開発版 である、ということを表しています。実際の所、このプロジェクトにはまだコードがありません。このプロジェクトを価値あるものにするだけのコードを書いたら、versionフィールドから dev を取り除いて 0.1 にしましょう。

リリースを作成するために、ソースコードを1つのアーカイブファイルにまとめる必要があります。これは以下のように sdist コマンドで出来ます:

$ python setup.py sdist

これで、プロジェクトの dist サブディレクトリが作られ、プロジェクトのソースコードが配布用のアーカイブファイルにまとめて圧縮されます。ファイル名は次のようになります:

TowelStuff-0.1.tar.gz

圧縮されたアーカイブファイルのフォーマットは、POSIXではデフォルトで .tar.gz になり、Windowsでは .zip になります。

標準設定のままではDistutilsはプロジェクトディレクトリ以下の全てのファイルを含めてはくれません。同梱されるファイルはデフォルトでは以下の通りです:

もし追加したいファイルがあれば、いくつかの方法でそれらのファイルを指定することが出来ます:

• 拡張パッケージを使ってDistutilsの機能を拡張する方法。SetuptoolsとDistributeはバージョン管理システムと連携して含めるべきファイルを検出します。
• 最上位に MANIFEST.in ファイルを作成する方法。このテンプレートファイルにはどのファイルを含めるかのファイル名やパターンを記載します。 (TO-DO: link to a MANIFEST.in document)

sdist コマンドを実行すると、パッケージに含めるべき全てのファイル名が含まれたMANIFESTファイルが生成されます。このファイルを確認して、配布パッケージに含まれるファイルが正しく列挙出来ているかどうかをダブルチェックすることができます。これでプロジェクトをリリースする準備が整いました。リリースする前に以下の項目についてダブルチェックすることをお勧めします:

• 正しいバージョン番号.

  dev マーカーをバージョン番号に手動で付けることで、リリース版と開発版を明確に分けル事が出来きますが、 dev の付いたバージョンをリリース版として公開は したくない はず。

• 必要な全てのファイルが含まれているか.

  MANIFESTファイルを見て、あるいは sdist コマンドで生成されたアーカイブファイルを見て確認しましょう。

4. パッケージをPython Package Index (PyPI) に登録

sdist で生成された配布ファイルはどこででも公開することが出来ます。Pythonには多くのPythonプロジェクトを公開している中央インデックス The Python Package Index (PyPI) がpytohn.org以下にあります。リリースした配布物を公開するのにここを使うことが出来ます。

まず最初にこのサイトを訪れて、プロジェクトをPyPIで公開するためのアカウントを登録しましょう。公開するプロジェクトは以下のようなURLになります:

http://pypi.python.org/pypi/<projectname>

プロジェクト名は既にPyPIに登録されているものでなければ好きな名前にすることができます。プロジェクトを登録するには以下のコマンドを実行します:

$ python setup.py register

5. リリース物をアップロードして、タオルを掴んで宇宙を救ってください！ [1]

おめでとう！これで問題無くソース配布物も完成して、PyPIに成果物をアップロードする時がきました。ここで bdist_wininst コマンドでWindowsインストーラ形式の配布ファイルを作成することもできます。このように、Pythonの配布物としていくつかの異なるファイルフォーマットを作成することが出来ます。アップロードしたいフォーマットをアップロードコマンドと一緒に指定する必要があります。そうしないと事前に配布物を生成していてもアップロードはされません。ソース配布物は常にアップロードしておいた方が良いでしょう。他のフォーマットは好きに選ぶことが出来ますが利用者が望んでいるものを用意しましょう:

$ python setup.py sdist bdist_wininst upload

そしてリリースしたらパッケージリリースをコミュニティーに報告しましょう！

最後に、 setup.py の version フィールドを次のリリースに向けて新しい値に進めておきましょう (例えば 0.2dev)。

この はじめの一歩 は簡潔で良い導入ですが、多くの、ひっかかりやすいケースについては触れていません。より詳細な情報については Introduction to Packaging を参照してください。より理解を深めるには Current State of Packaging を参照して下さい。

[1]	訳注: 参考 銀河ヒッチハイク・ガイド - Wikipedia