Python パッケージを管理する

このページでは、Python パッケージとパッケージ バージョンの追加、表示、削除について説明します。

始める前に

1. Google Cloud CLI をインストールして初期化します。

   Python リポジトリに対するコマンドを実行するには、Google Cloud CLI バージョン 354.0.0 以降が必要です。バージョンは、次のコマンドで確認できます。

   gcloud version
   

2. ターゲット リポジトリが存在しない場合は、新しい Python パッケージ リポジトリを作成します。

3. Python 3 がインストールされていることを確認してください。インストール手順については、Google Cloud Python の設定のチュートリアルをご覧ください。

4. （省略可）gcloud コマンドのデフォルトを構成します。

5. gcloud 認証情報でキーリング認証を使用している場合は、ユーザー アカウントまたはサービス アカウントで Google Cloud CLI にログインします。

必要なロール

パッケージの管理に必要な権限を取得するには、リポジトリに対する次の IAM ロールの付与を管理者に依頼してください。

• パッケージまたはパッケージ内のファイルを表示する: Artifact Registry 読み取り （roles/artifactregistry.reader）
• パッケージをダウンロードまたはインストールする: Artifact Registry 読み取り （roles/artifactregistry.reader）
• リポジトリにパッケージを追加する: Artifact Registry 書き込み （roles/artifactregistry.writer）
• パッケージを削除する: Artifact Registry リポジトリ管理者 （roles/artifactregistry.repoAdmin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

パッケージの追加

リポジトリ モード: 標準

Python プロジェクトをビルドすると、ディストリビューション ファイルはプロジェクトの dist サブディレクトリに保存されます。その後、Twine を使用してパッケージを標準リポジトリにアップロードできます。

パッケージに対しては、次のベスト プラクティスをおすすめします。

• 特に pip 構成に複数のパッケージ インデックスが含まれている場合は、pypi.org のパッケージ名と一致しないように、プライベート パッケージに一意の名前を使用します。
• パッケージ バージョン 番号には、PEP 440 というバージョン ID の仕様を使用します。デフォルトでは、pip は安定版リリースのみをインストールします。バージョン ID の仕様を使用して、安定版とプレリリース版を区別し、インストールするバージョンの要件をすべて解析します。

パッケージを追加するには、次の手順を行います。

1. Twine をインストールします。

   pip install twine
   

2. Python プロジェクトのディレクトリに移動します。

