Python Packaging User Guide

注釈

日本語訳について:

Python Packaging User Guide (PyPUG) を勝手に訳したものです。

原文として commit 42c52e4 を参照しています。たぶん今後の更新には追随しません。

未訳部分があります(私が必要とするまで放置されます)。

翻訳の質はお察しなので必要なら原文を参照のこと。

Last Reviewed:2015-09-08

“Python Packaging User Guide” (PyPUG) は、現在あるツールを使って Python 配布物をパッケージ、公開、インストールする方法に関する正式なリソースを提供しようとするものだ。

Python パッケージングの開発状況を追うには、 Python Packaging Authority を見よ。

このガイドは github でメンテナンスされている。

推奨ツール

Page Status:Complete Last Reviewed:2016-06-24

Python パッケージングとインストールについてはよく知っていて、単に現在どのツールが推奨されているか知りたいだけなら、ここにその情報がある。

推奨インストールツール

• PyPI から Python パッケージ をインストールするには、 pip を使う。[1] [2] pip のインストール方法によっては、wheel キャッシュを利用するために wheel もインストールする必要があるかもしれない。[3]
• 共用の Python 環境からアプリケーション固有の依存関係を隔離するには、 virtualenv または venv を使う。[4]
• 完全に統合されたクロスプラットフォームなソフトウェアスタック管理システムが欲しければ、以下を検討せよ:
  • buildout: 主に Web 開発コミュニティ向け。
  • Spack, Hashdist, または conda: 主に科学コミュニティ向け。

推奨パッケージングツール

• プロジェクトを定義して Source Distributions を作るには、setuptools を使う。 [5] [6]
• Wheels を作るには、wheel project から利用できる setuptools 拡張 bdist_wheel を使う。プロジェクトがバイナリ拡張を含む場合、これは特に有用だ。[7]
• PyPI へ配布物をアップロードするには、 twine を使う。

---

[1]	場合によっては、 easy_install (setuptools に含まれる) を選ぶことになるかもしれない。例えば、(pip がサポートしない) Eggs からインストールする必要がある場合だ。詳しい解説は pip vs easy_install を見よ。

[2]	PEP 453 が accept されたので、Python 3.4 以降のほとんどの環境で pip がデフォルトで利用できる。pip が選ばれた理由については、PEP 453 の rationale セクション を見よ。

[3]	get-pip.py と virtualenv は wheel をインストールするが、ensurepip と venv は今のところそうではない。また、各種 Linux ディストリビューションでよく見られる “python-pip” パッケージは今のところ “python-wheel” に依存していない。

[4]	Python 3.4 以降、 venv は pip がインストールされた仮想環境を作るので、virtualenv と同等になる。ただし、バージョン間の一貫性が必要なユーザには virtualenv の使用を勧める。

[5]

distutils のみを使うことは多くのプロジェクトでは可能だが、これは他のプロジェクトへの依存関係の定義をサポートしておらず、また配布物のメタデータを自動で設定するために setuptools が提供するいくつかの便利なユーティリティを欠いている。 setuptools は標準ライブラリの外部にあるので、Python の異なるバージョン間でより一貫した仕様を提供できる。また、 (distutils と異なり) setuptools はサポートする全てのバージョンで今後の “Metadata 2.0” 標準フォーマットを生成するように更新される。 distutils を選択したプロジェクトであっても、pip がそのプロジェクトを(事前ビルドされた wheel ファイルからではなく)ソースから直接インストールする場合、実際には setuptools を使ってビルドされる。

[6]	distribute (setuptools のフォーク)は 2013 年 6 月に setuptools へマージされたので、setuptools がパッケージングのデフォルトの選択肢となった。

[7]	PyPI は今のところ Windows および Mac OS X 用の wheels のみを受理しており、またそれらは python.org で提供されるバイナリインストーラと互換であるべきとされる。wheel compatibility tagging scheme が改善されるまで、Linux 用 wheels は受理されない。

パッケージのインストール

Page Status:Complete Last Reviewed:2016-06-24

このセクションでは、Python パッケージ のインストール方法の基本を説明する。

重要な注意: この文脈で「パッケージ」とは、distribution (つまり、インストールされるひとかたまりのソフトウェア)の同義語であり、Python ソースコード内で import する package (モジュールコンテナ)を指すのではない。Python コミュニティでは、distribution を表すのに「パッケージ」の語を用いるのが普通だ。 “distribution” という用語はしばしば避けられる。というのは、Linux distribution だとか、あるいは Python 自身のような他のより大きなソフトウェアの distribution と混同しやすいからだ。

パッケージインストールの要件

このセクションでは、他の Python パッケージをインストールする前に行うべき手順を説明する。

pip, setuptools, wheel をインストールする

• Python 2 の 2.7.9 以上、または Python 3 の 3.4 以上を python.org からインストールした場合、pip と setuptools は既に存在する。ただし最新版へのアップグレードが必要だ:

  Linux または OS X では:

  pip install -U pip setuptools
  

  Windows では:

  python -m pip install -U pip setuptools
  

• Linux 上でシステムのパッケージマネージャ(“yum”, “apt-get” など…)管理下の Python 環境を使っており、システムのパッケージマネージャを使って pip のインストールとアップグレードを行いたいなら、 Linux パッケージマネージャによる pip/setuptools/whell のインストール を見よ。

• それ以外の場合:

• 安全な手段で get-pip.py をダウンロードする。[1]

• python get-pip.py を実行する。[2] これは pip のインストールとアップグレードを行う。加えて、setuptools と wheel を (まだインストールされていなければ)インストールする。

  警告

  オペレーティングシステムまたはその他のパッケージマネージャ管理下の Python 環境を使っている場合は注意が必要だ。get-pip.py はそれらのツールとは協調しないので、システムが矛盾した状態になるかもしれない。

仮想環境を作る(必要なら)

詳細は 以下のセクション で述べるが、基本的なコマンドはこうだ:

virtualenv を使う場合:

pip install virtualenv
virtualenv <DIR>
source <DIR>/bin/activate

venv を使う場合: [3]

python3 -m venv <DIR>
source <DIR>/bin/activate

仮想環境の作成

Python「仮想環境」は、Python パッケージ をグローバルにではなくアプリケーション固有の隔離された場所にインストールできるようにする。

あるアプリケーションで LibFoo バージョン 1 が必要だが、別のアプリケーションではバージョン 2 が必要だとしよう。これらのアプリケーションを併用するにはどうしたらよいか?もし何もかもを /usr/lib/python2.7/site-packages (またはプラットフォーム標準の場所)にインストールしていると、アップグレードすべきでないアプリケーションを意図せずアップグレードしてしまう状況が容易に起こりうる。

より一般的な話をすると、インストールしたアプリケーションをそのままの状態に保ちたい場合はどうか?現在あるアプリケーションがうまく動いていても、それが利用するライブラリが変わったり、ライブラリのバージョンが変わったりすると、そのアプリケーションが壊れる可能性がある。

また、パッケージ をグローバルな site-package ディレクトリにインストールできない場合はどうか?共用ホストがその例だ。

仮想環境はこれら全てのケースで役立つ。仮想環境はそれ自身のインストールディレクトリを持ち、他の仮想環境とライブラリを共有しない。

現在、Python 仮想環境を作るために 2 つのツールが利用できる:

• venv は Python 3.3 以降でデフォルトで利用できる。Python 3.4 以降では、仮想環境作成時に pip と setuptools のインストールも行う。
• virtualenv は Python とは別にインストールする必要があるが、 Python 2.6+ と Python 3.3+ の両方をサポートする。また、仮想環境作成時に pip, setuptools, wheel が常にインストールされる(Python のバージョンによらず)。

基本的な使い方はこうだ:

virtualenv を使う場合:

virtualenv <DIR>
source <DIR>/bin/activate

venv を使う場合:

python3 -m venv <DIR>
source <DIR>/bin/activate

詳細は virtualenv, venv のドキュメントを見よ。

インストールには pip を使う

pip は推奨インストーラだ。以下では、最も一般的な使い方について説明する。詳細については、完全な リファレンスガイド を含む pip ド キュメント を見よ。

まれなケースだが、pip の代わりに easy_install を使いたくなることがあるかもしれない。詳しくは、追加トピック の pip vs easy_install の解説を見よ。

PyPI からのインストール

pip の最も一般的な用途は、requirement specifier を指定して Python Package Index からのインストールを行うことだ。大まかに言うと、requirement specifier はプロジェクト名とそれに続くオプションの version specifier から成る。PEP 440 に現在サポートされる specifier の 完全な仕様 がある。以下にいくつかの例を示す。

“SomeProject” の最新バージョンをインストール:

pip install 'SomeProject'

特定のバージョンをインストール:

pip install 'SomeProject==1.4'

あるバージョン以上、あるバージョン未満のものをインストール:

pip install 'SomeProject>=1,<2'

特定のバージョンと 「互換」 なバージョンをインストール: [4]

pip install 'SomeProject~=1.4.2'

この場合、”==1.4.*” かつ “>=1.4.2” である任意のバージョンがインストールされる。

Source Distributions vs Wheels

pip は Source Distributions (sdist), Wheels のいずれからのインストールも行えるが、PyPI にその両方が存在する場合、pip は互換性のある wheel を優先する。

Wheels は事前ビルドされた distribution フォーマットであり、Source Distributions (sdist) より高速にインストールできる。プロジェクトがコンパイル済み拡張を含む場合は特に速い。

インストール時に wheel が見つからない場合、pip はローカルに wheel をビルドし、それを今後のインストール用にキャッシュする。これにより、今後 source distribution をリビルドする必要がなくなる。

パッケージのアップグレード

インストール済みの SomeProject を PyPI の最新版にアップグレード:

pip install --upgrade SomeProject

ユーザディレクトリへのインストール

パッケージ を現在のユーザ専用にインストールするには、 --user フラグを使う:

pip install --user SomeProject

詳しくは、pip ドキュメントの User Installs セクションを見よ。

Requirements files

Requirements File で指定された必要なパッケージをまとめてインストール:

pip install -r requirements.txt

VCS からのインストール

VCS から “editable” モードでプロジェクトをインストールできる。構文の完全な解説は、pip の VCS Support セクションを見よ。

pip install -e git+https://git.repo/some_pkg.git#egg=SomeProject          # from git
pip install -e hg+https://hg.repo/some_pkg.git#egg=SomeProject            # from mercurial
pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomeProject         # from svn
pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomeProject  # from a branch

PyPI 以外のインデックスからのインストール

代替インデックスからインストール:

pip install --index-url http://my.package.repo/simple/ SomeProject

インストール中に PyPI の他に追加のインデックスも検索:

pip install --extra-index-url http://my.package.repo/simple SomeProject

ローカルソースツリーからのインストール

ローカルのソースから 開発モード でインストール(プロジェクトはインストールされたように見えるが、ソースツリーから編集可能なままになる):

pip install -e <path>

ソースから通常のインストールも可能:

pip install <path>

ローカルアーカイブからのインストール

特定のローカルアーカイブファイルからインストール:

pip install ./downloads/SomeProject-1.0.4.tar.gz

アーカイブ群を含むローカルディレクトリからインストール(PyPI は無視):

pip install --no-index --find-links=file:///local/dir/ SomeProject
pip install --no-index --find-links=/local/dir/ SomeProject
pip install --no-index --find-links=relative/dir/ SomeProject

プレリリースのインストール

安定版に加え、プレリリースおよび開発版も探す(デフォルトでは、pip は安定版のみを探す):

pip install --pre SomeProject

Setuptools “Extras” のインストール

setuptools extras をインストール:

$ pip install SomePackage[PDF]
$ pip install SomePackage[PDF]==3.0
$ pip install -e .[PDF]==3.0  # editable project in current directory

---

[1]	この文脈で「安全」とは、モダンブラウザや curl のようなツールを使い、https URL からのダウンロード時に SSL 証明書を検証することを指す。

[2]	プラットフォームによっては、root または管理者権限が必要かもしれない。pip は現在、 ユーザ単位のインストールをデフォルト とする ことでこの状況を変えることを検討している。

[3]	Python 3.4 から、 venv (virtualenv の標準ライブラリ版)は pip がインストールされた仮想環境を作るので、 virtualenv と同等になる。

[4]	この compatible release specifier は PEP 440 で accept され、setuptools v8.0, pip v6.0 でサポートされた。

プロジェクトのパッケージングと配布

Page Status:Complete Last Reviewed:2015-09-08

このセクションでは、独自の Python プロジェクトを設定、パッケージ、配布する方法の基本を説明する。パッケージのインストール のページの内容は既に熟知していることを前提とする。

このセクションは Python プロジェクト開発のベストプラクティス全体を網羅するものでは ない 。例えば、バージョン管理、文書化、テストのためのガイダンスや推奨ツールは提供しない。

詳細なリファレンスは setuptools ドキュメントの Building and Distributing Packages を見よ。ただしそこにあるいくつかの勧告は内容が古くなっているかもしれない。不整合な点があれば、Python Packaging User Guide の方を選択せよ。

パッケージングと配布の要件

1. まず、パッケージインストールの要件 を満たしていることを確認する。

