Python パッケージガイドライン

このドキュメントでは Python ソフトウェアの PKGBUILD を書くときの決まり事とガイドラインを提供します。

パッケージの命名規則

Python 3 ライブラリモジュールの場合は、python-modulename を使用します。パッケージが Python エコシステムに強く結合されたプログラムを提供する場合にも、接頭辞を使用します (例: pip または tox) 他のアプリケーションの場合は、プログラム名のみを使用します。

ノート: パッケージ名はすべて小文字にする必要があります。

アーキテクチャ

PKGBUILD#arch を参照してください。

C 拡張機能を含む Python パッケージはアーキテクチャに依存します。それ以外の場合は、アーキテクチャに依存しない可能性が高くなります。

[1] を使用してビルドされたパッケージは、setup.py の ext_modules キーワードを使用して C 拡張機能を定義します。

ソース

PyPI Web サイトからリンクされているダウンロード URL には、パッケージを更新する必要があるたびに PyPI Web サイトから取得する必要がある予測不可能なハッシュが含まれています。このため、PKGBUILD での使用には適していません。PyPI が提供 代替の安定したスキーム: PKGBUILD#source source=() 配列次の URL テンプレートを使用する必要があります。

ソースパッケージ

https://files.pythonhosted.org/packages/source/${_name::1}/$_name/$_name-$pkgver.tar.gz

純粋な Python wheel パッケージ

https://files.pythonhosted.org/packages/py2.py3/${_name::1}/$_name/${_name//-/_}-$pkgver-py2.py3-none-any.whl (バイリンガル – Python 2 および Python 3 互換)

https://files.pythonhosted.org/packages/py3/${_name::1}/$_name/${_name//-/_}-$pkgver-py3-none-any.whl (Python 3 のみ)

ディストリビューション名にはダッシュを含めることができますが、wheel ファイル名での表現にはダッシュを含めることができないことに注意してください (ダッシュはアンダースコアに変換されます)

アーキテクチャ固有の wheel パッケージ

source_x86_64=('...') のように、アンダースコアとアーキテクチャ名を追加することで、アーキテクチャ固有の配列を追加できます。また、_py=cp310 を使用して、Python バージョンを繰り返さないようにすることもできます。

https://files.pythonhosted.org/packages/$_py/${_name::1}/$_name/${_name//-/_}-$pkgver-$_py-${_py}m-manylinux1_x86_64.whl

Python パッケージには通常、python- という接頭辞が付けられるため、pkgname の代わりにカスタムの _name 変数が使用されることに注意してください。この変数は一般に次のように定義できます。

_name=${pkgname#python-}

インストール方法

Python パッケージは通常、pip などの言語固有のパッケージ マネージャーを使用してインストールされます。このマネージャーは、オンラインリポジトリ (通常は PyPI) からパッケージを取得します。 Package Index) を作成し、関連ファイルを追跡します。

ただし、PKGBUILD 内から Python パッケージを管理するには、Python パッケージを一時的な場所 $pkgdir/usr/lib/python<Python) に インストール する必要があります。バージョン>/site-packages/$pkgname

standard metadata を使って pyproject.toml でビルドバックエンドを指定している Python パッケージでは、python-build と python-installer を使うのが最も簡単です。

古いパッケージでは、setuptools を使用することを指定できず、手動で呼び出す必要がある setup.py のみが提供される場合があります。

ノート: パッケージのメタデータからの依存関係は、depends 配列で定義する必要があります。定義しないとインストールされません。

標準ベース (PEP 517)

標準ベースのワークフローは簡単です。python-build を使用して wheel をビルドし、python-installer を使用してそれを $pkgdir にインストールします。

ヒント: 上流から提供されたソースのtarballをビルドする際、上流がプロジェクトのバージョン文字列をgitに依存している場合、ホイールをビルドする前に特定のツールに関する環境変数を $pkgver に設定する必要があります:

• python-flit-core, python-hatch-vcsおよびpython-setuptools-scm: SETUPTOOLS_SCM_PRETEND_VERSION
• python-pbr: PBR_VERSION
• python-pdm-backend: PDM_BUILD_SCM_VERSION

標準ベースのワークフローは簡単です。python-build を使用して wheel をビルドし、python-installer を使用してそれを $pkgdir にインストールします:

