PythonパッケージをPyPIに公開する

これまでのPythonパッケージングレッスンで、あなたは次のことを学びました:

1. Pythonパッケージとは

2. コードをインストール可能にします。

学習目標

このレッスンで学ぶこと:

• パッケージのソース (sdist) とwheelディストリビューションをビルドします。

• TestPyPIにアカウントを設定する（PyPIでも同様の手順です）

• パッケージをTestPyPIとPyPIに公開する

このレッスンでは、すべての開発作業を Hatch を使って行います。

パッケージがPyPIに載ったら、 Grayskull を使ってconda-forge (condaのチャンネルです) に公開できます。

conda-forgeに公開する方法は 次のレッスン で学びます。

PythonパッケージをPyPI（またはConda）に公開するには、ビルドする必要があります。ビルドプロセスは、あなたのコードとメタデータをPyPIにアップロードできる配布フォーマットに整理し、その後ユーザーがダウンロードしてインストールできるようにします。

TestPyPI vs PyPI

PyPIには、Pythonパッケージをアップロードできる2つのリポジトリがあります。

1. TestPyPI: TestPyPIはPyPIが提供するパッケージリポジトリで、あなたのパッケージが正しくアップロード、ダウンロード、インストールできるかをテストするために使用できます。これは、実際のPyPIサービスに不完全なパッケージを公開することなく、パッケージを公開する方法を学び、練習するのに最適な場所です。

2. PyPI: これは、あなたが公式に Python パッケージを公開でき、ユーザがあなたのパッケージを取得できる、本番用の PyPI リポジトリです。重要: PyPIにパッケージを公開するのは、それが他の人に使われる準備ができたとき、そして/またはそれがあなたが保守するパッケージになると確信したときだけにしてください。 PyPIはPythonパッケージの公開方法を学ぶ練習の場ではありません。

TestPyPIとPyPIで公開する手順は、URLが異なることを除いて似ています。両者の相違点を指摘します。

TestPyPI (またはPyPI)でPythonパッケージを公開するための4つのステップ

このレッスンでは、 Hatch を使ってパッケージをTestPyPIに公開する方法を学びます。 Pythonパッケージを公開するために必要なことは4つあります: TestPyPIでは。必要なのは:

1. パッケージ開発環境の構築

2. hatch build を使ってパッケージをビルドします。 パッケージのビルドは、コードを2種類の配布ファイルに変換するプロセスです: sdistとwheel。wheel配布ファイルは、あなたのパッケージを pip install するユーザーにとって特に重要です。

3. TestPyPI (またはPyPI)でアカウントを作成します: TestPyPIアカウントと、パッケージをアップロードするためのパーミッションを提供する関連トークンを作成する必要があります。 後でパッケージをPyPIに公開するときは、別のPyPIアカウントとトークンが必要になります。

4. ** hatch publish を使用してTestPyPIにパブリッシュする**

In a future lesson, you will learn how to create an automated GitHub Actions workflow that publishes an updated version of your package to PyPI every time you create a GitHub release.

Pythonパッケージのビルドについては、ガイドを参照してください。

• Pythonパッケージのビルドについてもっと知る

• PyPIが必要とするwheelと呼ばれるパッケージ配布ファイルについての詳細はこちら

• PyPIでconda-forgeが必要とするsdist (ソースディストリビューション) と呼ばれるパッケージ配布ファイルについてはこちらを参照してください

ステップ1: Pythonパッケージ開発環境の構築

パッケージ構築の最初のステップは、開発環境を作ることだ。Python環境には、あなたのパッケージのインストールと作業の両方に必要な依存関係がすべて含まれています。

Hatchを使って環境を整えましょう。

# This will create a default environment with your package installed in editable mode
> hatch env create
# If you have already created an environment this command will return Environment `default` already exists

次に、Hatchがアクセスできる現在の環境をすべて表示します:

> hatch env show
     Standalone
┏━━━━━━━━━┳━━━━━━━━━┓
┃ Name    ┃ Type    ┃
┡━━━━━━━━━╇━━━━━━━━━┩
│ default │ virtual │
└─────────┴─────────┘

そして環境をアクティブにします。 Hatch環境からシェルを呼び出すと、開発モードまたは編集可能モードで、あなたのパッケージが自動的に環境にインストールされることに注意してください。

# Hatch shell can be used to activate your environment
> hatch shell
... Installing project in development mode
source "/Path/to/env/here/hatch/env/virtual/pyosPackage/Mk7F5Y0T/sphinx-2i2c-theme/bin/activate"