2. “twine” をインストール [1]:

   pip install twine
   

   これはプロジェクトの distribution を PyPI にアップロードするために必要だ(以下 を参照)。

プロジェクトの設定

初期ファイル

setup.py

最も重要なファイルは “setup.py” だ。これはプロジェクトのルートディレクトリに置かれる。サンプルは PyPA sample project の setup.py を見よ。

“setup.py” は主に 2 つの機能を提供する:

1. プロジェクトのさまざまな側面の設定。 setup.py の第一の特徴は、グローバル関数 setup() の単一の呼び出しを含むことだ。この関数に渡すキーワード引数によって、プロジェクトの詳細が定義される。最も重要な引数群は 以下のセクション で説明する。
2. パッケージングタスクに関連するさまざまなコマンドを実行するコマンドラインインターフェース。コマンドの一覧を得るには、 python setup.py --help-commands を実行する。

setup.cfg

“setup.cfg” は setup.py コマンドのデフォルトオプションを含む ini ファイルだ。サンプルは PyPA sample project の setup.cfg を見よ。

README.rst

全てのプロジェクトはその目的を記した readme ファイルを含むべきだ。最も一般的なフォーマットは reStructuredText で、拡張子 “rst” を持つが、これは必須事項ではない。

サンプルは PyPA sample project の README.rst を見よ。

MANIFEST.in

“MANIFEST.in” は python setup.py sdist (or bdist_wheel) が自動ではパッケージに含めないファイルを追加したい場合に必要だ。デフォルトでパッケージに含まれるファイルのリストは、distutils ドキュメントの Specifying the files to distribute を見よ。

サンプルは PyPA sample project の MANIFEST.in を見よ。

MANIFEST.in ファイルの記述の詳細は、distutils ドキュメントの The MANIFEST.in template を見よ。

<your package>

これは必須ではないが、プロジェクト内の Python モジュールとパッケージはプロジェクトと同 名 もしくは非常に似た名前の単一トップレベルパッケージ以下に置くのが最も一般的なやり方だ。

サンプルは PyPA sample project に含まれる sample パッケージを見よ。

setup() の引数

前述の通り、 setup.py の第一の特徴はグローバル関数 setup() への単一の呼び出しを含むことだ。この関数へのキーワード引数によってプロジェクトの詳細が定義される。

最も重要な引数群を以下で説明する。各コード片は PyPA sample project に含まれる setup.py からの引用だ。

name

name='sample',

これはプロジェクトの名前であり、PyPI 上での表示に使われる。使える文字の詳細は、PEP 426 の name セクションを見よ。

version

version='1.2.0',

これはプロジェクトの現在のバージョンだ。これによってユーザは最新版をインストールしているか判断でき、またユーザ自身のソフトウェアがどのバージョンに対してテスト済みかを示せる。

プロジェクトを公開すると、PyPI 上では各リリースについてバージョンが表示される。

バージョン番号を使ってユーザに互換性情報を伝える方法の詳細は、 Versioning scheme の選択 を見よ。

プロジェクトコード自体が実行時にバージョン番号へのアクセスを必要とする場合、最も単純な方法は setup.py とコードの両方にバージョン番号を書くことだ。値の重複を避けたいのであれば、方法はいくつかある。追加トピックの「プロジェクトバージョンの単一ソース化 」を見よ。

description

description='A sample Python project',
long_description=long_description,

プロジェクトの短い説明と長い説明だ。プロジェクトを公開すると、 PyPI 上でこれらの値が表示される。

url

url='https://github.com/pypa/sampleproject',

プロジェクトのホームページ URL を書く。

author

author='The Python Packaging Authority',
author_email='pypa-dev@googlegroups.com',

作者に関する情報を書く。

license

license='MIT',

ライセンスの種別を書く。

classifiers

classifiers=[
    # How mature is this project? Common values are
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    'Development Status :: 3 - Alpha',

    # Indicate who your project is intended for
    'Intended Audience :: Developers',
    'Topic :: Software Development :: Build Tools',

    # Pick your license as you wish (should match "license" above)
     'License :: OSI Approved :: MIT License',

    # Specify the Python versions you support here. In particular, ensure
    # that you indicate whether you support Python 2, Python 3 or both.
    'Programming Language :: Python :: 2',
    'Programming Language :: Python :: 2.6',
    'Programming Language :: Python :: 2.7',
    'Programming Language :: Python :: 3',
    'Programming Language :: Python :: 3.2',
    'Programming Language :: Python :: 3.3',
    'Programming Language :: Python :: 3.4',
],

プロジェクトの分類に使われる値のリストを書く。完全なリストは https://pypi.python.org/pypi?%3Aaction=list_classifiers を見よ。

keywords

keywords='sample setuptools development',

プロジェクトを説明するキーワードのリスト。

packages

packages=find_packages(exclude=['contrib', 'docs', 'tests*']),

プロジェクトに含まれる パッケージ のリストを得るために必要となる。手動でリストを書いてもよいが、 setuptools.find_packages を使うと自動で探してくれる。 exclude キーワード引数を使うことで、リリース/インストールしたくないパッケージを除外できる。

install_requires

install_requires=['peppercorn'],

“install_requires” は、プロジェクトの実行のために最小限必要な依存関係を指定するのに使う。pip がプロジェクトをインストールするとき、この指定に従って依存パッケージがインストールされる。

“install_requires” の使用については、install_requires vs Requirements files により詳しい情報がある。

package_data

package_data={
    'sample': ['package_data.dat'],
},

パッケージ に追加のファイルをインストールしなければならないことがしばしばある。これらはパッケージの実装に深く関わるデータだったり、パッケージを使うプログラマの関心を引くようなドキュメントを含むテキストファイルだったりする。これらのファイルは “package data” と呼ばれる。

“package_data” の値はパッケージ名から相対パス名群へのマッピングであり、指定されたファイルがパッケージへコピーされる。パスはパッケージを含むディレクトリからの相対パスとして解釈される。

詳しくは、 setuptools ドキュメント の Including Data Files を見よ。

data_files

data_files=[('my_data', ['data/data_file'])],

ほとんどの場合は package_data 設定で事足りるが、場合によっては パッケージ の 外 にデータファイルを置く必要があるかもしれない。 data_files ディレクティブはこれを可能にする。

シーケンス内の各 (directory, files) ペアでインストール先ディレクトリとそこに置くファイル群を指定する。ディレクトリが相対パスの場合、 installation prefix (pure-Python distribution なら Python の sys.prefix, 拡張モジュールを含むなら sys.exec_prefix) からの相対パスとして解釈される。各ファイル名はプロジェクトの source distribution のトップにある setup.py からの相対パスとして解釈される。

詳しくは、distutils の Installing Additional Files セクションを見よ。

注釈

setuptools は “data_files” に絶対パスを許しており、 sdist からのインストール時は、pip はそれを絶対パスのまま扱う。しかし wheel distribution からのインストール時はそうではない。Wheels は絶対パスをサポートしておらず、”site-packages” からの相対パスへのインストールとなる。この件に関する議論は wheel Issue #92 を見よ。

scripts

setup() は、予め作成されたスクリプトをインストールするための scripts キーワードをサポートしている。しかし、プラットフォーム間の互換性のために推奨されるアプローチは console_scripts エントリポイントを使うことだ(下記参照)。

entry_points

entry_points={
  ...
},

このキーワードを使うと、プロジェクトまたは依存パッケージにより定義される名前付きエントリポイントとしてプロジェクトが提供するプラグインを指定できる。

詳しくは、setuptools ドキュメントの Dynamic Discovery of Services and Plugins セクションを見よ。

最もよく使われるエントリポイントは “console_scripts” だ(下記参照)。

console_scripts

entry_points={
    'console_scripts': [
        'sample=sample:main',
    ],
},

スクリプトインターフェースを登録するには、”console_script” エントリポイント を使う。これらのインターフェースを実際のスクリプトに変換する作業はツールチェインが行ってくれる。[2] スクリプトは distribution のインストール中に生成される。

詳しくは、 setuptools ドキュメント の Automatic Script Creation を見よ。

Versioning scheme の選択

相互運用性のための標準準拠

個々の Python プロジェクトは固有のニーズに基づいて異なる versioning scheme を採用してよいが、それら全ては PEP 440 で指定された public version scheme に適合していなければならない。これは pip や setuptools のようなツール/ ライブラリのサポートを得るためだ。

標準準拠バージョン番号の例をいくつか示す:

1.2.0.dev1  # Development release
1.2.0a1     # Alpha Release
1.2.0b1     # Beta Release
1.2.0rc1    # Release Candidate
1.2.0       # Final Release
1.2.0.post1 # Post Release
15.10       # Date based release
23          # Serial release

バージョン番号を付けるアプローチには歴史的なバリエーションがあり、これらによりよく対応するため、PEP 440 は包括的な バージョン正規化 手法も定義している。これは個々のバージョン番号の様々な書式を標準化された正規形にマップするものだ。

Scheme の選択肢

Semantic versioning (推奨)

新規プロジェクトでは、 Semantic Versioning に基づく versioning scheme を推奨する。ただし、プレリリースとビルドメタデータを扱う際は異なるアプローチが採用されている。

Semantic versioning の本質は MAJOR.MINOR.MAINTENANCE の 3 パートからなる番号付けであり、プロジェクト作者は以下の場合にそれぞれの番号をインクリメントする:

1. MAJOR バージョンは、非互換な API 変更を行ったとき。
2. MINOR バージョンは、後方互換性のある機能追加を行ったとき。
3. MAINTENANCE バージョンは、後方互換性のあるバグ修正を行ったとき。

プロジェクト作者がこのアプローチを採用していれば、ユーザは “compatible release” specifier を利用できる。例えば name ~= X.Y とすることで、少なくともリリース X.Y が必要だが、後続のリリースのうち MAJOR バージョンが一致する任意のものを許す、という指定ができる。

Semantic versioning を採用する Python プロジェクトは、 Semantic Versioning 2.0.0 specification の 1-8 項に従うべきだ。

Date based versioning

Semantic versioning は全てのプロジェクトに適した選択肢というわけではない。例えば、定期的な日時ベースのリリースサイクルを持つものや、機能を削除するまでのリリース数を警告として提示する機能廃止プロセスを持つものには適さない。

Date based versioning の主な利点は、特定リリースの基本機能セットがどの程度古いものかがバージョン番号を見ただけですぐわかることだ。

典型的な Date based プロジェクトのバージョン番号は YEAR.MONTH の形だ (例えば、 12.04, 15.10)。

Serial versioning

これは最も単純な versioning scheme であり、リリースごとにインクリメントされる単一の番号から成る。

Serial versioning は開発者にとっては管理が非常に容易だが、エンドユーザにとっては最も追跡しにくいものだ。なぜなら、serial version number は API の後方互換性に関する情報をほとんど、または全く伝えないからだ。

Hybrid schemes

上で挙げたものを組み合わせることも考えられる。例えば、date based versioning と serial versioning を組み合わせて YEAR.SERIAL という方式を作ることもできる。これはおおよそのリリース時期が容易にわかるが、年内の特定のリリースサイクルでコミットするわけではない。

Pre-release versioning

基本となる versioning scheme がどうであれ、ある最終リリースに対するプレリリースは以下のように公開される:

• 0 以上の dev リリース (”.devN” サフィックスで示す)
• 0 以上の alpha リリース (”.aN” サフィックスで示す)
• 0 以上の beta リリース (”.bN” サフィックスで示す)
• 0 以上の release candidates (”.rcN” サフィックスで示す)

pip とその他のモダンな Python パッケージインストーラは、依存パッケージをインストールする際はデフォルトでプレリリースを無視する。

Local version identifiers

Public version identifiers は、 PyPI 経由での配布をサポートするために設計されたものだ。Python のソフトウェア配布ツールは、local version identifier の概念もサポートしている。これは公開予定のないローカル開発ビルドや、再配布者によりメンテナンスされる修正リリースを識別するのに使われる。

Local version identifier は <public version identifier>+<local version label> の形になる。例えば:

1.2.0.dev1+hg.5.b11e5e6f0b0b  # 5th VCS commmit since 1.2.0.dev1 release
1.2.1+fedora.4                # Package with downstream Fedora patches applied

「開発モード」での作業

必須ではないが、作業中のプロジェクトを “editable” または “develop” と呼ばれるモードでローカルにインストールするのが一般的だ。これにより、インストールしたプロジェクトをそのまま編集できる。

今プロジェクトのルートディレクトリにいるとしよう。以下を実行する:

pip install -e .

いくぶん暗号的だが、 -e は --editable の短縮形で、 . はカレントディレクトリを指す。つまり、カレントディレクトリ(プロジェクト)を editable モードでインストールするという意味だ。これは “install_requires” で宣言された依存パッケージ、および “console_scripts” で宣言されたスクリプトも全てインストールする。このときインストールされる依存パッケージは editable モードにはならない。

依存パッケージも editable モードでインストールしたいというのはよくあることだ。例えば、プロジェクトが “foo” と “bar” を必要としているが、 “bar” は VCS から editable モードでインストールしたいとしよう。その場合、requirements ファイルは以下のように書ける:

-e .
-e git+https://somerepo/bar.git#egg=bar

