Gérer les packages Python

Cette page explique comment ajouter, afficher et supprimer des packages Python et des versions de package.

Avant de commencer

  1. Installez et initialize la Google Cloud CLI.

    Google Cloud CLI version 354.0.0 ou ultérieure est nécessaire pour exécuter des commandes pour les dépôts Python. Vous pouvez vérifier la version à l'aide de la commande suivante:

    gcloud version
    
  2. Si le dépôt cible n'existe pas, créez un dépôt de packages Python.

  3. Vérifiez que Python 3 est installé. Pour obtenir des instructions d'installation, consultez le tutoriel Google Cloud sur la configuration de Python.

  4. (Facultatif) Configurez des valeurs par défaut pour les commandes gcloud.

  5. Si vous utilisez l'authentification par trousseau avec des identifiants gcloud, connectez-vous à Google Cloud CLI à l'aide de votre compte utilisateur ou de votre compte de service.

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les packages, demandez à votre administrateur de vous attribuer les rôles IAM suivants sur le dépôt:

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Ajouter des packages

Modes de dépôt: standard

Lorsque vous compilez un projet Python, les fichiers de distribution sont enregistrés dans un sous-répertoire dist de votre projet. Vous pouvez ensuite utiliser Twine pour importer des packages dans un dépôt standard.

Nous vous recommandons de suivre les bonnes pratiques suivantes pour vos packages:

  • Utilisez des noms uniques pour vos packages privés afin qu'ils ne correspondent pas à ceux de pypi.org, en particulier si votre configuration pip comprend plusieurs index de packages.
  • Utilisez la spécification d'identifiant de version dans PEP 440 pour les numéros de version de vos packages. Par défaut, pip n'installe que les versions stables. Il utilise la spécification de l'identifiant de version pour distinguer les versions stables des versions préliminaires et pour analyser les exigences que la version doit installer.

