Python-Pakete verwalten

Auf dieser Seite wird beschrieben, wie Sie Python-Pakete und Paketversionen hinzufügen, aufrufen und löschen.

Hinweis

1. Installieren und initialisieren Sie die Google Cloud CLI.

   Google Cloud CLI-Version 354.0.0 oder höher ist erforderlich, um Befehle für Python-Repositories auszuführen. Sie können die Version mit dem folgenden Befehl prüfen:

   gcloud version
   

2. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Python-Paket-Repository.

3. Prüfen Sie, ob Python 3 installiert ist. Eine Installationsanleitung finden Sie im Google Cloud Tutorial zum Einrichten von Python.

4. (Optional) Konfigurieren Sie die Standardeinstellungen für gcloud-Befehle.

5. Wenn Sie die Keyring-Authentifizierung mit gcloud-Anmeldedaten verwenden, melden Sie sich mit Ihrem Nutzerkonto oder Dienstkonto in der Google Cloud CLI an.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Verwalten von Paketen benötigen:

• Pakete oder Dateien in Paketen ansehen: Artifact Registry-Leser (roles/artifactregistry.reader)
• Pakete herunterladen oder installieren: Artifact Registry-Leser (roles/artifactregistry.reader)
• Pakete zu einem Repository hinzufügen: Artifact Registry-Autor (roles/artifactregistry.writer)
• Pakete löschen: Repository-Administrator für Artifact Registry (roles/artifactregistry.repoAdmin)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Pakete hinzufügen

Repository-Modi: Standard

Wenn Sie ein Python-Projekt erstellen, werden die Verteilungsdateien in einem Unterverzeichnis dist in Ihrem Projekt gespeichert. Anschließend können Sie Twine verwenden, um Pakete in ein Standard-Repository hochzuladen.

Wir empfehlen die folgenden Best Practices für Ihre Pakete:

• Verwenden Sie eindeutige Namen für Ihre privaten Pakete, damit sie nicht mit Paket namen auf pypi.org übereinstimmen. Dies ist besonders wichtig, wenn Ihre Pip-Konfiguration mehrere Paketindizes enthält.
• Verwenden Sie die Spezifikation für die Versionskennung in PEP 440 für Ihre Paketversionsnummern. Standardmäßig installiert Pip nur stabile Releases. Die Spezifikation für die Versionskennung wird verwendet, um stabile Versionen von Vorabversionen zu unterscheiden und alle Anforderungen für die zu installierende Version zu parsen.

So fügen Sie ein Paket hinzu:

1. Installieren Sie Twine.

   pip install twine
   

2. Wechseln Sie zu Ihrem Python-Projektverzeichnis.