pip list を使って環境にあるものを見ます:

➜ pip list
Package         Version      Editable project location
--------------- ------------ ----------------------------------------------------
numpy           1.26.3
pandas          2.1.4
pip             23.3.1
pyosPackage     0.1.0        /path/to/your/project/here/pyosPackage
python-dateutil 2.8.2
pytz            2023.3.post1
six             1.16.0
tzdata          2023.4

いつでも exit を使って環境を終了することができます。

➜ hatch shell
source "/Users/leahawasser/Library/Application Support/hatch/env/virtual/pyospackage/twO2iQR3/pyospackage/bin/activate"

# Notice here you're in the (pyospackage) environment which is the default
pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv (pyospackage)
➜ exit

pyosPackage (☊ main) [✎ ×1 ] is 📦 v0.1.4 via 🐍 pyenv took 43s
➜

Hatchと環境

hatchが新しい仮想環境を作るときの裏側では、デフォルトではPythonのインストールに付属しているデフォルトの環境管理ツールである venv[1] を使います。

Hatch は:

1. コンピュータ上に新しい仮想環境 (venv) を作成します。

2. 編集可能モードでパッケージを環境にインストールします ( python -m pip install -e と同様) 。 これは、pyproject.tomlファイルで宣言されているように、あなたのプロジェクトとプロジェクトの依存関係の両方をインストールすることを意味します。

ステップ 2: パッケージのsdistとwheelディストリビューションをビルドする

開発環境のセットアップが完了したら、Hatchを使ってパッケージをビルドする準備ができました。 ビルドとは、Pythonパッケージのファイル構造を2つの配布ファイルにするプロセスであることを覚えておいてください:

1. wheelディストリビューション は、あなたのパッケージのビルド済みバージョンです。 pip などのツールを使って直接インストールできるので、ユーザーにとっては便利です。このファイルの拡張子は .whl です。

2. ソースディストリビューション には、あなたのパッケージを構成するファイルが、ビルドされていない状態で含まれています。 このファイルの拡張子は .tar.gz となります。

You will use Hatch as a Front end tool that builds your package's sdist and wheel using the hatchling build back-end. The hatchling build back-end is used because you declared it in your pyproject.toml file in the previous lesson.

パッケージをビルドするには hatch build を実行します:

➜ hatch build
──────────────── sdist ─────────────────
dist/pyospackage-0.1.tar.gz
──────────────── wheel ─────────────────
dist/pyospackage-0.1-py3-none-any.whl

Pythonパッケージのビルドについて

ビルドについては、 パッケージングガイドのビルドのページ で詳しく説明しています。

sdistは、conda-forgeにパッケージを 公開する場合に重要です 。これについては後のレッスンで学びます。

おめでとう - Pythonパッケージの配布ファイルを作成しました

これで Python パッケージをビルドし、パッケージ配布ファイルを作成しました。次のステップは、TestPyPIのアカウントをセットアップして、パッケージを公開できるようにすることです。

ステップ 3. TestPyPIアカウントをセットアップする

次に、TestPyPIのアカウントをセットアップします。 TestPyPIは本物のPyPIではなく、パッケージが準備できる前に誤ってパッケージを "リリース" することなく、安全にパッケージを公開する方法を学ぶ方法として使用していることを忘れないでください。

TestPyPI vs. PyPI

もしあなたがPyPIに属していると確信しているパッケージを持っているなら、以下の手順はすべてあなたにも有効です。 Hatch を使って公開する場合、TestPyPI に公開する hatch publish -r test ではなく、直接 PyPI に公開する hatch publish を呼び出します。

1. ウェブブラウザを開き、TestPyPIのウェブサイトにアクセスする.

2. まだアカウントをお持ちでない方は、 アカウントを作成してください。 パスワードは必ず安全な場所に保管してください！

3. アカウントを設定したら、ログインしてください。

4. https://test.pypi.org/ で検索して ( https://pypi.org/ でも検索して) 、選択したパッケージ名がすでに存在しないことを確認してください。 テスト用のpyosPackageを使う場合は、一意であることを保証するために、パッケージ名の最後に自分の名前かGitHubのユーザー名を追加することをお勧めします。

例: pyosPackage_yourNameHere.

How to rename your Python package if the name is already taken in (test) PyPI

要件

1. デプロイする (複数) 箇所を検索し、新しい名前が取られていないことを確認します (TestPyPI, PyPI, conda-forge)