1 行目はプロジェクトと依存パッケージ全てをインストールすると宣言している。2 行目は依存パッケージ “bar” を PyPI からではなく VCS から取得するようにオーバーライドしている。Requirements ファイルの詳細は、pip ドキュメントの Requirements File セクションを見よ。VCS インストールの詳細は、pip ドキュメントの VCS Support セクションを見よ。

最後に、依存パッケージを何もインストールしたくないなら、以下を実行する:

pip install -e . --no-deps

詳しくは、 setuptools ドキュメント の Development Mode を見よ。

プロジェクトのパッケージング

プロジェクトを PyPI のような Package Index からインストール可能にするには、プロジェクトの Distribution (パッケージ)を作る必要がある。

Source Distributions

最低でも、Source Distribution は作る必要がある:

python setup.py sdist

“Source distribution” はビルドされていない(つまり、Built Distribution ではない)。これを pip でインストールする際はビルドのステップが必要だ。たとえ distribution が pure Python (一切の拡張を含まない)であっても、 setup.py からインストールメタデータをビルドするステップが必要となる。

Wheels

プロジェクトの wheel も作るべきだ。Wheel は ビルド済みパッケー ジ であり、インストールに「ビルド」プロセスを必要としない。Wheel があると、エンドユーザは source distribution よりずっと高速にインストールができる。

プロジェクトが pure Python (一切のコンパイル済み拡張を含まない)で、 Python 2 と 3 の両方をネイティブにサポートするなら、“Universal Wheel” (以下のセクションを参照) と呼ばれるものを作ることになる。

プロジェクトが pure Python で、Python 2 と 3 の片方しかネイティブにサポートしないなら、“Pure Python Wheel (以下のセクションを参照) を作ることになる。

プロジェクトがコンパイル済み拡張を含むなら、“Platform Wheel” (以 下のセクションを参照) と呼ばれるものを作ることになる。

Universal Wheels

“Universal Wheels” は pure Python (一切のコンパイル済み拡張を含まない) かつ Python 2 と 3 をサポートする wheels だ。この wheel はどの環境でも pip でインストールできる。

Universal Wheel をビルドするには:

python setup.py bdist_wheel --universal

“setup.cfg” で --universal フラグを恒久的に設定することもできる(サンプル: sampleproject/setup.cfg)

[bdist_wheel]
universal=1

--universal 設定は以下の場合のみ使うこと:

1. プロジェクトが一切の修正なしで(つまり、2to3 を必要とせず) Python 2 と 3 で動く
2. プロジェクトが C 拡張を一切含まない。

今のところ、 bdist_whell はこの設定が不適切に使われていても警告を出さないので注意。

プロジェクトがオプションの C 拡張を含むなら、universal wheel を公開することは勧められない。というのは、pip は source installation より wheel を優先するため、拡張をビルドしなくなるからだ。

Pure Python Wheels

“Universal” でない “Pure Python Wheels” は、pure Python (一切のコンパイル済み拡張を含まない)かつ Python 2 と 3 の片方しかネイティブにサポートしない whells だ。

この wheel をビルドするには:

python setup.py bdist_wheel

bdist_wheel はコードが pure Python であることを検出し、ビルドに使ったのと同じメジャーバージョン (Python 2 または Python 3)の Python 環境で使えるように名付けられた wheel を作る。Wheelファイルの命名の詳細は、 PEP 425 を見よ。

コードが Python 2 と 3 の両方をサポートするが、それが異なったコードによる(例えば、 “2to3” を使っている)場合は、 setup.py bdist_wheel を 2 回(Python 2, 3 用に 1 回ずつ)実行できる。これでそれぞれのバージョン用の wheels が生成される。

Platform Wheels

“Platform Wheels” は Linux, OSX, Windows といったプラットフォーム固有の wheels だ。これは普通、コンパイル済み拡張を含むためにそうなっている。

この wheel をビルドするには:

python setup.py bdist_wheel

bdist_wheel はコードが pure Python でないことを検出し、ビルドされたプラットフォームでのみ使えるように名付けられた wheel を作る。Wheel ファイルの命名の詳細は、PEP 425 を見よ。

注釈

PyPI は今のところ Windows と OS X 向けの platform wheels のみアップロードを許可しており、Linux は許可して「いない」。今のところ、wheel tag specification (PEP 425) は Linux ディストリビューション間の多様性を扱わない。

PyPI へのプロジェクトのアップロード

注釈

メインの PyPI リポジトリへリリースする前に、 PyPI テストサイト で練習することを勧める。このテストサイトは半定期的にクリーンアップされる。テストサイトを使うための設定については、 この説明 を見よ。

Distribution を作るコマンドを実行すると、プロジェクトのルートディレクトリ下に新規ディレクトリ dist/ が作られる。ここにアップロードすべき distribution ファイルがある。

アカウント作成

まず、PyPI のユーザアカウントが必要だ。これには 2 つの方法がある:

