2016年2月11日木曜日

Python パッケージの作成と PyPI への登録について

Python のパッケージを作成しPyPI へ登録しようとする際に参考にすべき公式ドキュメントは、"Python Packaging User Guide" である。
直接にはその中の "Packaging and Distributing Projects" のページが、プロジェクトのパッケージングと PyPI への登録方法について解説している。

このドキュメントにたどり着くには、Python 公式ドキュメントのトップページから「Python プロジェクトの配布」をクリックし、表示されたページの中の「ガイドを読む」の見出しの下にある3つのリンクをどれでもいいのでクリックすると、このドキュメントに移動する。

また、パッケージの作成についてのさらにくわしい説明は Setuptools のドキュメントの中にあるが、記述の古い箇所があるので、このドキュメントとくい違う記述があった場合はこのドキュメントの記述を優先するように、と Packaging and Distributing Projects のページの冒頭にある。

以下は2016年2月時点での Packaging and Distributing Projects のページの内容を簡単にまとめたもの。詳細と最新の情報は原文を確認する。


1、ツールの確認とインストール


以下の必要なツールがインストールされているかどうかを確認し、なければインストールする。

  • setuptools
  • wheel
  • twine

pip install setuptools wheel twine


2、パッケージに必要なファイルの作成


パッケージに必要なファイルを作成する。


いずれも PyPA sample project にサンプルがある。

setup.py

setup.py 内では setup() 関数を実行する。その際、引数にプロジェクトのメタデータを渡して実行する。 指定すべき引数は以下の通り。

  • name: プロジェクトの名前。PyPIにはこの名前で登録される。
  • version: プロジェクトの現在のバージョン。バージョン番号の振り方については Choosing a versioning scheme も参照する。
  • description: プロジェクトの1行説明。長い説明もつけたい場合はlong_descriptionに記載。
  • url: プロジェクトのホームページの url。
  • author: プロジェクトの作者の名前とメールアドレス。
  • license: ライセンス。
  • classifiers: プロジェクトのカテゴリー。複数指定可。カテゴリーの全リストは https://pypi.python.org/pypi?%3Aaction=list_classifiers を参照。
  • keywords: プロジェクトを説明するキーワード。複数指定可。
  • packages: プロジェクトに含まれるべきパッケージ。ひとつひとつ列挙することもできるが、setuptools.find_packages で自動で見つけさせることもできる(インストールさせたくないパッケージがあるときは exclude キーワード引数を使う)。
  • install_requires: プロジェクトに最低限必要な依存ライブラリ。
  • package_data: パッケージ内に追加でインストールするファイル。
  • data_files: パッケージ外にインストールするファイル。
  • entry_points: プロジェクトに付属して配布するプラグイン。よく使われるのは console_scripts。 パッケージのインストールと同時にスクリプトを作成・インストールさせることができる。

setup.cfg

setup.py コマンドで常に有効にしたいオプション値があればここに記載しておく。universal フラグなど。

README.rst

readme ファイル。reStructuredText フォーマットは必須ではない。

MANIFEST.in

パッケージ作成コマンド(後述)によって自動的にパッケージに含まれないファイルをパッケージに含めたいときにこのファイルで指定。どのファイルが自動的にパッケージに含まれるかは Specifying the files to distribute を、MANIFEST.in ファイルの記載の仕方は The MANIFEST.in template を参照。

パッケージ本体

プロジェクトと同じか、ごく近い名前のフォルダの中に、モジュールもしくはパッケージを配置するのが必須ではないが広く行なわれている方法。

3、配布用のファイルの作成


配布用のファイル(ディストリビューションという。パッケージとも)を作成する。配布用のファイルには以下の4種類がある。
ソースディストリビューションは必ず作成。Wheel ファイルも作成しておくとユーザ側でビルドが不要。


Source Distribution

python setup.py sdist

Universal Wheel

Python 2 と 3 両対応のパッケージにするとき。setup.cfg で universal フラグを常に有効にしておくこともできる。
python setup.py bdist_wheel --universal

Pure Python Wheel

Python 2 用と 3 用と別々にファイルを用意したいとき。Python2 と Python3 でそれぞれ実行。
python setup.py bdist_wheel

Platform Wheel

特定のプラットフォーム用にコンパイルされた C 拡張モジュールなどをパッケージに含めたいとき。
python setup.py bdist_wheel


4、PyPI へのアップロード


PyPI にアカウントを作成し、プロジェクト情報を登録し、ファイルをアップロードする。

  1. Create an account
  2. Register your project
  3. Upload your distributions

1. Create an account

PyPI のアカウントを作っていなければ作成する。PyPI のサイトでフォームから作成するのが推奨。またその場合、~/.pypirc ファイルを自分で作成する。
[distutils]
index-servers=pypi

[pypi]
repository = https://pypi.python.org/pypi
username = <username>
password = <password>

2. Register your project

最初のリリース時にはプロジェクトの登録が必要。
PyPI にログインしてフォームから PKG-INFO ファイルをアップロードするか、twine コマンドを使う。twine コマンドを使う場合は ~/.pypirc ファイルが必要。
twine register dist/*

3. Upload your distributions

twineを使う方法が推奨。
twine upload dist/*

なお、テスト専用サイトテストアップロードすることも可能。


5、PyPI での確認


PyPIのサイト上で確認し、必要ならファイルに修正を施し、再度パッケージングをして、アップロードする。


6、アップデート


パッケージがバージョンアップされた際には、setup.py のメタデータ他必要な修正を行い、再パッケージングと再アップロードを行なう。
プロジェクトのページには最新のアップロードしたバージョンしか表示されない。これはプロジェクトの開発者用ページで変更することができる。

56Packaging and Distributing Projects のページにはないが、追加で記載した。)

その他


開発時に開発モードでパッケージをローカルにインストールする方法の説明が、ドキュメント中にある。プロジェクトのルートディレクトリに移動して、以下を実行する(e の後にカレントディレクトリを意味するピリオドがあることに注意)。
pip install -e .

また、Additional Topics には Python パッケージに関わる種々の参考になるトピックが集められている。