Pour ajouter un package :

  1. Installez Twine.

    pip install twine
    
  2. Accédez au répertoire de votre projet Python.

  3. Importez les fichiers de distribution dans le dépôt à partir du sous-répertoire dist du projet. Exécutez la commande suivante :

    twine upload dist/*
    

    Vous pouvez spécifier un dépôt particulier à l'aide de l'option --repository-url.

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

Afficher des packages et des versions

Modes de dépôt:standard, distant

Pour afficher des packages et des versions de package à l'aide de la console Google Cloud ou de gcloud, procédez comme suit:

Console

  1. Ouvrez la page Dépôts de la console Google Cloud.

    Ouvrir la page "Dépôts"

  2. Dans la liste des dépôts, cliquez sur le dépôt approprié.

    La page Packages répertorie les packages du dépôt.

  3. Cliquez sur un package pour afficher ses versions.

gcloud

Pour répertorier les packages d'un dépôt, exécutez la commande suivante :

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

  • REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.
  • LOCATION est un emplacement régional ou multirégional. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.

Pour afficher les versions d'un package, exécutez la commande suivante :

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

Où :

  • PACKAGE est l'ID ou l'identifiant complet du package.
  • REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
  • LOCATION est un emplacement régional ou multirégional. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.

Pour les dépôts distants, la liste renvoyée doit inclure toutes les dépendances directes et transitives.

Liste des fichiers

Modes de dépôt:standard, distant

Vous pouvez répertorier les fichiers d'un dépôt, les fichiers de toutes les versions d'un package spécifié ou les fichiers d'une version spécifique d'un package.

Pour toutes les commandes suivantes, vous pouvez définir un nombre maximal de fichiers à renvoyer en ajoutant l'option --limit à la commande.

Pour répertorier tous les fichiers du projet, du dépôt et de l'emplacement par défaut lorsque les valeurs par défaut sont configurées:

gcloud artifacts files list

Pour répertorier les fichiers d'un projet, d'un dépôt et d'un emplacement spécifiés, exécutez la commande suivante:

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

Pour répertorier les fichiers de toutes les versions d’un package spécifique:

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

Pour répertorier les fichiers d’une version de package spécifique:

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

Remplacez les valeurs suivantes :

  • LOCATION est l'emplacement régional ou multirégional du dépôt.
  • PROJECT est l'ID de votre projet Google Cloud. Si l'ID du projet contient le signe deux-points (:), consultez la section Projets à l'échelle du domaine.
  • REPOSITORY est le nom du dépôt où l'image est stockée.
  • PACKAGE est le nom du package.
  • VERSION est la version du package.

Examples

Tenez compte des informations suivantes sur les packages:

  • Projet : my-project
  • Dépôt: my-repo
  • Emplacement du dépôt : us-central1
  • Colis: my-app

La commande suivante répertorie tous les fichiers du dépôt my-repo à l'emplacement us-central1 dans le projet par défaut:

gcloud artifacts files list \
    --location=us-central1 \
    --repository=my-repo
La commande suivante répertorie les fichiers de la version 1.0 du package.

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

Installer des packages

Modes de dépôt:standard, distant, virtuel

Utilisez la commande pip pour installer des packages.

Pour installer la dernière version stable d’un package, exécutez la commande suivante:

pip install PACKAGE

Pour les dépôts standards, vous téléchargez un package directement à partir du dépôt.

Pour un dépôt distant, vous devez télécharger une copie mise en cache du package et de ses dépendances. Si aucune copie en cache n'existe, le dépôt distant télécharge le package à partir de la source en amont et le met en cache avant de vous le diffuser. Pour vérifier que le dépôt distant a bien récupéré les packages depuis la source en amont, affichez la liste des packages du dépôt.

Pour un dépôt virtuel, Artifact Registry recherche le package demandé dans les dépôts en amont.

  • Les dépôts distants en amont téléchargent et mettent en cache le package demandé si aucune copie mise en cache n'existe. Les référentiels virtuels ne diffusent que les packages demandés, ils ne les stockent pas.
  • Si vous demandez une version disponible dans plusieurs dépôts en amont, Artifact Registry choisit un dépôt en amont à utiliser en fonction des paramètres de priorité configurés pour le dépôt virtuel.

Par exemple, prenons un dépôt virtuel avec les paramètres de priorité suivants pour les dépôts en amont:

  • main-repo: priorité définie sur 100
  • secondary-repo1: priorité définie sur 80.
  • secondary-repo2: priorité définie sur 80.
  • test-repo: priorité définie sur 20.

main-repo présente la valeur de priorité la plus élevée. Le dépôt virtuel la recherche donc toujours en premier.

La priorité de secondary-repo1 et secondary-repo2 est définie sur 80. Si un package demandé n'est pas disponible dans main-repo, Artifact Registry recherche ensuite ces dépôts. Étant donné qu'ils ont tous les deux la même valeur de priorité, Artifact Registry peut choisir de diffuser un package à partir de l'un ou l'autre des dépôts si la version est disponible dans les deux.

test-repo présente la valeur de priorité la plus faible et diffuse un artefact stocké si aucun des autres dépôts en amont ne l'a.

Informations supplémentaires

Par défaut, pip installe des versions stables d'un package et ignore les versions préliminaires. PEP 440 définit la spécification de l'identifiant de version Python, qui permet aux utilisateurs pip d'analyser les numéros de version, y compris les versions préliminaires.

Pour inclure des versions préliminaires lorsque pip recherche un package à installer, ajoutez l'option --pre à votre commande.

pip install --pre PACKAGE

Pour spécifier une version ou une plage de versions requise, incluez un spécificateur d'exigence. Vous pouvez inclure l'exigence de version directement dans votre commande ou utiliser un fichier d'exigences.

Par exemple, cette commande spécifie que la version minimale de my-package est la version de développement 1.0.dev0.

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

Les versions stables sont considérées comme plus récentes que les versions préliminaires. Par conséquent, si la version 1.0 se trouve dans le dépôt, pip choisira la version 1.0 plutôt qu'une version préliminaire.

Si vous ne spécifiez pas de dépôt, la configuration pip dans pip.conf détermine la manière dont pip recherche le package.

  • Si vous avez configuré le dépôt Artifact Registry avec le paramètre index-url et qu'aucun autre index de packages n'est configuré, pip ne recherche le package que dans votre dépôt Artifact Registry.
  • Si vous utilisez un dépôt virtuel, Artifact Registry utilise les priorités configurées dans la règle en amont pour choisir un package lorsque plusieurs dépôts en amont disposent de la version de package demandée. Si deux dépôts contenant le package ont la même priorité, Artifact Registry le diffuse à partir de l'un ou l'autre des dépôts.
  • Si vous avez configuré pip avec le paramètre extra-index-url ou si vous avez configuré plusieurs index de packages, pip recherche pypi.org et tout autre index de package configuré, puis choisit la dernière version du package.

Vous pouvez ignorer les paramètres index-url ou extra-index-url dans le fichier des exigences. Vous pouvez également utiliser des options pour ces paramètres dans votre commande pip. Par exemple, cette commande remplace index-url par un dépôt Artifact Registry.

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

Pour en savoir plus sur l'installation des packages, consultez la documentation sur les packages Python.

Supprimer des packages et des versions

Modes de dépôt:standard, distant

Vous pouvez supprimer un package et toutes ses versions, ou supprimer une version spécifique.

  • La suppression d'un package est irréversible.
  • Pour les dépôts distants, seule la copie mise en cache du package est supprimée. La source en amont n'est pas affectée. Si vous supprimez un package mis en cache, Artifact Registry le téléchargera et le mettra à nouveau en cache la prochaine fois que le dépôt recevra une requête pour la même version de package.

Avant de supprimer un package ou une version de package, vérifiez que vous avez communiqué ou résolu toute dépendance importante associée.

Pour supprimer un package, procédez comme suit :

Console

  1. Ouvrez la page Dépôts de la console Google Cloud.

    Ouvrir la page "Dépôts"

  2. Dans la liste des dépôts, cliquez sur le dépôt approprié.

    La page Packages répertorie les packages du dépôt.

  3. Sélectionnez le package que vous souhaitez supprimer.

  4. Cliquez sur SUPPRIMER.

  5. Dans la boîte de dialogue de confirmation, cliquez sur SUPPRIMER.

gcloud

Exécutez la commande suivante :

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

  • PACKAGE est le nom du package dans le dépôt.
  • REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
  • LOCATION est un emplacement régional ou multirégional. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.
  • --async renvoie immédiatement une réponse, sans attendre la fin de l'opération en cours.

Pour supprimer des versions d'un package, procédez comme suit :

Console

  1. Ouvrez la page Dépôts de la console Google Cloud.

    Ouvrir la page "Dépôts"

  2. Dans la liste des dépôts, cliquez sur le dépôt approprié.

    La page Packages répertorie les packages du dépôt.

  3. Cliquez sur un package pour afficher ses versions.

  4. Sélectionnez les versions que vous souhaitez supprimer.

  5. Cliquez sur SUPPRIMER.

  6. Dans la boîte de dialogue de confirmation, cliquez sur SUPPRIMER.

gcloud

Exécutez la commande suivante :

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

  • PACKAGE est le nom du package dans le dépôt.
  • REPOSITORY est le nom du dépôt. Si vous avez configuré un dépôt par défaut, vous pouvez omettre cet indicateur pour utiliser le dépôt par défaut.
  • LOCATION est un emplacement régional ou multirégional. Utilisez cette option pour afficher les dépôts dans un emplacement spécifique. Si vous avez configuré un emplacement par défaut, vous pouvez omettre cette option pour utiliser la valeur par défaut.
  • --async est immédiatement renvoyé, sans attendre la fin de l'opération en cours.

Étapes suivantes