1. PyPI ウェブサイトのフォームを使って 手動でアカウントを作る。
2. (非推奨): 最初のプロジェクトを登録するついでにアカウントを作る (セキュリティ上の理由で推奨されない。次のセクションの方法 #3 を見よ)。

方法 #1 (フォーム)でアカウントを作った場合、 ~/.pypirc ファイルを以下のように書く必要がある:

[distutils]
index-servers=pypi

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

パスワード行は省略してもよい。twine に -p PASSWORD 引数を渡すか、単に要求されたときにパスワードを入力すればよい。

プロジェクトの登録

次に、これが最初のリリースの場合、アップロードする前にプロジェクトを明示的に登録する必要がある(今のところ)。

これには 3 つの方法がある:

1. PyPI ウェブサイトのフォーム を使い、ローカルのプロジェクトツリーの myproject.egg-info/PKG-INFO にある PKG-INFO をアップロードする。このファイルまたはディレクトリがない場合は、 python setup.py egg_info を実行すれば生成される。
2. twine register dist/mypkg.whl を実行すると、twine が指定されたファイル内のパッケージメタデータに基づいてプロジェクトを登録する。twine が正しく動くために、予め ~/.pypirc を適切に設定しておかなければならない。
3. (非推奨): python setup.py register を実行する。まだユーザアカウントがない場合、ウィザードが作成してくれる。ここでこのアプローチを説明するのは他のガイドで言及されているからだが、推奨はしない。なぜなら、Python のバージョンによっては平文の HTTP, または検証されていない HTTPS 接続を使う可能性があり、その場合ユーザ名とパスワードが傍受できてしまうからだ。

Distributions のアップロード

ついに、PyPI へ distributions をアップロードできるようになった。

これには 2 つの方法がある:

1. twine を使う:

   twine upload dist/*
   

   twine を使う最大の理由は、 python setup.py upload (以下の方法 #2) はファイルを平文でアップロードすることだ。これだと MITM 攻撃でユーザ名とパスワードが盗まれうる。twine は検証された TLS 接続のみを使って PyPI へのアップロードを行い、認証情報を盗難から守る。

   次に、twine を使うと distribution ファイルを事前に作っておくことができる。 python setup.py upload では、同じコマンド呼び出しで作ったものしかアップロードできない。これだと、PyPI へのアップロード前にそのファイルをテストして正しく動くことを保証することができない。

   最後に、twine を使うと、事前にファイルに署名し、その .asc ファイルをコマンドラインで渡せる (twine upload twine-1.0.1.tar.gz twine-1.0.1.tar.gz.asc)。これにより、パスフレーズを gpg 以外に対して入力していないことを保証できる(あなた が直接 gpg --detach-sign -a <filename> を実行するのだから)。

2. (非推奨): setuptools を使う:

   python setup.py sdist bdist_wheel upload
   

   ここでこのアプローチを説明するのは他のガイドで言及されているからだが、推奨はしない。なぜなら、Python のバージョンによっては平文の HTTP, または検証されていない HTTPS 接続を使う可能性があり、その場合ユーザ名とパスワードが傍受できてしまうからだ。

---

[1]	プラットフォームによっては、root または管理者権限が必要かもしれない。pip は現在、 ユーザ単位のインストールをデフォルト とする ことでこの状況を変えることを検討している。

[2]	具体的には、”console_script” アプローチを使うと Windows 上で .exe ファイルを生成できる。これが必要なのは Windows が .exe ファイルを特別扱いするためだ。 PATHEXT や Python Launcher for Windows のようなスクリプト実行機能は多くのケースで利用できるが、全てではない。

追加トピック

Last Reviewed:2015-09-08

このセクションでは、特定の プロジェクト や「パッケージのインストール 」、「プロジェクトのパッケージングと配布 」ガイドに収まらない様々なパッケージングの概念とトピックについて説明する。

Linux パッケージマネージャによる pip/setuptools/whell のインストール

Page Status:Incomplete Last Reviewed:2015-09-17

このセクションでは、Linux パッケージマネージャを使って pip, setuptools, wheel をインストールする方法を説明する。

python.org からダウンロードした Python を使っているなら、このセクションの内容は当てはまらない。代わりに、 パッケージインストールの要件 セクションを見よ。

特定の Linux ディストリビューションでサポートされる pip, setuptools, wheel は、それが公開された時点で既に古いバージョンであることがよくある。そして、更新は普通セキュリティ上の理由でのみ行われ、機能更新は行われない。ディストリビューションによっては、より新しいバージョンを提供する追加リポジトリがある。我々が知っているリポジトリについては以下で説明する。

また、Linux ディストリビューションがセキュリティ上の理由だったり固有の標準に合わせるためにパッチを当てていることもしばしばある。場合によっては、これがオリジナルのパッチなしバージョンとは異なるバグや予期せぬ動作につながる可能性がある。わかっている範囲については以下で注意する。

Fedora

• Fedora 21:

  • Python 2:

    sudo yum upgrade python-setuptools
    sudo yum install python-pip python-wheel
    

  • Python 3: sudo yum install python3 python3-wheel

• Fedora 22:

  • Python 2:

    sudo dnf upgrade python-setuptools
    sudo dnf install python-pip python-wheel
    

  • Python 3: sudo dnf install python3 python3-wheel

Python 2 の pip, setuptools, wheel のより新しいバージョンを得るには、 Copr Repo instructions に従って PyPA Copr Repo を有効にし、以下を実行する:

sudo yum|dnf upgrade python-setuptools
sudo yum|dnf install python-pip python-wheel

CentOS/RHEL

CentOS と RHEL はデフォルトで setuptools がインストールされているが、pip, wheel はコアリポジトリでは提供されない。

システムの Python 用に pip, wheel をインストールするには、2 つの方法がある:

1. この説明 に従って EPEL repository を有効にする。EPEL 6, EPEL 7 では、以下のようにして pip をインストールできる:

   sudo yum install python-pip

   EPEL 7 (EPEL 6 は不可)では、以下のようにして wheel をインストールできる:

   sudo yum install python-wheel
   

   EPEL が提供するのは競合を起こさない追加パッケージのみなので、 setuptools は提供されない。それはコアリポジトリに存在するからだ。

2. この説明 [1] に従って PyPA Copr Repo を有効にする。以下のようにして pip, wheel をインストールできる:

   sudo yum install python-pip python-wheel
   

   setuptools のアップグレードも行うには、以下を実行する:

   sudo yum upgrade python-setuptools
   

並行して非システム環境に pip, wheel, setuptools を (yum を使って)インストールするには、2 つの方法がある:

1. “Software Collections” 機能を使い、pip, setuptools, wheel を含む共存可能なソフトウェアコレクションを有効にする。

   • RedHat の場合、以下を参照: http://developers.redhat.com/products/softwarecollections/overview/
   • CentOS の場合、以下を参照: https://www.softwarecollections.org/en/

   このコレクションは最新バージョンを含むとは限らない。

2. IUS repository を有効にし、 parallel-installable な Python を pip, setuptools, wheel と一緒にインストールする。これはほぼ最新に保たれている。

   例えば、CentOS7/RHEL7 で Python 3.4 を選ぶ場合:

   sudo yum install python34u python34u-wheel
   

openSUSE

• Python 2:

  sudo zypper install python-pip python-setuptools python-wheel
  

• Python 3:

  sudo zypper install python3-pip python3-setuptools python3-wheel
  

Debian/Ubuntu

sudo apt-get install python-pip

Python 3 の場合、”python” を “python3” に置き換える。

警告

Debian/Ubuntu の最近のバージョンは pip がデフォルトで “User Scheme” を使うように修正を加えている。これは大きな仕様変更であり、ユーザによっては驚くべき動作になりうる。

Arch Linux

• Python 2:

  sudo pacman -S python2-pip
  

• Python 3:

  sudo pacman -S python-pip
  

---

[1]	今のところ、CentOS/RHEL では “copr” yum プラグインは利用できない。よって、説明にあるように唯一の選択肢はリポジトリファイルを手動で配置することだ。

バイナリ拡張

Page Status:Incomplete Last Reviewed:2013-12-08

CPython リファレンスインタプリタの一つの特徴は、Python コードを実行するだけでなく、他のソフトウェアから利用できる豊富な C API を提供していることだ。この C API の最も一般的な使い方の一つは、インポート可能な C 拡張を作り、pure Python コードでは容易にはできないことを可能にすることだ。

バイナリ拡張の概要

ユースケース

バイナリ拡張の典型的なユースケースは、慣例的には 3 つのカテゴリに分かれる:

• 高速化モジュール: これらのモジュールは完全に自己完結していて、単に CPython で動く同等な pure Python コードより高速に動作するために作られる。理想的には、高速化モジュールは同等な pure Python モジュールを常に備えており、あるシステムで高速版が利用できないときの fallback として使えるようになっているべきだ。CPython 標準ライブラリでは高速化モジュールが広く使われている。

• ラッパーモジュール: これらのモジュールは既存の C インターフェースを Python コードから利用するために作られる。これらは基礎となる C インターフェースを直接公開するかもしれないし、あるいは API を使いやすくするために Python 言語機能を利用し、より “Pythonic” な API を公開するかもしれない。CPython 標準ライブラリではラッパーモジュールが広く使われている。

• 低レベルシステムアクセス: これらのモジュールは CPython ランタイムのより低レベルな機能や、オペレーティングシステム、または基礎となるハードウェアにアクセスするために作られる。プラットフォーム固有のコードにより、拡張モジュールは pure Python コードでは不可能なことができるかもしれない。いくつかの CPython 標準ライブラリは C で書かれており、言語レベルでは公開されていないインタプリタの内部機能にアクセスしている。

  C 拡張の特筆すべき機能の一つは、インタプリタランタイムへコールバックする必要がない場合、時間のかかる操作(CPU bound か IO bound かによるが)の間、CPython の GIL (global interpreter lock) を解放できることだ。

全ての拡張モジュールが以上のカテゴリにきっちり当てはまるわけではない。例えば、NumPy に含まれる拡張モジュールはこれら 3 つのユースケース全てにわたっている - 速度上の理由で内部ループを C に移し、C, FORTRAN その他の言語で書かれた外部ライブラリをラップし、また CPython および基礎となるオペレーティングシステムの低レベルインターフェースを使うことで、ベクトル化演算の並列実行をサポートし、作成されるオブジェクトのメモリレイアウトを厳密に制御している。

欠点

バイナリ拡張を使う主な欠点は、その後のソフトウェア配布がより難しくなることだ。Python を使う利点の一つはその大部分がクロスプラットフォームであることだが、拡張モジュールを書くのに使われる言語(普通は C か C++ だが、実際は CPython C API にバインドできるなら何でもよい)は通常、プラットフォームごとにカスタムバイナリを作る必要がある。

つまり、バイナリ拡張は:

• エンドユーザがソースからビルドできるか、または誰かが共通のプラットフォーム用のビルド済みバイナリを公開している必要がある。
• CPython リファレンスインタプリタの異なるビルドに対して互換性がないかもしれない。
• PyPy, IronPython, Jython などの代替インタプリタではしばしば正しく動かない。
• 手で書かれている場合、メンテナンスがより難しくなる。なぜならメンテナは Python だけでなく、バイナリ拡張の作成に使われる言語や CPython C API の詳細にも精通していなければならないからだ。
• Pure Python の fallback 実装が提供されている場合、メンテナンスがより難しくなる。なぜなら変更点は 2 箇所で実装する必要があり、両方のバージョンが常に動作することを保証するためのテストスイートはさらに複雑化するからだ。

バイナリ拡張に頼ることのもう一つの欠点は、代替インポートメカニズム(例えば zip ファイルからモジュールを直接インポートする機能)が拡張モジュールではしばしば動作しないことだ(ほとんどのプラットフォームにおける動的ロードメカニズムは、ディスクからライブラリをロードすることしかできないので)。

手書きの高速化モジュールに対する代案

拡張モジュールが単にコードを速く実行するために使われているだけなら(プロファイリングで速度向上がメンテナンスコストに見合うコードを見分けた後で)、他の選択肢もいくつか考慮すべきだ:

• 既に最適化されたものがないか探す。CPython 標準ライブラリは多くの最適化されたデータ構造とアルゴリズムを含む(特に、組み込み関数と collections および itertools モジュールにおいて)。Python Package Index にはさらなる選択肢がある。場合によっては、標準ライブラリやサードパーティモジュールを適切に選ぶことで、独自の高速化モジュールを作る必要がなくなる。
• 長時間動作するアプリケーションでは、JIT コンパイル機能を持つ PyPy インタプリタ を標準 CPython ランタイムの代わりに使うのが適切かもしれない。PyPy を採用する上で主な障害となるのは、他のバイナリ拡張モジュールへの依存だ - PyPy は確かに CPython C API をエミュレートするのだが、それに依存するモジュールは PyPy JIT で問題を起こすことがあり、またエミュレーションレイヤはしばしば CPython が現在許容している拡張モジュールの潜在的欠陥の影響を受ける(よくあるのは参照カウント周りのエラーだ - オブジェクトの参照カウント 2 が 1 になったとしても問題はないだろうが、1 が 0 になるのは重大な問題だ)。
• Cython は成熟した静的コンパイラで、ほとんどの Python コードを C 拡張モジュールへコンパイルできる。最初のコンパイルで (CPython インタプリタレイヤを介さないことで)いくらか速度が向上する。また、Cython のオプションの静的型付け機能によりさらなる速度向上が見込める。Cython を使うと完成したアプリケーションの配布が複雑化する欠点はあるものの、Python プログラマにとって参入障壁が低い利点がある(C や C++ のような他の言語に比べれば)。
• Numba はより新しいツールで、科学 Python コミュニティのメンバーにより作られた。これは LLVM を活用し、実行時に Python アプリケーションをネイティブコードへ選択的にコンパイルできるようにするのが目的だ。コードが実行されるシステムで LLVM が利用可能でなければならないが、大幅な速度向上が見込める。ベクトル化に適した操作では特にそうだ。

手書きのラッパーモジュールに対する代案

C ABI (Application Binary Interface) は複数のアプリケーション間で機能を共有するための標準だ。CPython C API (Application Programming Interface) の強みの一つは、Python ユーザがこの機能を利用できることだ。しかし、ラッパーモジュールを手で書くのはかなり退屈な作業なので、他のアプローチをいくつか見当すべきだ。

以下で述べるアプローチは配布を簡単にするものではないが、ラッパーモジュールを最新に保つメンテナンス負担を大幅に軽減 できる 。

• Cython は高速化モジュールだけでなく、ラッパーモジュールの作成にも役立つ。ただしインターフェースは依然として手でラップしなければならないので、大きな API をラップする場合はよい選択肢ではないかもしれない。

• cffi は PyPy 開発者の一部が作ったプロジェクトで、Python と C の両方を知っているプログラマが C モジュールを Python アプリケーション向けに公開するのを容易にするのが目的だ。また、C を知らなくても、ヘッダファイルに基づいて C モジュールをラップするのを比較的容易にしてくれる。

  cffi の主な利点の一つは、PyPy JIT と互換性があることだ。これにより、CFFI ラッパーモジュールは PyPy のトレース JIT 最適化の完全な恩恵を受けられる。

• SWIG はラッパーインターフェース生成器で、 Python を含む様々な言語が C および C++ コードと連携できるようにする。

• 標準ライブラリの ctypes モジュールは、ヘッダファイルがないときに C レベルのインターフェースにアクセスするのに便利だが、C ABI レベルでしか動作しないのが難点だ。このため、実際にライブラリがエクスポートするインターフェースと Python コードで宣言されたそれとの間の一貫性の自動チェックは一切行われない。対照的に、上記の選択肢は全て C API レベルで動作でき、C ヘッダファイルを使うことで、ラップ対象のライブラリがエクスポートするインターフェースと Python ラッパーモジュールが期待するそれとの間の一貫性を保証できる。 cffi は直接 C ABI レベルでも動作 できる が、そのような使い方をすると ctypes と同様のインターフェースの一貫性に関する問題を抱えることになる。

低レベルシステムアクセスに対する代案

(理由を問わず)低レベルシステムアクセスを必要とするアプリケーションでは、バイナリ拡張モジュールがしばしば最善の方法 だ 。CPython ランタイム自身への低レベルアクセスについては特にそうだ。なぜなら、ある種の操作 (GILの解放など)はインタプリタがコードを実行中だと単に無効化されるからだ。これはたとえ ctypes や cffi のようなモジュールを使って関連 C API インターフェースにアクセスしても同様だ。

拡張モジュールが(CPython ランタイムではなく)基礎となるオペレーティングシステムやハードウェアを操作している場合は、単に普通の C ライブラリ(または C++ や Rust のような C 互換 ABI をエクスポートできるシステムプログラミング言語のライブラリ)を書き、それから上記のラッピング手法のどれかを使って Python モジュールとしてインポートできるインターフェースを作る方がよい場合もあるかもしれない。

バイナリ拡張の実装

mention the stable ABI (3.2+, link to the CPython C API docs)
mention the module lifecycle
mention the challenges of shared static state and subinterpreters
mention the implications of the GIL for extension modules
mention the memory allocation APIs in 3.4+

mention again that all this is one of the reasons why you probably
*don't* want to handcode your extension modules :)

バイナリ拡張のビルド

Windows 上でのビルド環境構築

バイナリ拡張をビルドする前に、適切なコンパイラが利用できることを確認する必要がある。Windows では、Visual C が公式 CPython インタプリタのビルドに使われており、互換性のあるバイナリ拡張のビルドにもこれを使うべきだ。

Python 2.7 は Visual Studio 2008 を使っており、Python 3.3 と 3.4 は Visual Studio 2010 を使っており、Python 3.5+ は Visual Studio 2015 を使っている。残念ながら、旧バージョンの Visual Studio はもはや Microsoft から容易に入手できなくなった。よって、Python 3.5 より前のバージョンについては、別の方法でコンパイラを入手しなければならない(必要なバージョンの Visual Studio を既に持っているのでなければ)。

バイナリ拡張のビルド環境構築手順は以下の通り:

Python 2.7 の場合

1. “Visual C++ Compiler Package for Python 2.7” をインストールする。これは Microsoft のウェブサイト から入手できる。
2. setup.py で(最新バージョンの) setuptools を使うようにする (いずれにしろ、pip がこれを行ってくれる)。
3. 完了。

Python 3.4 の場合

1. “Windows SDK for Windows 7 and .NET Framework 4” (v7.1) をインストールする。これは Microsoft のウェブサイト から入手できる。
2. SDK のコマンドプロンプトを使うようにする(環境変数が設定され、SDK が PATH に登録される)。
3. 環境変数 DISTUTILS_USE_SDK=1 を設定する。
4. 完了。

Python 3.5 の場合

1. Visual Studio 2015 Community Edition (または、リリースされていればより新しいバージョン)をインストールする。
2. 完了。

Python 3.5 以降では、Visual Studio は後方互換性のある方法で動作するため、今後の任意のバージョンの Visual Studio で Python 3.5 以降の全バージョンの Python 拡張をビルドできる。

FIXME

cover Windows binary compatibility requirements
cover Mac OS X binary compatibility requirements
cover the vagaries of Linux distros and other *nix systems

バイナリ拡張の公開

FIXME

cover publishing as wheel files on PyPI or a custom index server
cover creation of Windows and Mac OS X installers
mention the fact that Linux distros have a requirement to build from
source in their own build systems anyway, so pre-built binaries for
*nix systems currently aren't common

複数の Python バージョンのサポート

Page Status:Incomplete Last Reviewed:2014-12-24

FIXME

Useful projects/resources to reference:

- DONE six
- DONE python-future (http://python-future.org)
- tox
- DONE Travis and Shining Panda CI (Shining Panda no longer available)
- DONE Appveyor
- DONE Ned Batchelder's "What's in Which Python"
  - http://nedbatchelder.com/blog/201310/whats_in_which_python_3.html
    - http://nedbatchelder.com/blog/201109/whats_in_which_python.html
- Lennart Regebro's "Porting to Python 3"
- Greg Hewgill's script to identify the minimum version of Python
  required to run a particular script:
  https://github.com/ghewgill/pyqver
- the Python 3 porting how to in the main docs
- cross reference to the stable ABI discussion
  in the binary extensions topic (once that exists)
- mention version classifiers for distribution metadata

Python パッケージを作る際、異なるバージョンの Python で使えるようにする必要がしばしば生じる。異なる Python バージョンには異なる(または別名の)標準ライブラリが含まれるかもしれず、また Python バージョン 2.x, 3.x 間では構文を含めた変更が行われている。

パッケージが全てのターゲット Python (および OS!) バージョンで正しく動くことを保証するための全テストは、手動でやったのでは非常に時間がかかるだろう。幸い、この問題に対処するツールがいくつかあるので、ここで簡単に論ずる。

自動テストと継続的インテグレーション

自動テスト用のホスト型サービスがいくつかある。これらは通常、ソースコードリポジトリ(Github や Bitbucket) を監視し、新たなコミットのたびにプロジェクトのテストスイートを実行する。

これらのサービスは、プロジェクトのテストスイートを 複数バージョンの Python で実行する機能も提供しており、コードが正しく動くかどうかの迅速なフィードバックが得られる。開発者はそうしたテストを自分で実行する必要がない。

Wikipedia に多くの継続的インテグレーションシステムの幅広い 比較 がある。2 つのホスト型サービスを組み合わせて使うことで、Linux, Mac, Windows での自動テストができる:

• Travis CI は Linux と Mac OSX の両環境を提供する。執筆時点で、Linux 環境は Ubuntu 12.04 LTS Server Edition 64 bit, OSX は 10.9.2 だ。
• Appveyor は Windows 環境 (Windows Server 2012) を提供する。

TODO Either link to or provide example .yml files for these two
services.

TODO How do we keep the Travis Linux and OSX versions up-to-date in this
document?

Travis CI と Appveyor はともに YAML 形式のファイルを必要とし、これがテスト指示書の仕様となる。失敗したテストがあれば、指定した構成の出力ログを検査できる。

Python プロジェクトを単一ソースで Python 2, 3 両方へデプロイしたい場合、方法はいくつかある。

単一ソース Python パッケージ用ツール

six は Benjamin Peterson が開発したツールで、Python 2 と Python 3 の間の違いを吸収するためのものだ。six パッケージは広く使われており、Python 2 と 3 の両方で使える単一ソース Python モジュールを書くための信頼できる方法と考えられる。six モジュールは Python 2.5 の時点から使われていた。Armin Ronacher が開発した modernize というツールを使うと、six によるコード修正を自動で適用できる。

six と似たものとして python-future パッケージがあり、これは Python 2 と Python 3 の間の互換レイヤを提供する; ただしこのパッケージは six と異なり、2 つの Python バージョンの一方に合致する構文を使うことで Python 2 と Python 3 の相互運用性を実現しようとする。つまり:

• Python 3 プロジェクトで(構文上の) Python 2 モジュールが使える。
• Python 2 プロジェクトで(構文上の) Python 3 モジュールが使える。

この双方向性により、python-future は Python 2 パッケージを Python 3 構文へモジュールごとに変換する方法を提供する。しかし、six とは対照的に、python-future は Python 2.6 以降でのみサポートされる。six に対する modernize と同様、python-future には futurize, pasteurize という 2 つのスクリプトが付属しており、Python 2 モジュールと Python 3 モジュールそれぞれに適用できる。

six または python-future を使うと、パッケージに実行時の依存関係が追加される: python-future を使う場合、 futurize スクリプトを --stage1 オプション付きで呼び出すことができ、これは Python 2.6+ が既に Python 3 への前方互換性を持つ変更のみを施す。残りの互換性問題は手動で解決する必要がある。

どの Python で何が変わった?

Ned Batchelder が各 Python リリースでの変更点のリストを Python 2, Python 3 について個別に提供している。これらのリストは Python バージョン間での変更点がパッケージに影響するかどうかのチェックに使えるかもしれない。

TODO These lists should be reproduced here (with permission).

TODO The py3 list should be updated to include 3.4

Patching & Forking

Page Status:Incomplete Last Reviewed:2014-12-24

FIXME

- locally patch 3rd-part projects to deal with unfixed bugs
   - old style pkg_resources "patch releases":  1.3-fork1
   - PEP440's local identifiers: http://www.python.org/dev/peps/pep-0440/#local-version-identifiers
- fork and publish when you need to publish a project that depends on the fork
   (DONT use dependency links)

PyPI mirrors and caches

Page Status:Incomplete Last Reviewed:2014-12-24

Mirroring or caching of PyPI can be used to speed up local package installation, allow offline work, handle corporate firewalls or just plain Internet flakiness.

Three options are available in this area:

1. pip provides local caching options,
2. devpi provides higher-level caching option, potentially shared amongst many users or machines, and
3. bandersnatch provides a local complete mirror of all PyPI packages.

Caching with pip

pip provides a number of facilities for speeding up installation by using local cached copies of packages:

1. Fast & local installs by downloading all the requirements for a project and then pointing pip at those downloaded files instead of going to PyPI.

2. A variation on the above which pre-builds the installation files for the requirements using pip wheel:

   $ pip wheel --wheel-dir=/tmp/wheelhouse SomeProject
   $ pip install --no-index --find-links=/tmp/wheelhouse SomeProject
   

Caching with devpi

devpi is a caching proxy server which you run on your laptop, or some other machine you know will always be available to you. See the devpi documentation for getting started.

Complete mirror with bandersnatch

bandersnatch will set up a complete local mirror of all PyPI packages (externally-hosted packages are not mirrored). See the bandersnatch documentation for getting that going.

A benefit of devpi is that it will create a mirror which includes packages that are external to PyPI, unlike bandersnatch which will only cache packages hosted on PyPI.

プロジェクトバージョンの単一ソース化

Page Status:Complete Last Reviewed:2015-12-03

プロジェクトのバージョン番号について、単一ソースの原則を維持する多くの手法がある:

1. setup.py を正規表現でパースしてバージョンを得る。例えば(pip の setup.py より):

   def read(*names, **kwargs):
       with io.open(
           os.path.join(os.path.dirname(__file__), *names),
           encoding=kwargs.get("encoding", "utf8")
       ) as fp:
           return fp.read()
   
   def find_version(*file_paths):
       version_file = read(*file_paths)
       version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]",
                                 version_file, re.M)
       if version_match:
           return version_match.group(1)
       raise RuntimeError("Unable to find version string.")
   
   setup(
      ...
      version=find_version("package", "__init__.py")
      ...
   )
   

   注釈

   この手法は複雑な正規表現を扱わなければならない欠点がある。

2. 両方の場所で更新管理ができるか、もしくは両方の場所で使える API を持つ外部ビルドツールを使う。

   そんなツールはほとんどないが、挙げるとすれば bumpversion, changes, zest.releaser だ。この順序に特定の意図はないし、これで全てだとも限らない。

3. プロジェクト内の専用モジュール(例えば version.py) でグローバル変数 __version__ の値を設定し、 setup.py がそれを読んで exec した値を変数に格納する。

   execfile を使う例:

   execfile('...sample/version.py')
   # now we have a `__version__` variable
   # later on we use: __version__
   

   exec を使う例:

   version = {}
   with open("...sample/version.py") as fp:
       exec(fp.read(), version)
   # later on we use: version['__version__']
   

   この手法を使っている例: warehouse

4. 単純な VERSION というテキストファイルに値を格納し、 setup.py とプロジェクトコードの両方でそれを読む。

   with open(os.path.join(mypackage_root_dir, 'VERSION')) as version_file:
       version = version_file.read().strip()
   

   この手法の利点は Python に特化していないことだ。どのツールでもバージョンを読み取れる。

   警告

   この手法をとる場合、 VERSION ファイルが全ての source / binary distributions に含まれていることを確認しなければならない(例えば、 MANIFEST.in に include VERSION を追加するなど)。

5. setup.py で値を設定し、プロジェクトコードでは pkg_resources API を使う。

   import pkg_resources
   assert pkg_resources.get_distribution('pip').version == '1.2.0'
   

   注意: pkg_resources API が認識するのはインストール環境のメタデータだけであり、これは必ずしも現在インポートされているコードとは限らない。

6. sample/__init__.py で __version__ の値を設定し、 setup.py で sample をインポートする。

   import sample
   setup(
       ...
       version=sample.__version__
       ...
   )
   

   この手法はよく使われているが、 sample/__init__.py が install_requires 依存関係からパッケージをインポートしていると失敗しうる。 setup.py の実行時点では、その依存関係はまだインストールされていない可能性が高いからだ。

7. コードではなくバージョン管理システム (Git, Mercurial など)のタグにバージョン番号を保管し、 setuptools_scm を使って自動抽出する。

install_requires vs Requirements files

Page Status:Complete Last Reviewed:2015-09-08

install_requires

install_requires は setuptools setup.py のキーワードで、プロジェクトが正しく動くのに 最低限 必要なものを指定するのに使う。pip がプロジェクトをインストールする際、これに従って依存関係がインストールされる。

例えば、プロジェクトが A と B を必要とするなら、 install_requires はこのようになる:

install_requires=[
   'A',
   'B'
]

加えて、バージョンの下限と上限があればそれを示すのがベストプラクティスだ。

例えば、プロジェクトが最低でも ‘A’ の v1, および ‘B’ の v2 を必要とするとわかっているなら、このようにする:

install_requires=[
   'A>=1',
   'B>=2'
]

A が semantic versioning を使っており、’A’ の v2 が互換性を破っていることもわかっているなら、v2 を許可しないのは理にかなっている:

install_requires=[
   'A>=1,<2',
   'B>=2'
]

install_requires を使って依存関係を特定バージョンに固定したり、サブ依存関係(依存関係のさらに依存関係)を指定するのはベストプラクティスとはいえない。これは制約が厳しすぎるし、ユーザが依存関係をアップグレードするのを妨げる。

最後に、 install_requires は「抽象」requirements のリストであることを理解するのが重要だ。つまり、名前とバージョンに関する制約を記述するだけで、その依存関係がどの場所(インデックスやソース)から満たされるかは指定しないということだ。その場所(「具体化」)はインストール時に pip オプションを使って決定される。

Requirements files

Requirements Files は、最も簡単に説明すると、単に pip install への引数リストをファイルに格納したものだ。

install_requires はプロジェクト単独の依存関係を定義するが、 Requirements Files はしばしば完全な Python 環境の要件を定義するのに使われる。

install_requires の要件は最小限だが、requirements files は完全な環境の repeatable installations を実現するために固定されたバージョンの完全なリストを含むことがしばしばある。

install_requires の要件は「抽象」(つまり、特定のインデックスに関連付けられていない)だが、requirements files はしばしば --index-url や --find-links のような pip オプションを含んでおり、要件を「具体化」(特定のインデックスやパッケージディレクトリに関連付け)している。 [1]

install_requires メタデータは pip がインストール中に自動解析するが、requirements files はそうではない。requirements files が使われるのは、ユーザが pip install -r でインストールするときだけだ。

---

[1]	「抽象」「具体」要件に関する詳細は、 https://caremad.io/2013/07/setup-vs-requirement/ を見よ。

pip vs easy_install

Page Status:Complete Last Reviewed:2015-09-08

easy_install は 2004 年に setuptools の一部としてリリースされた。当時注目を集めたのは、 PyPI から requirement specifiers を用いて パッケージ をインストールし、依存関係も自動でインストールできたことだ。

pip は 2008 年に easy_install の代替としてリリースされたが、やはり大部分は setuptools コンポーネントの上に構築されている。当時注目を集めたのは、パッケージのインストールに Eggs を 使わず (単に sdists から「フラットな」パッケージとしてインストール)、Requirements Files の考えを導入することでユーザが環境を容易に複製できるようにしたことだ。

現時点での pip と easy_install の重要な違いを示す:

	pip	easy_install
Wheels からのインストール	Yes	No
パッケージのアンインストール	Yes (pip uninstall)	No
依存関係のオーバーライド	Yes (Requirements Files)	No
インストールされたパッケージの一覧	Yes (pip list and pip freeze)	No
PEP 438 サポート	Yes	No
インストール形式	egg-info メタデータを用いる「フラットな」パッケージ	カプセル化された Egg 形式
sys.path の変更	No	Yes
Eggs からのインストール	No	Yes
pylauncher サポート	No	Yes [1]
Multi-version Installs	No	Yes
インストール時にスクリプトを除外	No	Yes

---

[1]	https://setuptools.readthedocs.io/en/latest/easy_install.html#natural-script-launcher

Wheel vs Egg

Page Status:Complete Last Reviewed:2015-09-10

Wheel と Egg はともに、ビルドやコンパイルなしでインストールを行うユースケースをサポートするパッケージ形式だ。これらによってビルドやコンパイルに伴うテストや開発ワークフローのコストが削減される。

Egg 形式は setuptools が 2004 年に導入した。一方 Wheel 形式は PEP 427 が 2012 年に導入した。

現在は Wheel が Python 用の ビルド済み または バイナリ パッケージ方式の標準と考えられている。

Wheel と Egg の重要な違いを示す:

• Wheel には 公式 PEP があるが、Egg にはない。
• Wheel は distribution 形式、つまりパッケージング形式だ。[1] Egg は distribution 形式である一方ランタイムインストール形式でもあり (zip 形式のままの場合)、インポートができるように設計されている。
• Wheel アーカイブは .pyc ファイルを含まない。よって、 distribution が Python ファイルのみを含み(一切のコンパイル済み拡張を含まず)、Python 2 および 3 と互換性があるなら、wheel を “universal” にできる(sdist のように)。
• Wheel は PEP 376 準拠 の .dist-info ディレクトリを使う。Egg は .egg-info を使う。
• Wheel には 情報量の多いファイル名規約 がある。 Wheel アーカイブ名を見るだけで、互換性のある Python バージョンおよび実装、ABI, システムアーキテクチャがわかる。
• Wheel はバージョン管理されている。全ての wheel ファイルは、 wheel 仕様およびパッケージングを行った実装のバージョンを含む。
• Wheel は内部的に sysconfig path type を使って構成されているため、他の形式に変換するのが容易だ。

---

[1]	ときどき wheel がインポート可能なランタイム形式として使われることがあるが、現在これは公式にはサポートされない 。

科学パッケージのインストール

Page Status:Incomplete Last Reviewed:2014-07-24

科学ソフトウェアは他のほとんどより複雑な依存関係を持つ傾向がある。それにはしばしば複数のビルドオプションがあり、各種ハードウェアを利用したり、様々な外部ソフトウェアと連携できるようになっている。

特に、 NumPy は scientific Python stack のほとんどのソフトウェアの基礎をなしているが、これは様々な FORTRAN ライブラリと連携し、現代の CPU で利用できる様々なレベルのベクトル化命令を利用するように設定できる。

残念ながら、2013 年 12 月現在、NumPy のビルド/配布モデルのために、標準ツールはビルド済み NumPy バイナリの配布にはあまり適していない。ほとんどのユーザはどのバージョンが必要なのか知らないし、今のところ wheel 形式はインストール中にユーザがバージョンを指定できるようにはなっていないからだ。

この状況はいずれ解決されるはずだ。標準ツールが将来 NumPy のビルド/配布プロセスの複雑さを完全にサポートできるようになるか、あるいは NumPy 開発者が「許容できる公約数」ビルドを選び、それを PyPI 上で wheel として公開することで。

しかし当面は、いくつかの代替策によって科学 Python ライブラリ(またはソースからインストールするためのコンパイル環境を要求し、PyPI でビルド済み wheel を公開していないライブラリ)を入手できる。

ソースからのビルド

自分でソースからビルドするのは難しい。それは NumPy (と、それに依存する多くのプロジェクト)を wheel として配布するのと同様に複雑だからだ。しかし、C および FORTRAN コンパイラ/リンカとの格闘に時間を費やすのを厭わないなら、ソースからのビルドは常に選択肢としてある。

Linux 配布パッケージ

Linux ユーザの場合、システムパッケージマネージャが様々な科学ソフトウェア(NumPy および scientific Python stack の他の部分を含む)のコンパイル済みバージョンを用意していることがよくある。

それらのバージョンは数ヶ月単位で古いかもしれないが、それが受け入れられるならよい選択肢だろう(仮想環境を使う場合、システムの Python にインストールされたパッケージへのアクセスを許可しなければならないことに注意)。

Windows インストーラ

現在 wheel を公開していない(できない) Python プロジェクトの多くは、 PyPI またはプロジェクトのダウンロードページで少なくとも Windows インストーラは公開している。これらのインストーラを使うことで、ユーザはローカルで拡張をビルドするための環境構築をせずに済む。

これらのインストーラで提供される拡張は、python.org で公開されている CPython Windows インストーラと互換性があるのが普通だ。

自前で Windows インストーラを提供しない(一部はしているが)プロジェクトについては、カリフォルニア大学の Christoph Gohlke が Windows インス トーラコレクション を提供している。Windows 上の Python ユーザの多くがこれらのビルド済みバージョンが役に立ったと報告している。

Linux システムパッケージ同様、Windows インストーラはシステムの Python 環境のみにインストールを行う - 仮想環境へのインストールはサポートしない。この制限を回避する一般的な方法は、仮想環境使用時にシステムの Python にインストールされたパッケージへのアクセスを許可することだ。

wheel プロジェクトは、Windows の bdist_wininst インストーラを wheel に変換する wheel convert サブコマンドも用意している。

Mac OS X インストーラ/パッケージマネージャ

Windows における状況と同様、多くのプロジェクト (NumPy 含む)が Mac OS X 用インストーラを公開しており、それは python.org で公開されている Mac OS X 用 CPython バイナリと互換性がある。

Mac OS X ユーザは MacPorts のような Linux スタイルのパッケージマネージャも利用できる。SciPy サイトには、MacPorts による scientific Python stack のインストールに関する詳細がある。

SciPy 配布物

SciPy サイトには、完全な SciPy スタックを利用と更新が容易な形式でエンドユーザに提供する いくつかの配布物 のリストがある。

これらの配布物のいくつかは標準の pip, virtualenv ベースのツールチェインと互換性がないかもしれない。

Spack

Spack は複数のバージョン、構成、プラットフォーム、およびコンパイラをサポートする設計の柔軟なパッケージマネージャだ。大規模スーパーコンピューティングセンターや科学アプリケーションチームはしばしばソフトウェアを多くの異なった方法でビルドしなければならないが、これはそうした要求をサポートできるように作られた。Spack は Python に限定されない; C, C++, Fortran, R その他の言語向けのパッケージをインストールできる。それは非破壊的だ; あるパッケージの新バージョンをインストールしても、既存のインストール環境は壊れない。よって同じシステム上で多くの構成を共存させられる。

Spack は単純だが強力な構文を提供しており、ユーザはバージョンや構成を簡潔に指定できる。パッケージファイルは pure Python で書かれており、またテンプレート化されているため、単一パッケージファイルでコンパイラ、依存関係の実装(MPI など)、バージョン、およびビルドオプションを簡単に交換できる。Spack は モジュール ファイルも生成し、パッケージがユーザ環境でロード/アンロードできるようにする。

Conda クロスプラットフォームパッケージマネージャ

Anaconda は Continuum Analytics が公開している Python ディストリビューションだ。これはビッグデータと科学的用途のためのオープンソースパッケージの安定したコレクションだ。Anaconda 2.2 には約 100 のパッケージがインストールされており、また Anaconda リポジトリから合計 279 パッケージがインストールできる。

conda は Anaconda に含まれるオープンソース(BSD ライセンス)のパッケージ管理および環境管理システムだ。これにより、ユーザは複数バージョンのバイナリソフトウェアパッケージとその依存関係をインストールし、それらを簡単に切り替えられる。これは Windows, OSX, Linux で動くクロスプラットフォームツールだ。Conda はどんなものでもパッケージ化して配布でき、それは Python パッケージに限らない。これはネイティブ仮想環境を完全にサポートしている。Conda は環境を first-class として扱うため、C ライブラリに対してさえ独立した環境を容易に作れる。これは Python で書かれてはいるが、Python を意識することはない。Conda は Python 自身をもパッケージとして扱うため、 conda update python が可能だ。これは Python パッケージの管理しか行わない pip とは対照的だ。Conda は Anaconda と Miniconda (Python と conda のみを含む簡易版)で利用できる。

アプリケーションのデプロイ

Page Status:Incomplete Last Reviewed:2014-11-11

Overview

Supporting multiple hardware platforms

FIXME

Meaning: x86, x64, ARM, others?

For Python-only distributions, it *should* be straightforward to deploy on all
platforms where Python can run.

For distributions with binary extensions, deployment is major headache.  Not only
must the extensions be built on all the combinations of operating system and
hardware platform, but they must also be tested, preferably on continuous
integration platforms.  The issues are similar to the "multiple python
versions" section above, not sure whether this should be a separate section.
Even on Windows x64, both the 32 bit and 64 bit versions of Python enjoy
significant usage.

OS Packaging & Installers

FIXME

- Building rpm/debs for projects
- Building rpms/debs for whole virtualenvs
- Building Mac OS X installers for Python projects
- Building Android APKs with Kivy+P4A or P4A & Buildozer

Windows

FIXME

- Building Windows installers for Python projects

Pynsist

Pynsist は、Python プログラムに Python インタプリタをバンドルして NSIS ベースの単一インストーラを作るツールだ。ほとんどの場合、ユーザは Python インタプリタのバージョン選択とプログラムの依存関係の宣言を行うだけでパッケージングができる。このツールは指定された Windows 用 Python インタプリタをダウンロードし、全ての依存関係と一緒に単一の Windows-executable インストーラへパッケージする。

できあがったインストーラはユーザのシステムに Python インタプリタをインストールするか、または更新する。このインタプリタはパッケージされたプログラムとは独立して使える。プログラム自体はインストーラがスタートメニューに配置するショートカットから起動できる。プログラムをアンインストールしても、ユーザの Python 環境はそのまま残る。

Pynsist の大きな利点は、Linux 上で Windows パッケージが作れることだ。 ドキュメント に各種プログラム(コンソール、GUI) の例がいくつかある。このツールは MIT ライセンスでリリースされている。

Application Bundles

FIXME

- py2exe/py2app/PEX
- wheels kinda/sorta

Configuration Management

FIXME

puppet
salt
chef
ansible
fabric

Multi-version Installs

Page Status:Complete Last Reviewed:2014-12-27

easy_install allows simultaneous installation of different versions of the same project into a single environment shared by multiple programs which must require the appropriate version of the project at run time (using pkg_resources).

For many use cases, virtual environments address this need without the complication of the require directive. However, the advantage of parallel installations within the same environment is that it works for an environment shared by multiple applications, such as the system Python in a Linux distribution.

The major limitation of pkg_resources based parallel installation is that as soon as you import pkg_resources it locks in the default version of everything which is already available on sys.path. This can cause problems, since setuptools created command line scripts use pkg_resources to find the entry point to execute. This means that, for example, you can’t use require tests invoked through nose or a WSGI application invoked through gunicorn if your application needs a non-default version of anything that is available on the standard sys.path - the script wrapper for the main application will lock in the version that is available by default, so the subsequent require call in your own code fails with a spurious version conflict.

This can be worked around by setting all dependencies in __main__.__requires__ before importing pkg_resources for the first time, but that approach does mean that standard command line invocations of the affected tools can’t be used - it’s necessary to write a custom wrapper script or use python -c '<commmand>' to invoke the application’s main entry point directly.

Refer to the pkg_resources documentation for more details.

Appveyor による Windows サポート

Page Status:Incomplete Last Reviewed:2015-12-03

このセクションでは、無料の Appveyor 継続的インテグレーションサービスを使ってプロジェクトの Windows サポートを提供する方法を説明する。これには、Windows 上でのコードのテスト、およびプロジェクトが C 拡張を使う場合の Windows 用バイナリのビルドが含まれる。

背景

多くのプロジェクトはデフォルトでは Unix 上で開発されており、Windows サポートの提供は難しいことがある。というのは、Windows テスト環境を適切に構築するのは面倒だし、ソフトウェアライセンスの購入が必要かもしれないからだ。

Appveyor サービスは継続的インテグレーションサービスで、より有名な Travis サービス(Github でホストされたプロジェクトがよくテストに使っている)によく似ている。しかし Travis と異なり、Appveyor のビルドワーカーは Windows ホストであり、Python 拡張のビルドに必要なコンパイラがインストール済みだ。

Windows ユーザは C コンパイラを持っていないのが普通なので、彼らが C 拡張を使うプロジェクトを pip install <dist> でインストールするには、プロジェクト側で配布する PyPI 上のバイナリ wheel に頼ることになる。 Appveyor をビルドサービスとして使うと(テストには使わなくても)、プロジェクトが専用の Windows 環境なしで Windows バイナリを提供できるようになる。

セットアップ

プロジェクトで Appveyor を使って Windows 用 wheels をビルドするには、サービスのアカウントを作る必要がある。アカウント取得の手順は Appveyor ドキュメント にある。オープンソースプロジェクトなら、無料版アカウントで全く問題ない。

Appveyor には Github および Bitbucket との統合機能があるので、プロジェクトがこれら 2 つのサービスのいずれかでホストされているなら、 Appveyor との統合は簡単だ。

Appveyor アカウントを取得してプロジェクトを追加すると、Appveyor はコミットのたびにプロジェクトを自動ビルドするようになる。この動作は Travis ユーザにはおなじみのものだろう。

プロジェクトに Appveyor サポートを追加する

Appveyor がプロジェクトをビルドする方法を定義するには、プロジェクトに appveyor.yml ファイルを追加する。このファイルの内容の完全な詳細は Appveyor ドキュメントにある。このガイドでは wheel のビルド設定に必要な部分を詳しく説明する。

Appveyor にはデフォルトで Python 用拡張のビルドに必要な全てのコンパイラツールチェインが含まれている。これらは Python 2.7, 3.5+ および 32-bit 版の 3.3, 3.4 に対してはそのままで使える。しかし 64-bit 版の Python 3.3, 3.4 の場合、少々の追加設定を行って distutils に 64-bit コンパイラの場所を知らせる必要がある (3.5 以降では、使用するバージョンの Visual Studio は追加設定なしで 64-bit コンパイラを含む)。

appveyor.yml

environment:

  matrix:

    # For Python versions available on Appveyor, see
    # http://www.appveyor.com/docs/installed-software#python
    # The list here is complete (excluding Python 2.6, which
    # isn't covered by this document) at the time of writing.

    - PYTHON: "C:\\Python27"
    - PYTHON: "C:\\Python33"
    - PYTHON: "C:\\Python34"
    - PYTHON: "C:\\Python35"
    - PYTHON: "C:\\Python27-x64"
    - PYTHON: "C:\\Python33-x64"
      DISTUTILS_USE_SDK: "1"
    - PYTHON: "C:\\Python34-x64"
      DISTUTILS_USE_SDK: "1"
    - PYTHON: "C:\\Python35-x64"

install:
  # We need wheel installed to build wheels
  - "%PYTHON%\\python.exe -m pip install wheel"

build: off

test_script:
  # Put your test command here.
  # If you don't need to build C extensions on 64-bit Python 3.3 or 3.4,
  # you can remove "build.cmd" from the front of the command, as it's
  # only needed to support those cases.
  # Note that you must use the environment variable %PYTHON% to refer to
  # the interpreter you're using - Appveyor does not do anything special
  # to put the Python evrsion you want to use on PATH.
  - "build.cmd %PYTHON%\\python.exe setup.py test"

after_test:
  # This step builds your wheels.
  # Again, you only need build.cmd if you're building C extensions for
  # 64-bit Python 3.3/3.4. And you need to use %PYTHON% to get the correct
  # interpreter
  - "build.cmd %PYTHON%\\python.exe setup.py bdist_wheel"

artifacts:
  # bdist_wheel puts your built wheel in the dist directory
  - path: dist\*

#on_success:
#  You can use this step to upload your artifacts to a public website.
#  See Appveyor's documentation for more details. Or you can simply
#  access your wheels from the Appveyor "artifacts" tab for your build.

このファイルは ここ からダウンロードできる。

appveyor.yml ファイルはプロジェクトのルートディレクトリに置かねばならない。これは YAML 形式で、いくつかのセクションから成る。

environments セクションは作成される wheels に対する Python バージョンを定義する鍵となるものだ。Appveyor には Python 2.6, 2.7, 3.3, 3.4, 3.5 が(全て 32-bit, 64-bit の両方)インストールされている。サンプルファイルでは、Python 2.6 を除く全ての環境用にビルドするよう指定している。Python 2.6 には pip が付属していないので、インストールがより複雑になる。この文書では 2.6 はサポートしない(まだ Python 2 を使っている Windows ユーザは、普通大した困難なく Python 2.7 へ移行できるので)。

install セクションでは、pip を使ってプロジェクトに必要な追加ソフトウェアをインストールしている。Wheels のビルドに必要なのは wheel だけだが、プロジェクトでこのコードをカスタマイズしたい場合もあるかもしれない(例えば、 Cython のようなビルドパッケージや、 tox のようなテストツールを追加でインストールするとき)。

build セクションでは単にビルドをオフにしている - Python にビルドステップは必要ない (C# のような言語と違って)。

プロジェクトごとに調整する必要がある主なセクションは test_script と after_test だ。

test_script セクションでプロジェクトのテストを実行する。build.cmd スクリプトが setup.py test でテストスイートを実行する。Wheels のビルドのみに興味があり、Windows 上でテストを行うつもりがないなら、このセクションを echo Skipped Tests のようなダミーコマンドで置き換えてもよい。テストツールとして nose や py.test などを使いたいこともあるかもしれない。あるいは tox のようなテストドライバを使いたいこともあるかもしれない - ただし tox を使う場合、以下で説明するようにいくつか追加の設定変更を考慮する必要があるだろう。

after_test はテスト完了後に一回だけ実行される。つまりここで wheels がビルドされる。プロジェクトが推奨ツール(特に setuptools) を使っていれば、 setup.py bdist_wheel コマンドで wheels がビルドされる。

Wheels はテストが成功した場合のみビルドされることに注意。Windows 上ではテストが失敗するとわかっているなら、上記のようにテストをスキップできる。

サポートスクリプト

appveyor.yml ファイルは一つのサポートスクリプトに依存している。このスクリプトは 64-bit Python 3.3, 3.4 用に SDK コンパイラを使うための環境構築を行う。プロジェクトがコンパイラを必要としないか、64-bit Windows 上の Python 3.3, 3.4 をサポートしないなら、必要なのは appveyor.yml ファイルだけだ。

build.cmd は Windows バッチスクリプトで、選択した Python バージョンに対して適切なコンパイラを使う環境で単一のコマンドを実行する。必要なのは環境変数 DISTUTILS_USE_SDK に値 1 を設定することだけで、残りはこのスクリプトが行う。これは 64-bit Python 3.3, 3.4 に必要な SDK を設定するという意味なので、他の Python ビルドに対してはこの環境変数を設定しないこと。

上記のバッチファイルをダウンロードしてプロジェクトにそのまま含めてよい。

ビルドされた wheels へのアクセス

ビルドが完了すると、プロジェクトの Appveyor コントロールパネルからビルドされた wheels が取得できる。各ビルドのビルドステータスページを順に辿ることで見つけられる。ビルド出力の上部にリンクが並んでおり、 “Artifacts” というものがある。そのページには当該 Python バージョン/ アーキテクチャ用の wheels へのリンク一覧がある。これらの wheels をダウンロードし、リリースプロセスの一環として PyPI へアップロードできる。

Additional Notes

Tox を用いたテスト

多くのプロジェクトがテストの実行に Tox ツールを使っている。これはプロジェクトが配布するのと全く同じファイルを使う隔離環境でテストが実行されることを保証する。

Appveyor で tox を使うには、いくつか追加の考慮事項がある(実際のところ、これらは Appveyor 固有の問題ではなく、他の CI システムにも影響しうる)。

1. デフォルトでは、 tox は環境変数のうち選択されたサブセットのみをテストプロセスに渡す。 distutils は環境変数を使ってコンパイラを制御しているので、この「テスト隔離」機能により誤ったコンパイラがデフォルトで使われてしまうことがある。

   tox が必要な環境変数をサブプロセスに渡すようにするには、 tox 構成オプション passenv を設定し、サブプロセスに渡すべき追加の環境変数リストを与える必要がある。SDK コンパイラを使う場合、以下を設定する:

   • DISTUTILS_USE_SDK
   • MSSdk
   • INCLUDE
   • LIB

   passenv オプションは tox.ini で設定できるが、プロジェクトファイル群に Windows 固有設定を加えるのを避けたければ、 TOX_TESTENV_PASSENV 環境変数を設定してもよい。先に示した build.cmd スクリプトは DISTUTILS_USE_SDK がセットされていればデフォルトでこれを行う。

2. 対話的に使う場合、 tox は複数の環境(しばしば複数の Python バージョンを意味する)に対してテストを実行できる。この機能は Travis や Appveyor のような CI 環境ではさほど有用ではない。なぜなら全テストは個別の構成に対して隔離環境で実行されるからだ。結果として、プロジェクトはしばしば -e ENVNAME 引数を tox に与えて使う環境を指定することになる(ほとんどの Python バージョンに対してはデフォルトの環境があるので)。

   しかし、この方法は Appveyor のような Windows CI システムではうまく いかない 。例えば Python 3.4 の環境が 2 つ(32-bit と 64-bit) あるが、 tox には py34 環境 1 つしかない、といった場合だ。

   従って、 tox を使ってテストを実行するには、プロジェクトはおそらく tox 内ではデフォルトの py 環境を使うべきだ。この環境は tox の実行に使われたのと同じ Python インタプリタを使う。これにより、Appveyor がテストを実行する際、設定されたインタプリタで実行されることが保証される。

   py 環境での実行をサポートするために、複雑な tox 構成を持つプロジェクトは tox.ini ファイルを修正しなければならない可能性がある。しかしこれはこの文書の範囲外だ。

Wheels の自動アップロード

Appveyor が自動で wheels をアップロードするように要求できる。 appveyor.yml には deployment ステップがあり、例えばビルド結果を FTP サイトや Amazon S3 インスタンスにコピーしたりできる。これを行う方法は Appveyor ガイドに含まれている。

代わりに、ビルドに twine upload ステップを追加することもできる。先に示した appveyor.yml ではこれを行っていない。なぜならコミットのたびに新しい wheels をアップロードするのが望ましいかどうかはわからないからだ(プロジェクトによってはそうしたいと思うかもしれないが)。

外部依存関係

先に示したスクリプトは、ビルドの際にサードパーティの外部ライブラリに依存しない任意の distribution をビルドできる。

appveyor.yml 構成(普通は “install” セクション内)に distribution が必要とする外部ライブラリをダウンロード/ビルドするステップを加えることができる。また、必要ならこれらのライブラリの場所をコンパイラに知らせるためのビルド用構成を追加することもできる。しかし、このレベルの構成はこの文書の範囲外だ。

サポートスクリプト

参考までに、SDK 設定用サポートスクリプトを掲載する:

code/build.cmd

@echo off
:: To build extensions for 64 bit Python 3, we need to configure environment
:: variables to use the MSVC 2010 C++ compilers from GRMSDKX_EN_DVD.iso of:
:: MS Windows SDK for Windows 7 and .NET Framework 4
::
:: More details at:
:: https://github.com/cython/cython/wiki/64BitCythonExtensionsOnWindows

IF "%DISTUTILS_USE_SDK%"=="1" (
    ECHO Configuring environment to build with MSVC on a 64bit architecture
    ECHO Using Windows SDK 7.1
    "C:\Program Files\Microsoft SDKs\Windows\v7.1\Setup\WindowsSdkVer.exe" -q -version:v7.1
    CALL "C:\Program Files\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.cmd" /x64 /release
    SET MSSdk=1
    REM Need the following to allow tox to see the SDK compiler
    SET TOX_TESTENV_PASSENV=DISTUTILS_USE_SDK MSSdk INCLUDE LIB
) ELSE (
    ECHO Using default MSVC build environment
)

CALL %*

Hosting your Own Simple Repository

Page Status:Complete Last Reviewed:2015-09-24

If you wish to host your own simple repository [1], you can either use a software package like devpi or you can use simply create the proper directory structure and use any web server that can serve static files and generate an autoindex.

In either case, since you’ll be hosting a repository that is likely not in your user’s default repositories, you should instruct them in your project’s description to configure their installer appropriately. For example with pip:

pip install --extra-index-url https://python.example.com/ foobar

In addition, it is highly recommended that you serve your repository with valid HTTPS. At this time, the security of your user’s installations depends on all repositories using a valid HTTPS setup.

“Manual” Repository

The directory layout is fairly simple, within a root directory you need to create a directory for each project. This directory should be the normalized name (as defined by PEP 503) of the project. Within each of these directories simply place each of the downloadable files. If you have the projects “Foo” (with the versions 1.0 and 2.0) and “bar” (with the version 0.1) You should end up with a structure that looks like:

.
├── bar
│   └── bar-0.1.tar.gz
└── foo
    ├── Foo-1.0.tar.gz
    └── Foo-2.0.tar.gz

Once you have this layout, simply configure your webserver to serve the root directory with autoindex enabled. For an example using the built in Web server in Twisted, you would simply run twistd -n web --path . and then instruct users to add the URL to their installer’s configuration.

---

[1]	For complete documentation of the simple repository protocol, see PEP 503.

PyPA 仕様

Page Status:Complete Last Reviewed:2016-01-22

Python Packaging Authority が管理している現在アクティブな相互運用性に関する仕様のリストを示す。

Package distribution metadata

Core metadata

現在の core metadata ファイルフォーマット バージョン 1.2 の仕様は PEP 345 にある。

しかし、当該 PEP の version specifiers および environment markers セクションについては他の PEP が優先される(後述)。さらに、メタデータファイルは以下の追加フィールドを含んでもよい:

Provides-Extra (複数可)

オプション機能の名前を含む文字列。有効な Python 識別子でなければならない。オプション機能が要求されたかどうかによって条件付き依存関係を記述するのに使える。

例:

Provides-Extra: pdf
Requires-Dist: reportlab; extra == 'pdf'

角括弧で囲むことでオプションの依存関係を要求でき、カンマで区切ることで複数指定することもできる。要求された各機能について要件が評価され、 distribution の要件セットに追加される。

Example:

Requires-Dist: beaglevote[pdf]
Requires-Dist: libexample[test, doc]

機能名 test と doc は予約されており、それぞれ自動テストとドキュメント生成が必要であるとマークするのに使われる。

Requires-Dist: で参照されない Provides-Extra: を指定するのは合法だ。

Version Specifiers

バージョン番号の要件、およびバージョン間の比較指定のセマンティクスは PEP 440 で定義されている。

この PEP の version specifiers セクションは PEP 345 の version specifiers セクションに優先する。

Dependency Specifiers

他のコンポーネントへの依存関係を宣言するための dependency specifier フォーマットは PEP 508 で定義されている。

この PEP の environment markers セクションは PEP 345 の environment markers セクションに優先する。

Source Distribution Format

Source distribution 形式 (sdist) には今のところ正式な定義がない。代わりに、その形式は setup.py sdist コマンドを実行した際の標準ライブラリの distutils モジュールの動作によって暗黙に定義される。

Binary Distribution Format

Binary distribution format (wheel) は PEP 427 で定義されている。

Platform Compatibility Tags

Wheel distribution で使われる platform compatibility tagging model は PEP 425 で定義されている。

当該 PEP で定義されるスキームは Linux (一般には *nix) 用 wheel のパブリックな配布のためには不十分なので、PEP 513 が作られ、 manylinux1 タグが定義された。

インストール済み distribution の記録

インストール済みパッケージとその内容を記録するためのフォーマットは PEP 376 で定義されている。

デフォルトのパッケージングツールチェインは、今のところ当該 PEP のうち dist-info ディレクトリと RECORD ファイル形式のみを実装している。

Package index interfaces

Simple repository API

インデックスサーバにパッケージバージョンを問い合わせ、パッケージを取得するためのインターフェースは PEP 503 で定義されている。

プロジェクト概要

Page Status:Complete Last Reviewed:2016-06-24

Python インストールおよびパッケージングに関する最も重要なプロジェクト群の概要とリンクを示す。

PyPA 内のプロジェクト

bandersnatch

Mailing list [2] | Issues | Bitbucket | PyPI

bandersnatch は PyPI ミラーリングクライアントだ。PyPI コンテンツを完全かつ効率的にミラーリングするよう設計されている。

distlib

Docs | Mailing list [2] | Issues | Bitbucket | PyPI

distlib は Python ソフトウェアのパッケージングと配布に関する低レベル機能を実装するライブラリだ。これは distutils2 プロジェクトの一部からなる。distutils2 は Python 3.3 標準ライブラリで packaging としてリリースされる予定だったが、Python 3.3 がベータテストに入る直前に削除された。

packaging

Dev list | Issues | Github | PyPI | User irc:#pypa | Dev irc:#pypa-dev

pip と setuptools が利用する Python パッケージング用のコアユーティリティ。

pip

Docs | User list [1] | Dev list | Issues | Github | PyPI | User irc:#pypa | Dev irc:#pypa-dev

Python パッケージをインストールするツール。

Python Packaging User Guide

Docs | Mailing list | Issues | Github | User irc:#pypa | Dev irc:#pypa-dev

このガイド!

setuptools

Docs | User list [2] | Dev list | Issues | GitHub | PyPI | User irc:#pypa | Dev irc:#pypa-dev

setuptools (easy_install を含む)は Python distutils の強化版で、 Python distributions, 特に他のパッケージに依存するものをより簡単にビルド/配布できるようにする。

distribute は setuptools の fork だったが、v0.7 で setuptools に再度マージされた。これにより、setuptools が Python パッケージングの第一の選択肢となった。

twine

Mailing list [2] | Issues | Github | PyPI

Twine は PyPI とやりとりするユーティリティで、 setup.py upload の安全な代替となる。

virtualenv

Docs | User list | Dev list | Issues | Github | PyPI | User irc:#pypa | Dev irc:#pypa-dev

隔離された Python 環境を作るツール。

Warehouse

Docs | Mailing list [2] | Issues | Github | Dev irc:#pypa-dev

新しい未リリースの PyPI アプリケーション。 https://warehouse.python.org/ でプレビューできる。

wheel

Docs | Mailing list [2] | Issues | Bitbucket | PyPI | User irc:#pypa | Dev irc:#pypa-dev

主に、wheel プロジェクトは wheel distributions を作るための setuptools bdist_wheel 拡張を提供する。加えて、wheel の作成とインストールを行う独自のコマンドラインユーティリティも提供する。

PyPA 外のプロジェクト

bento

Docs | Mailing list | Issues | Github | PyPI

Bento は Python ソフトウェアのためのパッケージングソリューションで、 distutils, setuptools, distribute などの代替を目指している。Bento の哲学は再現性、拡張性、簡潔さだ(この順で)。

buildout

Docs | Mailing list [2] | Issues | PyPI | irc:#buildout

buildout は Python ベースのビルドシステムで、複数のパーツ(非 Python ベースでもよい)からアプリケーションを作成、アセンブル、デプロイできる。buildout 構成を作り、後で同じソフトウェアを再現できるようにする。

conda

Docs

Conda は Anaconda Python 環境用のパッケージ管理ツールだ。Anaconda Python は Continuum Analytics によるディストリビューションで、科学コミュニティ(特にバイナリ拡張のインストールが難しくなりがちな Windows環境)向けに特化している。

Conda は pip, virtualenv, wheel とは完全に別のツールだが、これらを組み合わせたような機能(パッケージ管理、仮想環境管理、バイナリ拡張のデプロイ)を提供する。

Conda はパッケージを PyPI からインストールせず、Continuum 公式リポジトリ, anaconda.org (ユーザが作成した conda パッケージの置き場), またはローカル(例:イントラネット)パッケージサーバからのみインストールを行う。ただし、pip をインストールすることもでき、pip は conda とは独立して PyPI 由来の distributions を管理する。

devpi

Docs | Mailing List | Issues | PyPI

devpi には強力な PyPI 互換サーバと PyPI プロキシキャッシュがあり、 Python でパッケージング、テスト、リリース活動を行うためのコマンドラインツールが付属する。

Hashdist

Docs | Github

Hashdist は non-root ソフトウェアディストリビューションを構築するライブラリだ。Hashdist は「Debian の技術がうまくいかない場合に選ぶ Debian」であろうとしている。Pythonista にとっての Hashdist のベストな見方は、virtualenv と buildout のより強力なハイブリッドかもしれない。

pex

Docs | Github | PyPI

pex は .pex (Python EXecutable) を生成するライブラリおよびツールであり、同時に virtualenv の精神に基づくスタンドアロン Python 環境でもある。 .pex ファイルは単なる zip ファイルで、 #!/usr/bin/env python および特別な __main__.py を持ち、Python アプリケーションのデプロイが cp と同じくらいシンプルにできるよう注意深く構築されている。

Spack

Docs | Github | Paper | Slides

柔軟なパッケージマネージャで、複数のバージョン、構成、プラットフォーム、コンパイラをサポートするよう設計されている。Spack は homebrew に似ているが、パッケージは Python で書かれており、またパラメータ化によってコンパイラ、ライブラリのバージョン、ビルドオプションなどを容易に交換できるようになっている。パッケージのバージョンがどれだけ多くても、それら全てが同じシステム上で共存できる。Spack はクラスタやスーパーコンピュータ上で高パフォーマンス科学アプリケーションを迅速に構築するために設計された。

Spack は PyPI には(まだ)入っていないが、インストールは不要で、github からクローンしてすぐ使える。

標準ライブラリプロジェクト

ensurepip

Docs | Issues

既存の Python 環境または仮想環境で pip のブートストラッピングをサポートする Python 標準ライブラリパッケージ。ほとんどの場合、エンドユーザがこのモジュールを使うことはなく、Python ディストリビューションのビルド中に使われる。

distutils

Docs | User list [2] | Issues | User irc:#pypa | Dev irc:#pypa-dev

distributions の作成とインストールをサポートする Python 標準ライブラリパッケージ。setuptools が distutils より強力な機能を提供しているので、distutils を単独で使うよりはそちらを使う方がはるかに一般的だ。

venv

Docs | Issues

仮想環境 を作るための Python 標準ライブラリパッケージ (Python 3.3 以降)。詳しくは、仮想環境の作成 のセクションを見よ。

---

[1]	pip を作ったのは virtualenv と同じ開発者で、早い段階で virtualenv メーリングリストを使うことにした。以来ずっとその状態が続いている。

[2]	(1, 2, 3, 4, 5, 6, 7, 8) 複数のプロジェクトが distutils-sig メーリングリストをユーザ用として再利用している。

用語集

Page Status:Complete Last Reviewed:2015-09-08

Binary Distribution

Built Distribution のうち、コンパイル済み拡張を含むもの。

Built Distribution

Distribution 形式のうち、中身のファイルとメタデータをターゲットシステムの正しい場所へ移動するだけでインストールができるもの。Wheel はそのような形式だが、distutils の Source Distribution はそうではない。後者はインストール前にビルドステップを要するからだ。この形式は Python ファイルがプリコンパイルを要するというわけではない(Wheel は意図的にコンパイル済み Python ファイルを含めていない)。

Distribution Package

バージョン管理されたアーカイブファイルで、Python パッ ケージ 、モジュール 、およびその他のリソースファイルを含む。Release の配布に使われる。エンドユーザがインターネットからダウンロードしてインストールするのはこのアーカイブファイルだ。

Distribution package は単に「パッケージ」とか “distribution” と呼ばれる方が一般的だが、このガイドでは明快さのためにこの長い用語を使うこともある。これは Import Package (これもよく「パッケージ」と呼ばれる)や、その他の類のディストリビューション(例えば、Linux ディストリビューションや Python 言語ディストリビューション。これらにしても単に「ディストリビューション」と呼ばれがち)との混同を避けるためだ。

Egg

setuptools が導入した Built Distribution 形式で、Wheel に取って代わられた。詳しくは、 The Internal Structure of Python Eggs および Python Eggs を見よ。

Extension Module

Python 実装における低レベル言語で書かれた モジュール: Python の場合 C/C++, Jython の場合 Java。通常、単一の動的ロード可能なコンパイル済みファイル内にある(例えば、Unix の Python拡張なら共有オブジェクト (.so) ファイル、Windows の Python 拡張なら DLL (拡張子 .pyd), Jython 拡張なら Java クラスファイル)。

Known Good Set (KGS)

互換性を持つようにバージョン指定された distribution のセット。通常、テストスイートが全てのテストを通ってはじめて特定のパッケージセットが known good set と宣言される。この用語は、複数の独立した distribution からなるフレームワークやツールキットでよく使われる。

Import Package

他のモジュール、または再帰的に他のパッケージを含む Python モジュール。

Import package は単に「パッケージ」と呼ばれる方が一般的だが、このガイドでは明快さのためにこの長い用語を使うことがある。これは Distribution Package (これもよく「パッケージ」と呼ばれる)との混同を避けるためだ。

Module

Python におけるコード再利用の基本単位。Pure Module, Extension Module のいずれか。

Package Index

Distributions のリポジトリで、パッケージ の発見と利用を自動化する Web インターフェースを備えている。

Project

ライブラリ、フレームワーク、スクリプト、プラグイン、アプリケーション、データやその他リソースのコレクション、またはそれらの組み合わせ。Distribution へパッケージされる。

ほとんどのプロジェクトは distutils または setuptools を使って Distributions を作るので、現在におけるプロジェクトの実際的な定義は、そのルートディレクトリに setup.py を含むものと言ってもよい。ここで “setup.py” は distutils, setuptools が使うプロジェクト仕様のファイル名だ。

Python プロジェクトの名前は一意でなければならず、この名前が PyPI に登録される。各プロジェクトは一つ以上の リリース を含み、各リリースは一つ以上の distribution を含む。

プロジェクト名はそれを動かす際にインポートされるパッケージ名と同じにするという強い規約がある。しかしこれは必ずしも真ではない。プロジェクト ‘foo’ から distribution をインストールしたとき、それがパッケージ ‘bar’ しか提供しない、ということも可能だ。

Pure Module

Python で書かれ、単一の .py ファイルに格納された モジュール (.pyc / .pyo ファイルに関連付けられているかもしれない)。

Python Packaging Authority (PyPA)

PyPA は Python パッケージングにおける重要プロジェクトの多くを管理する作業グループだ。https://www.pypa.io サイトの管理、 github, bitbucket 上でのプロジェクトのホスト、 pypa-dev メーリングリスト における議論を行っている。

Python Package Index (PyPI)

PyPI は Python コミュニティのデフォルト Package Index だ。全ての Python 開発者が distributions を利用、配布できる。

Release

特定の時点における プロジェクト のスナップショット。バージョン識別子で示される。

あるリリースで複数の Distributions が公開されることもある。例えば、プロジェクトのバージョン 1.0 がリリースされたとき、source distribution 形式と Windows インストーラ distribution 形式が利用できるかもしれない。

Requirement

インストールする パッケージ の指定。PyPA 推奨インストーラである pip は様々な形の指定ができるが、それらは全て “requirement” とみなせる。詳しくは、pip install リファレンスを見よ。

Requirement Specifier

Package Index からパッケージをインストールする際、 pip に渡す指定の形式。EBNF 図は setuptools ドキュメントの pkg_resources.Requirement エントリを見よ。例えば、”foo>=1.3” は requirement specifier であり、ここで “foo” はプロジェクト名、”>=1.3” は Version Specifier である。

Requirements File

pip を使ってインストールできる Requirements のリストを含むファイル。詳しくは、pip ドキュメントの Requirements Files を見よ。

setup.py

distutils と setuptools のためのプロジェクト仕様ファイル。

Source Archive

リリース の生のソースコードを含むアーカイブ。Source Distribution または Built Distribution を作る前段階。

Source Distribution (or “sdist”)

Distribution 形式の一つで、通常 python setup.py sdist で生成される。pip のようなツールでインストールを行ったり、Built Distribution を生成するのに必要なメタデータとソースファイルを含む。

System Package

オペレーティングシステムのネイティブ形式で提供されるパッケージ(例: rpm, dpkg ファイル)。

Version Specifier

Requirement Specifier のバージョン部分。例えば、 “foo>=1.3” の “>=1.3” の部分。PEP 440 には、Python パッケージングが現在サポートする specifiers の 完全な仕様 がある。PEP 440 のサポートは setuptools v8.0 および pip v6.0 で実装された。

Virtual Environment

隔離された Python 環境。この中ではパッケージを特定アプリケーション専用にインストールでき、システムワイドにはインストールされない。詳しくは、仮想環境の作成 セクションを見よ。

Wheel

PEP 427 で導入された Built Distribution 形式で、 Egg 形式の置き換えを意図している。pip は現在 wheel をサポートしている。

Working Set

インポートできる distributions の集合。これらは変数 sys.path 上にある distributions だ。ある working set では、1 プロジェクトに対応する distribution は高々 1 つだ。

サポート

Page Status:Complete Last Reviewed:2015-09-08

特定プロジェクトに関するサポートについては、プロジェクト概要 ページのリンクを見よ。

より一般的な事柄だったり、単によくわからない場合は、 distutils-sig メーリングリストを利用せよ。