2. pyproject.toml ファイルのプロジェクト名を更新します (e.g. name = "pyospackage_yourNameHere")

3. モジュールフォルダ名を同じに更新します (例: src/pyospackage_yourNameHere)

4. プロジェクトの再ビルド (hatch build)

5. パッケージを公開して名前を取得する(このチュートリアルを続けましょう!)

おすすめ

• GitHubリポジトリ名を新しいパッケージ名に合わせて更新します

• ローカルのプロジェクトフォルダを新しいパッケージ名に合わせて更新します (例: pyospackage_yourNameHere/src ）。

• 他のファイル (例えば README.md ) のリポジトリ名の記述を更新します。

TestPyPIにアップロードしようとする前に、あなたのパッケージの名前がすでに使われていないか確認してください。TestPyPIのウェブサイトの上部にある検索ボックスを使って検索することができます。

2ファクタ (2FA) 認証の設定

2要素認証とは、自分だけがアクセスできるバックアップデバイスを使用して、ログインする人が本当に自分であることを確認できる安全なログインプロセスです。他人がパスワードにアクセスし、あなたのアカウントにログインできるようにするパスワードフィッシングの問題に対処します。

なぜなら、誰かがあなたのアカウントにログインして、セキュリティ上の問題があるバージョンのパッケージをアップロードする可能性があるからです。 これらの問題は、そのバージョンのパッケージをダウンロードしてインストールする際に、すべてのユーザーに影響を与えます。

2024年1月1日からPyPI認証に2要素認証が必要になりました。

ステップ4. パッケージアップロードトークンを作成する

パッケージをTestPyPI (またはPyPI) にアップロードするには、まず自分のアカウントのトークンを作成する必要があります。 (以前にこのステップを完了した場合は、パッケージを再度アップロードするときにトークンを再利用できます。)

なぜパッケージ固有のトークンを作るのか？

パッケージ固有のトークンを作るのが理想的です。 アカウントワイドトークンを作成すると、そのアカウントにアクセスできる人なら誰でも、TestPyPI (またはPyPI) のすべてのプロジェクトにアクセスできるようになります。 パッケージ固有のトークンを作成することで、トークンのスコープを特定のパッケージのみに限定することができます。これは、特にパッケージ開発で他の人と共同作業する場合に、安全な設定方法です。

以下の手順に従ってトークンを作成してください。

• TestPyPIにログインし、アカウント設定に進みます。

• APIトークン のセクションまでスクロールダウンしてください

• APIトークンの追加 ボタンをクリックしてください

  • TestPyPIを使うのが初めてで、まだパッケージを持っていない場合、またはTestPyPIに他のパッケージを持っていて、新しいパッケージをアップロードする場合、アカウントワイドトークンを作成する必要があります。

• トークンを作成したら、ブラウザを閉じる前に必ずトークンの値をコピーし、安全な場所に保管してください。

あなたのトークンは次のようになるはずです:

pypi-abunchofrandomcharactershere...

pypi で始まり、ダッシュとたくさんの文字が続くはずです。

Hatchを使用してTestPyPIにアップロードする

トークンを取得したら、TestPyPIに公開する準備ができました。

• hatch publish -r test を実行します

-r はリポジトリを意味します。この場合、TestPyPIに公開するため、 -r test を使用します。 その後、Hatchはユーザー名と認証情報を要求します。

• ユーザー名には __token__ を追加してください。これはTestPyPIに、ユーザ名ではなくトークンの値を使用していることを伝えます。

• Enter your credentials プロンプトで TestPyPI トークンの値を貼り付けます:

❯ hatch publish -r test
Enter your username: __token__
Enter your credentials: <paste-your-token-value-here>
dist/pyospackage-0.1-py3-none-any.whl ... already exists
dist/pyospackage-0.1.tar.gz ... already exists

あなたの認証情報が有効で、すでに hatch build を実行し、2つの配布ファイルが dist/ ディレクトリにあれば、Hatch はあなたのパッケージを TestPyPI に公開します。

Hatchにはキャッシュシステムもあり、一度入力した認証情報は記憶されます。

TestPyPIからパッケージをインストールする

パッケージのアップロードが完了したら、TestPyPIからインストールできます。新しくアップロードしたパッケージのTestPyPIランディングページにインストール手順があります。

これはアップロードされたばかりのpyosPackageのランディングページの例です。 ページの一番上に、TestPyPIからパッケージをインストールする方法の説明があります。 そのコードをコピーし、それを使ってTestPyPIからパッケージをローカルにインストールするだけです。

例として、 TestPyPIのpyOpenSci pyosPackageランディングページをご覧ください 。 このページには、現在のパッケージのバージョンに関する情報と、次のようなインストール手順が記載されていることに注意してください:

python -m pip install -i https://test.pypi.org/simple/ pyosPackage

重要

TestPyPIへの公開 vs PyPI TestPyPIからインストールすることはできますが、パッケージをインストールする恒久的な方法としてTestPyPIに公開することはお勧めしません。なぜなら、TestPyPIは時間が経つとアカウントを削除するかもしれないからです。TestPyPIは、パッケージを公開し、インストールプロセスをテストする方法を学ぶのに最適な場所です。しかし、最終的なゴールは、ワークフローを把握し、パッケージがデプロイできる状態になったら、PyPIに公開することです。

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

• お使いのコンピューターで、新しく公開するパッケージをインストールする開発環境をアクティブにします。

• TestPyPIからパッケージのインストール手順を実行します。

Conda

> conda activate pyospkg-dev
> pip install -i https://test.pypi.org/simple/ youPackageNameHere
> conda list

venv Mac / Linux

> hatch shell
> pip install -i https://test.pypi.org/simple/ youPackageNameHere
> pip list

hatch、flit、poetryといったエンドツーエンドツールの価値

このレッスンでは Hatch と hatchling を使って Python パッケージを作成、ビルド、公開します。 エコシステム内の他のパッケージングツールについては、こちらをクリックしてください。

パッケージ固有のトークンと信頼できるパブリッシャー

パッケージの長期的なメンテナンスのために、PyPI公開に関する2つのオプションがあります。

1. PyPIにパッケージを (手動で) 公開する際に使用する、パッケージ固有のトークンを作成することができます。これはPyPI公開のワークフローを自動化したくない場合に最適なオプションです。

2. GitHub Actionsを使って、GitHub上で自動公開ワークフローを作成することもできます。 これは、出版プロセスをより簡単にする素晴らしい方法であり、また、成長するメンテナーチームをサポートするものでもあります。 この場合、トークンのことは気にせず、リリース時にパッケージを公開する GitHub Actionsを設定することをお勧めします。 その後、PyPIで "trusted publisher" ワークフローを作成することができます。

Trusted Publishing

While publishing from GitHub Action is possible using tokens, we recommend the Trusted Publishing approach as it also confers significant security and usability benefits.

On the usability front, when Trusted Publishing is enabled, users no longer need to manually create API tokens on PyPI and store them in the GitHub release workflow.

On the security front, Trusted Publishing reduces a risk related to the API token being long lived: with API tokens, as soon as an attacker gets access to it, they can publish many packages and versions in your name (depending on the scope of the token), until you discover the token compromise and rotate the credential. Trusted Publishing avoids this problem by minting very short lived tokens which expire automatically.

For these benefits, it is recommended that users use only the GitHub Actions release workflow to publish packages.

自動化された信頼できるパブリッシャーワークフローの作成方法については、次のレッスンで学びます。

オプション: 手動トークンベースの発行ワークフローを使用する場合

トークンを定期的に使ってPyPIに公開する予定がある場合、新しいパッケージに固有のトークンを作成するために、上記の手順をもう一度行うことを強くお勧めします。

そのためには:

1. TestPyPIに行きます。

2. アカウントの "Your Projects" セクションに移動します

3. トークンを追加したいプロジェクトの管理ボタンをクリックします

4. 設定に進む

5. "パッケージ名のトークンを作成する" をクリックします

6. トークンを作成し、上記の手順に従って、リポジトリ固有のトークンを使用してパッケージを公開します。

そして、すべて終わりました！

Trusted Publishing instead of token-based publication

Trusted Publishing will generate short lived tokens, scoped to the project, on demand, only when a specific release workflows gets triggered. This solves all the security and usability issues associated with storing credentials in files/GitHub secrets.

あなたはTestPyPIにパッケージを公開しました!

おめでとうございます。これで、TestPyPIへのパッケージの公開が成功しました。実際のPyPIで利用できる準備が整ったパッケージがあれば、同じ手順で (上記の違いはありますが) PyPIに公開することができます。

PyPIで公開したら、 grayskull ツールを使って簡単にconda-forgeエコシステムにパッケージを追加できます。

その方法は次のレッスンで学習します。

脚注

[1]

https://docs.python.org/3/library/venv.html