ノート: python-build と python-installer のほかに、パッケージで使用されている ビルドバックエンド を makedepends に追加する必要があります。リポジトリにあるすべてのビルドバックエンドは、python-build-backend グループのメンバーです。プロジェクトの pyproject.toml に記載された build-system.build-backend を確認して、プロジェクトに適したビルドバックエンドを使用してください。設定されていない場合は、デフォルトで python-setuptools が使用されます。

makedepends=(python-build python-installer python-wheel)

build() {
    cd $_name-$pkgver
    python -m build --wheel --no-isolation
}

package() {
    cd $_name-$pkgver
    python -m installer --destdir="$pkgdir" dist/*.whl
}

場所

• --wheel では、wheel ファイルのみがビルドされ、ソースは配布されません。
• --no-isolation は、システムにインストールされているもの (depends で指定したパッケージを含む) を使用してパッケージがビルドされることを意味します。デフォルトでは、ツールは分離された仮想環境にアクセスし、そこでビルドを実行します。
• --destdir="$pkgdir" により、パッケージファイル内ではなくホストシステムに直接インストールしようとすることが防止されます。これにより、権限エラーが発生します。
• --compile-bytecode=... または --no-compile-bytecode を installer に渡すことができますが、デフォルトは賢明に選択されているため、これは必要ありません。

ノート: build をスキップして .whl ファイルを source 配列に入れることは、ソースからビルドする方法の方が推奨されており、後者が実行不可能な場合(例えば、wheel ソースのみで提供されるパッケージで、ソースからビルドできない場合)にのみ使用すべきです。

ヒント: あなたのパッケージが VCSパッケージ (python-...-git) の場合、git -C "${srcdir}/${pkgname}" clean -dfx コマンドを prepare 関数に含めてください。これにより、他のビルド成果物とともに古くなった wheel が削除され、後々の問題を防ぐことができます。setuptools および Poetry に関するアップストリームの問題も参照してください。

setuptools または distutils

pyproject.toml が見つからない場合、または [build-system] テーブルが含まれていない場合は、プロジェクトが セットアップ を使用する古いレガシー形式を使用していることを意味します。 setuptools または distutils を呼び出す .py ファイル。distutils は Python の standardlib に含まれていますが、setuptools がインストールされているということは、パッチ適用されたバージョンの distutils を使用することを意味することに注意してください。

makedepends=('python-setuptools')  # unless it only requires distutils

build() {
    cd "$_name-$pkgver"
    python setup.py build
}

package() {
    cd "$_name-$pkgver"
    python setup.py install --root="$pkgdir" --optimize=1
}

場所:

• --root="$pkgdir" は上記の --destdir と同様に機能します
• --optimize=1 は、最適化されたバイトコードファイル (.opt-1.pyc) をコンパイルします。これにより、ファイルはホストシステム上で作成されるのではなく、pacman から要求、追跡できるようになります。
• --skip-build を追加すると、build() 関数で既に実行されているビルド ステップを再実行する不要な試行が最適化されます (該当する場合)

結果のパッケージに 非推奨の pkg_resources モジュールをインポートする 実行可能ファイルが含まれている場合は、setuptools を追加で指定する必要があります。分割された package_*() 関数の depends。 あるいは、PKGBUILD が Python の単一バージョンの Python パッケージのみをインストールする場合は、setuptools を makedepends から depends に移動する必要があります。

一部のパッケージは setuptools を使用しようとし、setuptools をインポートできない場合は distutils にフォールバックします。この場合、得られる Python メタデータがより適切になるように、setuptools を makedepends として追加する必要があります。

実行可能ファイル (distutils ではサポートされていない) が含まれているためにパッケージに setuptools をビルドする必要があるが、distutils のみをインポートする場合、ビルドすると警告が表示され、結果のパッケージは次のようになります。壊れている可能性があります (実行可能ファイルは含まれません):

/usr/lib/python3.8/distutils/dist.py:274: UserWarning: Unknown distribution option: 'entry_points'
  warnings.warn(msg)

アップストリームのバグは報告する必要があります。この問題を回避するには、文書化されていない setuptools 機能を使用できます。

# fails because of distutils
python setup.py build

# works by using a setuptools shim
python -m setuptools.launch setup.py build

パッケージで python-setuptools-scm を使用する場合、パッケージはビルドされず、次のようなエラーが発生する可能性があります。

LookupError: setuptools-scm was unable to detect version for /build/python-jsonschema/src/jsonschema-3.2.0.

Make sure you're either building from a fully intact git repository or PyPI tarballs. Most other sources (such as GitHub's tarballs, a git checkout without the .git folder) don't contain the necessary metadata and will not work.

SETUPTOOLS_SCM_PRETEND_VERSION をビルドするには、$pkgver を値として環境変数としてエクスポートする必要があります。

export SETUPTOOLS_SCM_PRETEND_VERSION=$pkgver

チェック

警告: tox は、tox の実行中にPyPIからダウンロードされた繰り返し可能な設定をテストするために明示的に設計されており、パッケージによってインストールされるバージョンをテストしません。これでは check 機能を持つ意味がありません。

テストスイートを提供するほとんどの Python プロジェクトは、nosetests または pytest を使用して、テストスイートを含むファイルまたはディレクトリの名前に test を含むテストを実行します。一般に、テストスイートを実行するには、nosetests または pytest を実行するだけで十分です。

check(){
    cd "$srcdir/foo-$pkgver"

    # For nosetests
    nosetests

    # For pytest
    pytest
}

コンパイルされた C 拡張機能がある場合は、それを見つけてロードするために、Python の現在のメジャーバージョンとマイナーバージョンを反映する $PYTHONPATH を使用してテストを実行する必要があります。

check(){
  cd "$pkgname-$pkgver"
  local python_version=$(python -c 'import sys; print("".join(map(str, sys.version_info[:2])))')
  # For nosetests
  PYTHONPATH="$PWD/build/lib.linux-$CARCH-cpython-${python_version}" nosetests

  # For pytest
  PYTHONPATH="$PWD/build/lib.linux-$CARCH-cpython-${python_version}" pytest
}

一部のプロジェクトでは、テストを実行するための setup.py エントリポイントが提供されています。これは、pytest と nosetests の両方で機能します。

check(){
    cd "$srcdir/foo-$pkgver"

    # For nosetests
    python setup.py nosetests

    # For pytest - needs python-pytest-runner
    python setup.py pytest
}

ヒントとテクニック

python バージョンを使用する

準備、構築、テスト、またはインストール中に、システムの Python のメジャーバージョンとマイナーバージョンを参照する必要がある場合があります。これをハードコードせず (例: 3.9 や 3.10)、代わりに Python インタープリターへの呼び出しを使用して情報を取得し、ローカル変数に保存します。

check(){
  local python_version=$(python -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
  ...
}

サイトパッケージの使用

構築、テスト、またはインストール中に、システムの site-packages ディレクトリを参照する必要がある場合があります。このディレクトリをハードコードせず、代わりに Python インタープリタへの呼び出しを使用してパスを取得し、ローカル変数に保存します。

check(){
  local site_packages=$(python -c "import site; print(site.getsitepackages()[0])")
  ...
}

サイトパッケージ内のテストディレクトリ

tests という名前のディレクトリを site-packages にインストールしないように注意してください (つまり、/usr/lib/pythonX.Y/site-packages/tests/) setuptools を使用する Python パッケージプロジェクトは、テストを含むディレクトリをトップレベルの Python パッケージとして含めるように誤って設定されることがあります。これに遭遇した場合は、パッケージプロジェクトに問題を提出して修正を依頼することができます (例: このような)

Pytest オプションを無効にします

pytest を実行する際、追加のプラグインを使用しないことがほとんど望ましいです。特に、リンティングやカバレッジ用のプラグインはパッケージングにおいて逆効果であり、動作の変更がテストの失敗を引き起こす可能性があります。 addopts のような pytest オプションを無効にするには、pytest が使用する設定ファイルをパッチするよりも、コマンドラインでオプションオーバーライドを使用する方が推奨されます。これはメンテナンスの手間を減らすためです。

すべての追加オプションを解除するには、

pytest -o addopts=""

meson-python の再現性の問題を修正する

meson-python を PEP 517 ビルドバックエンドとして使用する際、ランダム化されたフォルダーパスが使用され 再現性の問題を引き起こします これを回避するには、-Cbuild-dir フラグを使用して、使用するフォルダをハードコーディングすることができます。

python -m build --wheel --no-isolation -Cbuild-dir=build