3. Laden Sie die Verteilungsdateien aus dem Unterverzeichnis dist des Projekts in das Repository hoch. Führen Sie dazu diesen Befehl aus:

   twine upload dist/*
   

   Mit dem Flag --repository-url können Sie ein bestimmtes Repository angeben.

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

Hinweis: Standardmäßig gibt Twine keine detaillierten Fehlermeldungen zurück. Wenn ein Fehler auftritt, führen Sie den Twine-Befehl mit dem Flag --verbose noch einmal aus, um eine detailliertere Meldung zu erhalten. Informationen zu einigen häufigen Fehlercodes finden Sie unter Fehlerbehebung bei Python-Paketen.

Pakete und Versionen ansehen

Repository-Modi: Standard, Remote

如需使用 Google Cloud 控制台或 gcloud 查看软件包和软件包版本，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中打开代码库页面。

   Zur Seite „Repositories“

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 或软件包的完全限定标识符。
• REPOSITORY 是代码库的名称。如果您配置了默认代码库，则可以省略此标志以使用默认值。
• LOCATION 是代码库的区域位置。 使用此标志可查看特定位置的代码库。 如果您配置了默认位置，则可以省略此标志以使用默认值。

Bei Remote-Repositories sollte die zurückgegebene Liste alle direkten und transitiven Abhängigkeiten enthalten.

Dateien auflisten

Repository-Modi: Standard, Remote

Sie können Dateien in einem Repository, Dateien in allen Versionen eines bestimmten Pakets oder Dateien in einer bestimmten Version eines Pakets auflisten.

Für alle folgenden Befehle können Sie eine maximale Anzahl von Dateien festlegen, die zurückgegeben werden sollen. Fügen Sie dazu dem Befehl das Flag --limit hinzu.

So listen Sie alle Dateien im Standardprojekt, im Standard-Repository und am Standard-Speicherort auf, wenn die Standardwerte konfiguriert sind:

gcloud artifacts files list

Führen Sie den folgenden Befehl aus, um Dateien in einem bestimmten Projekt, Repository und Speicherort aufzulisten:

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

So listen Sie Dateien für alle Versionen eines bestimmten Pakets auf:

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

So listen Sie Dateien für eine bestimmte Paketversion auf:

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

Ersetzen Sie die folgenden Werte:

• LOCATION: der regionale Standort des Repositorys.
• PROJECT: Ihre Google Cloud Projekt-ID.
• REPOSITORY: der Name des Repositorys, in dem das Image gespeichert ist.
• PACKAGE: der Name des Pakets.
• VERSION: die Version des Pakets.

Beispiele

Betrachten Sie die folgenden Paketinformationen:

• Projekt: my-project
• Repository: my-repo
• Speicherort des Repositorys:
• Paket: my-app

Mit dem folgenden Befehl werden alle Dateien im Repository my-repo am Speicherort im Standardprojekt aufgelistet:

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

Mit dem folgenden Befehl werden die Dateien in Version 1.0 des Pakets aufgelistet.

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

Pakete installieren

Repository-Modi: Standard, Remote, virtuell

Verwenden Sie den Befehl pip, um Pakete zu installieren.

Führen Sie den folgenden Befehl aus, um die neueste stabile Version eines Pakets zu installieren:

pip install PACKAGE

Bei Standard-Repositories laden Sie ein Paket direkt aus dem Repository herunter.

Bei einem Remote-Repository laden Sie eine im Cache gespeicherte Kopie des Pakets und seiner Abhängigkeiten herunter. Wenn keine im Cache gespeicherte Kopie vorhanden ist, lädt das Remote-Repository das Paket aus der Upstream-Quelle herunter und speichert es im Cache, bevor es Ihnen bereitgestellt wird. Sie können prüfen, ob das Remote-Repository die Pakete aus der Upstream-Quelle abgerufen hat, indem Sie die Liste der Pakete im Repository ansehen.

Bei einem virtuellen Repository sucht Artifact Registry in Upstream-Repositories nach dem angeforderten Paket.

• Upstream-Remote-Repositories laden das angeforderte Paket herunter und speichern es im Cache, wenn keine im Cache gespeicherte Kopie vorhanden ist. Virtuelle Repositories stellen nur angeforderte Pakete bereit, sie speichern sie nicht.
• Wenn Sie eine Version anfordern, die in mehreren Upstream-Repositories verfügbar ist, wählt Artifact Registry ein Upstream-Repository basierend auf den für das virtuelle Repository konfigurierten Prioritätseinstellungen aus.

Betrachten Sie beispielsweise ein virtuelles Repository mit den folgenden Prioritätseinstellungen für Upstream-Repositories:

• main-repo: Priorität auf 100 festgelegt
• secondary-repo1: Priorität auf 80 festgelegt.
• secondary-repo2: Priorität auf 80 festgelegt.
• test-repo: Priorität auf 20 festgelegt.

main-repo hat den höchsten Prioritätswert, daher wird es vom virtuellen Repository immer zuerst durchsucht.

Für secondary-repo1 und secondary-repo2 ist die Priorität auf 80 festgelegt. Wenn ein angefordertes Paket in main-repo nicht verfügbar ist, durchsucht Artifact Registry als Nächstes diese Repositories. Da beide denselben Prioritätswert haben, kann Artifact Registry ein Paket aus einem der beiden Repositories bereitstellen, wenn die Version in beiden verfügbar ist.

test-repo hat den niedrigsten Prioritätswert und stellt ein gespeichertes Artefakt bereit, wenn es in keinem der anderen Upstream-Repositories vorhanden ist.

Weitere Informationen

Standardmäßig installiert Pip stabile Versionen eines Pakets und ignoriert Vorabversionen. PEP 440 definiert die Spezifikation für die Python-Versionskennung , die von Pip zum Parsen von Versionsnummern verwendet wird, einschließlich Vorabversionen.

Wenn Vorabversionen in die Suche von Pip nach einem zu installierenden Paket einbezogen werden sollen, fügen Sie dem Befehl das Flag --pre hinzu.

pip install --pre PACKAGE

Um eine erforderliche Version oder einen Versionsbereich anzugeben, fügen Sie einen Anforderungsspezifizierer hinzu. Sie können die Versionsanforderung direkt in den Befehl einfügen oder eine Anforderungsdateiverwenden.

Dieser Befehl gibt beispielsweise an, dass die Mindestversion von my-package die Entwicklungsversion 1.0.dev0 ist.

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

Stabile Releases gelten als neuer als Vorabversionen. Wenn also Version 1.0 im Repository vorhanden ist, wählt Pip Version 1.0 anstelle einer Vorabversion aus.

Wenn Sie kein Repository angeben, bestimmt die Pip-Konfiguration in pip.conf, wie Pip nach dem Paket sucht.

• Wenn Sie das Artifact Registry-Repository mit der Einstellung index-url konfiguriert haben und keine anderen Paketindizes konfiguriert sind, sucht Pip nur in Ihrem Artifact Registry-Repository nach dem Paket.
• Wenn Sie ein virtuelles Repository verwenden, wählt Artifact Registry anhand der in der Upstream-Richtlinie konfigurierten Prioritäten ein Paket aus, wenn mehrere Upstream-Repositories die angeforderte Paketversion enthalten. Wenn zwei Repositories mit dem Paket dieselbe Priorität haben, stellt Artifact Registry es aus einem der beiden Repositories bereit.
• Wenn Sie Pip mit der Einstellung extra-index-url konfiguriert oder mehrere Paketindizes konfiguriert haben, sucht Pip auf pypi.org und in allen anderen konfigurierten Paketindizes und wählt die neueste Version des Pakets aus.

Sie können die index-url oder extra-index-url Einstellungen in Ihrer Anforderungs Datei überschreiben. Sie können auch Flags für diese Einstellungen in Ihrem Pip-Befehl verwenden. Mit diesem Befehl wird beispielsweise index-url mit einem Artifact Registry-Repository überschrieben.

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

Weitere Informationen zum Installieren von Paketen finden Sie in der Dokumentation zu Python Packaging.

Hinweis: Standardmäßig gibt Pip keine detaillierten Fehlermeldungen zurück. Wenn ein Fehler auftritt, führen Sie den Befehl mit dem -v oder -vv Flag noch einmal aus, um eine detailliertere Ausgabe zu erhalten. Weitere Informationen finden Sie unter Fehlerbehebung bei Python-Paketen.

Pakete und Versionen löschen

Repository-Modi: Standard, Remote

Sie können ein Paket und alle zugehörigen Versionen oder eine bestimmte Version löschen.

• Nachdem Sie ein Paket gelöscht haben, können Sie die Aktion nicht mehr rückgängig machen.
• Bei Remote-Repositories wird nur die im Cache gespeicherte Kopie des Pakets gelöscht. Die Upstream-Quelle ist nicht betroffen. Wenn Sie ein im Cache gespeichertes Paket löschen, lädt Artifact Registry es herunter und speichert es wieder im Cache, wenn das Repository das nächste Mal eine Anfrage für dieselbe Paketversion erhält.

在删除软件包或软件包版本之前，请确认您已在其中告知或解决任何重要依赖项。

如需删除软件包，请按如下所述操作：

控制台

1. 在 Google Cloud 控制台中打开代码库页面。

   Zur Seite „Repositories“

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 选择要删除的软件包。

4. 点击删除。

5. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

替换以下内容：

• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了 默认代码库，则 可以省略此标志以使用默认值。
• LOCATION 是代码库的区域 位置。 使用此标志可查看特定位置的代码库。如果您 配置了默认 位置，则可以省略此标志以使用默认值。

--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。

如需删除软件包的版本，请按如下所述操作：

控制台

1. 在 Google Cloud 控制台中打开代码库页面。

   Zur Seite „Repositories“

2. 在代码库列表中，点击相应代码库。

   软件包页面列出代码库中的软件包。

3. 点击一个软件包以查看它的版本。

4. 选择您要删除的版本。

5. 点击删除。

6. 在确认对话框中，点击删除。

gcloud

运行以下命令：

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

替换以下内容：

• VERSION 是要删除的版本的名称。
• PACKAGE 是代码库中的软件包名称。
• REPOSITORY 是代码库的名称。如果您配置了 默认代码库，则 可以省略此标志以使用默认值。
• LOCATION 是代码库的区域 位置。 使用此标志可查看特定位置的代码库。如果您 配置了默认 位置，则可以省略此标志以使用默认值。

--async 标志会导致命令立即返回，而无需等待正在进行的操作完成。

Nächste Schritte

• Java-Pakete verwalten
• Node.js-Pakete verwalten
• Container-Images verwalten