3. プロジェクトの dist サブディレクトリからリポジトリにディストリビューション ファイルをアップロードします。次のコマンドを実行します。

   twine upload dist/*
   

   --repository-url フラグを使用して特定のリポジトリを指定できます。

   twine upload --repository-url https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/ dist/*
   

注: デフォルトでは、Twine は詳細なエラーメッセージを返しません。エラーが発生した場合は、--verbose フラグを指定して Twine コマンドを再実行することで、より詳細なメッセージを受け取ることができます。一般的なエラーコードについては、Python パッケージのトラブルシューティングをご覧ください。

パッケージとバージョンを表示する

リポジトリ モード: 標準、リモート

Google Cloud コンソールまたは gcloud を使用してパッケージとパッケージのバージョンを表示するには:

コンソール

1. Google Cloud コンソールで [リポジトリ] ページを開きます。

   [リポジトリ] ページを開く

2. リポジトリ リストで、適切なリポジトリをクリックします。

   [パッケージ] ページに、リポジトリ内のパッケージが一覧表示されます。

3. パッケージをクリックして、そのパッケージのバージョンを表示します。

gcloud

リポジトリ内のパッケージを一覧表示するには、次のコマンドを実行します。

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

以下を置き換えます。

• REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
• LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。 デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。

パッケージのバージョンを表示するには、次のコマンドを実行します。

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

以下を置き換えます。

• PACKAGE は、パッケージの ID またはパッケージの完全修飾 ID です。
• REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
• LOCATION は、リポジトリのリージョンまたはマルチリージョンのロケーションです。 このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。

リモート リポジトリの場合、返されるリストには、すべての直接的な依存関係と一時的な依存関係が含まれます。

ファイルのリスティング

リポジトリ モード: 標準、リモート

リポジトリ内のファイル、指定したパッケージのすべてのバージョン内のファイル、またはパッケージの特定のバージョン内のファイルを一覧表示できます。

次のすべてのコマンドについては、コマンドに --limit フラグを追加することで、返されるファイルの最大数を設定できます。

デフォルト値が構成されている場合にデフォルトのプロジェクト、リポジトリ、ロケーションのすべてのファイルを一覧表示するには次のようにします。

gcloud artifacts files list

指定したプロジェクト、リポジトリ、ロケーション内のファイルを一覧表示するには、次のコマンドを実行します。

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

特定のパッケージのすべてのバージョン内のファイルを一覧表示するには:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

特定のパッケージ バージョンのファイルを一覧表示するには:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

次の値を置き換えます。

• LOCATION: リポジトリのリージョンまたはマルチリージョン ロケーション。
• PROJECT: Google Cloud プロジェクト ID。プロジェクト ID にコロン（:）が含まれている場合は、ドメインをスコープとするプロジェクトをご覧ください。
• REPOSITORY: イメージが保存されるリポジトリの名前。
• PACKAGE: パッケージの名前。
• VERSION: パッケージのバージョン。

例

次のパッケージ情報について考慮するには:

• プロジェクト: my-project
• リポジトリ: my-repo
• リポジトリの場所: us-west1
• パッケージ: my-app

次のコマンドは、デフォルト プロジェクト内のロケーション us-west1 のリポジトリ my-repo 内のすべてのファイルを一覧表示します。

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo

パッケージのバージョン 1.0 内のファイルを一覧表示します。

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

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

リポジトリ モード: 標準、リモート、仮想

pip コマンドを使用して、パッケージをインストールします。

パッケージの最新の安定版リリースをインストールするには、次のコマンドを実行します。

pip install PACKAGE

標準リポジトリの場合は、リポジトリからパッケージを直接ダウンロードします。

リモート リポジトリの場合は、パッケージとその依存関係のキャッシュに保存されたコピーをダウンロードします。キャッシュに保存されたコピーが存在しない場合は、リモート リポジトリがアップストリーム ソースからパッケージをダウンロードし、それを提供する前にキャッシュに保存します。リモート リポジトリがアップストリーム ソースからパッケージを取得したことを確認するには、リポジトリ内のパッケージの一覧を表示します。

仮想リポジトリの場合は、Artifact Registry はリクエストされたパッケージのアップストリーム リポジトリを検索します。

• キャッシュに保存されたコピーが存在しない場合、アップストリームのリモート リポジトリは、リクエストされたパッケージをダウンロードしてキャッシュに保存します。仮想リポジトリはリクエストされたパッケージを提供だけして、保存しません。
• 複数のアップストリーム リポジトリに存在する利用可能なバージョンをリクエストすると、Artifact Registry は仮想リポジトリ用に構成された優先度設定に基づいて、使用するアップストリーム リポジトリを選択します。

たとえば、アップストリーム リポジトリに次の優先度設定がある仮想リポジトリについて考えます。

• main-repo: 優先度が 100 に設定
• secondary-repo1: 優先度が 80 に設定
• secondary-repo2: 優先度が 80 に設定
• test-repo: 優先度が 20 に設定

main-repo の優先度の値は最も高いため、仮想リポジトリは常に最初に検索します。

secondary-repo1 と secondary-repo2 はどちらも優先度が 80 に設定されています。リクエストされたパッケージが main-repo にない場合、Artifact Registry は次にこれらのリポジトリを検索します。どちらも同じ優先度を持つため、両方にそのバージョンがある場合、Artifact Registry はどちらか一方のリポジトリからパッケージを提供するように選択できます。

test-repo の優先度は最も低くなります。他のアップストリーム リポジトリにアーティファクトがない場合、保存されたアーティファクトが提供されます。

その他の情報

デフォルトでは、pip はパッケージの安定版をインストールし、プレリリース版を無視します。PEP 440 では、pip ユーザーがバージョン番号（プレリリース版を含む）を解析するための Python バージョン ID 仕様を定義しています。

pip がインストールするパッケージを検索するときにプレリリース版を含めるには、コマンドに --pre フラグを指定します。

pip install --pre PACKAGE

必要なバージョンまたはバージョン範囲を指定するには、要件指定子を含めます。バージョンの要件をコマンドに直接含めるか、要件ファイルを使用します。

たとえば、このコマンドでは、my-package の最小バージョンが開発版 1.0.dev0 であることを指定します。

pip install --pre my-package>=1.0.dev0

安定版リリースはプレリリースよりも新しいと見なされるため、バージョン 1.0 がリポジトリにある場合、pip はプレリリース版よりもバージョン 1.0 を選択します。

リポジトリを指定しない場合、pip.conf の pip 構成によって、pip がパッケージを検索する方法が決まります。

• Artifact Registry リポジトリを index-url 設定で構成し、他のパッケージ インデックスが構成されていない場合、pip は Artifact Registry リポジトリでそのパッケージのみを検索します。
• 仮想リポジトリを使用しており、リクエストされたパッケージ バージョンが複数のアップストリーム リポジトリにある場合、Artifact Registry はアップストリーム ポリシーで構成された優先度を使用してパッケージを選択します。パッケージがある 2 つのリポジトリの優先度が同じ場合、Artifact Registry はいずれかのリポジトリからパッケージを提供します。
• extra-index-url 設定で pip を構成した場合や、複数のパッケージ インデックスを構成した場合、pip は pypi.org と構成済みの他のパッケージ インデックスを検索し、パッケージの最新バージョンを選択します。

要件ファイルの index-url 設定や extra-index-url 設定はオーバーライドできます。pip コマンドにこれらの設定のフラグを使用することもできます。たとえば、このコマンドは Artifact Registry リポジトリで index-url をオーバーライドします。

pip install --index-url https://us-east1-python.pkg.dev/my-project/python-repo/simple/ my-package

パッケージのインストールの詳細については、Python のパッケージ化のドキュメントをご覧ください。

注: デフォルトでは、Twine は詳細なエラー メッセージを返しません。エラーが発生した場合は、-v または -vv のフラグを指定してコマンドを再実行し、詳細な出力を得ます。詳細については、Python パッケージのトラブルシューティングをご覧ください。

パッケージとバージョンの削除

リポジトリ モード: 標準、リモート

パッケージとそのすべてのバージョンを削除することや、特定のバージョンを削除することができます。

• パッケージを削除すると、その操作は元に戻せません。
• リモート リポジトリの場合は、パッケージのキャッシュに保存されたコピーのみが削除されます。アップストリーム ソース はこの影響を受けません。キャッシュに保存されたパッケージを削除し、次回、リポジトリが同じパッケージ バージョンのリクエストを受信すると、Artifact Registry は再度そのパッケージをダウンロードしてキャッシュに保存します。

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

1. Open the Repositories page in the Google Cloud console.

   [リポジトリ] ページを開く

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Replace the following:

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

1. Open the Repositories page in the Google Cloud console.

   [リポジトリ] ページを開く

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Replace the following:

• VERSION is the name of the version to delete.
• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

次のステップ

• Java パッケージの管理について学習する
• Node.js パッケージの管理について学習する
• コンテナ イメージの管理について確認する
• パッケージ内の個々のファイルをダウンロードする