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 ロールの付与を管理者に依頼してください。

ロールの付与の詳細については、アクセスの管理をご覧ください。

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

パッケージの追加

リポジトリ モード: 標準

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/*

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

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

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

コンソール

  1. Google Cloud Console で [リポジトリ] ページを開きます。

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

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

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

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

gcloud

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

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

Where

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

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

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

ここで

  • PACKAGE は、パッケージの 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

次の値を置き換えます。

例

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

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

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

gcloud artifacts files list \
    --location=us-central1 \
    --repository=my-repo
次のコマンドは、パッケージのバージョン 1.0 内のファイルを一覧表示します。

gcloud artifacts files list \
    --project=my-project \
    --location=us-central1 \
    --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 のパッケージ化のドキュメントをご覧ください。

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

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

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

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

パッケージまたはパッケージのバージョンを削除する前に、そのパッケージの重要な依存関係を送信済み、または対処済みであることを確認してください。

パッケージを削除するには：

コンソール

  1. Google Cloud Console で [リポジトリ] ページを開きます。

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

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

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

  3. 削除するパッケージを選択します。

  4. [削除] をクリックします。

  5. 確認のダイアログ ボックスで、[削除] をクリックします。

gcloud

次のコマンドを実行します。

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

Where

  • PACKAGE は、リポジトリ内のパッケージの名前です。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • LOCATION は、リージョンまたはマルチリージョンのロケーションです。このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • --async - 処理中のオペレーションの完了を待たずに、直ちにコマンドを終了します。

パッケージのバージョンを削除するには:

コンソール

  1. Google Cloud Console で [リポジトリ] ページを開きます。

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

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

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

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

  4. 削除するバージョンを選択します。

  5. [削除] をクリックします。

  6. 確認のダイアログ ボックスで、[削除] をクリックします。

gcloud

次のコマンドを実行します。

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

Where

  • PACKAGE は、リポジトリ内のパッケージの名前です。
  • REPOSITORY はリポジトリの名前です。デフォルト リポジトリを構成した場合は、このフラグを省略してデフォルトを使用できます。
  • LOCATION は、リージョンまたはマルチリージョンのロケーションです。このフラグを使用して、特定のロケーションのリポジトリを表示します。デフォルト ロケーションを構成している場合は、このフラグを省略してデフォルトを使用できます。
  • --async は処理中のオペレーションの完了を待たずに、直ちにコマンドを終了します。

次のステップ