setuptools、wheel、PyPI を使用した Python プロジェクト配布の合理化

堅牢な Python アプリケーションを開発することは、旅のほんの一部です。それらを他の人がアクセスしやすく、簡単にインストールできるようにすることも同様に重要です。素晴らしいユーティリティを作成したものの、ユーザーが手動の依存関係管理と複雑なセットアップ手順で苦労するのを想像してみてください。ここで標準化されたパッケージ化と配布が登場し、プロジェクトをスクリプトのコレクションからプロフェッショナルに展開可能なパッケージに変換します。

広大な Python エコシステムにおいて、setuptools、wheel を使用したパッケージ化の技術を習得し、PyPI を通じて配布することは、ベスト プラクティスであるだけでなく、作業のシームレスな共有、コラボレーション、およびより広範な採用を可能にする基本的なスキルです。この記事では、これらのツールの複雑さを掘り下げ、生のプロジェクトから公開されインストール可能な Python パッケージまでのガイドを提供します。

開始前のコアコンセプト

実践的な側面に飛び込む前に、関係する主要なプレイヤーについての共通の理解を確立しましょう。

• setuptools: これは Python パッケージ作成の基盤です。Python の標準配布ユーティリティである distutils の機能を拡張して、Python パッケージの定義、ビルド、およびインストールのための堅牢なツールを提供するライブラリです。メタデータと依存関係の指定から配布アーカイブの生成まで、すべてを処理します。
• wheel: wheel (.whl ファイル) は、Python の事前ビルドされた配布形式です。ソース配布 (sdist) とは異なり、wheel にはコンパイル済みのバイトコードが含まれており、セットアップ スクリプトを実行したり拡張機能をコンパイルしたりすることなく、直接インストールできます。これにより、インストールの速度が大幅に向上し、一般的な環境関連の問題が回避されるため、多くの人が好む配布形式となっています。
• PyPI (Python Package Index): "パイ・ピー・アイ" と発音され、Python の公式のサードパーティ製ソフトウェア リポジトリです。これは広大な公開インデックスであり、Python 開発者はパッケージをアップロードでき、ユーザーは pip のようなツールを使用してそれらをダウンロードしてインストールできます。Python ソフトウェアのセントラル マーケットプレイスと考えてください。
• pip: Python のパッケージインストーラです。パッケージ化に直接関与していませんが、pip はユーザーが PyPI または他のソースからパッケージをインストールするために使用する主なツールです。 pip が配布されたパッケージとどのように相互作用するかを理解することは不可欠です。

Python プロジェクトのパッケージ化と配布

Python プロジェクトのパッケージ化と配布のプロセスには、通常、プロジェクト メタデータの定義、配布アーカイブの作成、これらのアーカイブの PyPI へのアップロードが含まれます。各ステップを実践的な例で詳しく説明しましょう。

1. プロジェクト構造

整理されたプロジェクト構造は最初のステップです。my_package という名前のシンプルなプロジェクトを検討してください。

my_package_project/
├── my_package/
│   ├── __init__.py
│   └── main.py
├── tests/
│   ├── test_main.py
├── README.md
├── LICENSE
└── setup.py

ここで、my_package/ は実際の Python パッケージ ディレクトリ、tests/ はテストを保持し、README.md はプロジェクトのドキュメントを提供し、LICENSE はライセンス情報を示し、setup.py はパッケージ化の取り組みの心臓部です。

2. setup.py を使用したプロジェクト メタデータの定義

setup.py ファイルは、setuptools.setup() を使用してプロジェクトのすべての重要な情報を定義する場所です。my_package の基本的な setup.py を作成しましょう。

# setup.py
from setuptools import setup, find_packages

setup(
    name='my_package',
    version='0.1.0',
    description='A simple example Python package',
    long_description=open('README.md').read(),
    long_description_content_type='text/markdown',
    author='Your Name',
    author_email='your.email@example.com',
    url='https://github.com/yourusername/my_package',
    packages=find_packages(), # Automatically finds all packages in the directory
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
    python_requires='>=3.6',
    install_requires=[
        # List your project's dependencies here
        # 'requests>=2.20.0',
        # 'numpy',
    ],
    entry_points={
        'console_scripts': [
            'my-package-cli=my_package.main:cli_entry_point',
        ],
    },
)

フィールドの説明:

• name: パッケージの名前。ユーザーがインストールするためにタイプするものです (例: pip install my_package)。
• version: パッケージの現在のバージョン (例: 0.1.0)。明確さのためにセマンティック バージョニングに従ってください。
• description: 短い 1 行の概要。
• long_description: 詳細な説明。多くの場合、README.md から読み取られます。
• long_description_content_type: long_description の形式を指定します (例: text/markdown)。
• author、author_email: あなたの連絡先情報。
• url: プロジェクトのホームページまたは GitHub リポジトリ。
• packages: これは重要です。find_packages() は、プロジェクト内のすべての Python パッケージ (__init__.py を持つディレクトリ) を自動的に検出します。手動でリストすることも可能です。
• classifiers: PyPI でプロジェクトを分類し、ユーザーがそれを見つけやすくします。包括的なリストは PyPI で利用可能です。
• python_requires: 必要な最小 Python バージョンを指定します。
• install_requires: パッケージが必要とする実行時依存関係をリストします。pip は、パッケージがインストールされるときにこれらを自動的にインストールします。
• entry_points: パッケージがコマンドライン スクリプトを提供する場合、ここで定義します。my-package-cli は、my_package.main の cli_entry_point 関数を実行する呼び出し可能なコマンドになります。

my_package/main.py では、次のようなものがあるかもしれません。

# my_package/main.py
def cli_entry_point():
    print("Hello from my_package CLI!")

if __name__ == '__main__':
    cli_entry_point()

3. ソースおよび Wheel 配布のビルド

setup.py が準備できたら、配布アーカイブをビルドできます。まず、build がインストールされていることを確認してください: pip install build。

ターミナルでプロジェクトのルート ディレクトリ (my_package_project/) に移動し、次を実行します。

python -m build

このコマンドは通常、新しく作成された dist/ ディレクトリ内に 2 種類の配布ファイルを作成します。

• ソース配布 (sdist): ソース コードと setup.py を含む .tar.gz ファイル。これは、スクラッチからビルドしたいユーザー向けです。
• Wheel 配布 (bdist_wheel): .whl ファイル。これは、プラットフォーム固有 (コンパイル済み拡張機能を含む場合) または "ピュア Python" (プラットフォームに依存しない) の、直接インストールできる事前ビルド済みパッケージです。これにより、インストールの速度が大幅に向上し、一般的な環境関連の問題が回避されます。

my_package の場合、次のようなファイルが表示される可能性があります。

dist/
├── my_package-0.1.0-py3-none-any.whl  # Wheel
└── my_package-0.1.0.tar.gz          # Source distribution

Wheel ファイル名 my_package-0.1.0-py3-none-any.whl は通常、次を示します: package_name-version-python_tag-abi_tag-platform_tag.whl。py3-none-any は、Python 3 と互換性があり、特定の ABI (Application Binary Interface) がなく、プラットフォームに依存しないことを示します。

4. PyPI へのアップロード

配布の準備ができたら、公開リリースへの最終ステップは、それらを PyPI にアップロードすることです。

a. PyPI および TestPyPI への登録

まず、両方のアカウントが必要になります。

• PyPI (本番パッケージ用)
• TestPyPI (メイン PyPI を汚染することなくアップロード プロセスをテストするため)

b. twine のインストール

twine は PyPI へのパッケージのアップロードに推奨される安全なユーティリティです。インストールします。

pip install twine

c. TestPyPI へのアップロード (推奨！)

常に TestPyPI を使用してアップロード プロセスをテストしてください。これにより、実際のリリースなしで問題を捕捉できます。

twine upload --repository testpypi dist/*

TestPyPI ユーザー名とパスワード (セキュリティ上の理由から TestPyPI アカウント設定で生成された API トークン) を求められます。

アップロードが成功したら、test.pypi.org/project/my_package でパッケージを確認できます。インストールすることもできます。

pip install --index-url https://test.pypi.org/simple/ --no-deps my_package

--no-deps フラグは、TestPyPI 自体から不正確または古い依存関係をインストールするのを避けるために、TestPyPI アップロードでよく役立ちます。

d. 公式 PyPI へのアップロード

TestPyPI アップロードで自信が得られたら、公式 PyPI にアップロードできます。

twine upload dist/*

ここでも、PyPI ユーザー名と API トークンを入力します。

おめでとうございます！パッケージは PyPI で公開され、誰でも pip install my_package を使用してインストールできます。

アプリケーション シナリオ

• オープンソース ライブラリ: 再利用可能なコードを世界と共有し、簡単に見つけやすくインストールできるようにします。
• 社内ツール: 手動のインストール手順なしで、独自のユーティリティやモジュールを組織全体に配布します。
• 複雑なアプリケーション: 主な配布が PyPI を介していなくても、パッケージ化を理解することで、プロジェクトを信頼性の高い依存関係管理と将来の PyPI リリース向けに構造化するのに役立ちます。
• 依存関係管理: install_requires を適切に定義することで、ユーザーがすべての必要なコンポーネントを推測することなく取得することを保証します。

結論

setuptools、wheel、PyPI を使用して Python プロジェクトをパッケージ化および配布することは、すべての真剣な Python 開発者にとって不可欠なスキルです。生のコードをプロフェッショナルで共有しやすく、インストール可能な製品に変えます。これらの手順に従うことで、ハードワークが対象読者にシームレスに届き、Python コミュニティ内での採用とコラボレーションを促進することを保証できます。このワークフローをマスターして、Python の作成の可能性を最大限に引き出してください。