Administra paquetes de Python

Artifact Registry te permite almacenar, administrar y controlar las versiones de los paquetes de Python en repositorios con formato de Python. Puedes subir distribuciones con Twine, inspeccionar versiones y archivos almacenados, instalar dependencias con pip y borrar paquetes no utilizados.

Antes de comenzar

  1. Instala y, luego, inicializa Google Cloud CLI.

    Se requiere la versión 354.0.0 o posterior de Google Cloud CLI para ejecutar comandos para repositorios de Python. Puedes verificar la versión con el siguiente comando:

    gcloud version

  2. Si el repositorio de destino no existe, crea un nuevo repositorio de paquetes de Python.

  3. Verifica que Python 3 esté instalado. Para obtener instrucciones de instalación, consulta elGoogle Cloud instructivo para configurar Python.

  4. (Opcional) Configura valores predeterminados para los comandos de gcloud.

  5. Si usas la autenticación de llavero con credenciales de gcloud, accede a Google Cloud CLI con tu cuenta de usuario o cuenta de servicio.

Roles obligatorios

Para obtener los permisos que necesitas para administrar paquetes, pídele a tu administrador que te otorgue los siguientes roles de IAM en el repositorio:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Agrega paquetes

Modos de repositorio: estándar

Cuando compilas un proyecto de Python, los archivos de distribución se guardan en un subdirectorio dist de tu proyecto. Luego, puedes usar Twine para subir paquetes a un repositorio estándar.

Te recomendamos que sigas estas prácticas recomendadas para tus paquetes:

  • Usa nombres únicos para tus paquetes privados, de modo que no coincidan con los nombres de paquetes en pypi.org, en especial si tu configuración de pip incluye varios índices de paquetes.
  • Usa la especificación del identificador de versión en PEP 440 para los números de versión de tu paquete. De forma predeterminada, pip solo instala versiones estables. Utiliza la especificación del identificador de versión para distinguir las versiones estables de las versiones previas al lanzamiento y para analizar cualquier requisito de la versión que se instalará.

Para agregar un paquete, haz lo siguiente:

  1. Instala Twine.

    pip install twine

  2. Cambia al directorio de tu proyecto de Python.

  3. Sube los archivos de distribución al repositorio desde el subdirectorio dist del proyecto. Ejecuta el comando siguiente:

    twine upload dist/*

    Puedes especificar un repositorio en particular con la marca --repository-url.

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

Visualiza paquetes y versiones

Modos de repositorio: estándar, remoto

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

控制台

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

    Abrir la página repositorios

  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 是代码库的区域 位置。 使用此标志可查看特定位置的代码库。 如果您配置了默认 位置，则可以省略此标志以使用默认值。

En el caso de los repositorios remotos, la lista que se devuelve debe incluir todas las dependencias directas y transitivas.

Creando lista de archivos

Modos de repositorio: estándar, remoto

Puedes enumerar los archivos de un repositorio, los archivos de todas las versiones de un paquete especificado o los archivos de una versión específica de un paquete.

En todos los siguientes comandos, puedes establecer una cantidad máxima de archivos que se devolverán agregando la marca --limit al comando.

Para enumerar todos los archivos en el proyecto, el repositorio y la ubicación predeterminados cuando los valores predeterminados están configurados, haz lo siguiente:

gcloud artifacts files list

Para enumerar los archivos en un proyecto, un repositorio y una ubicación especificados, ejecuta el siguiente comando:

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

Para enumerar los archivos de todas las versiones de un paquete específico, haz lo siguiente:

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

Para enumerar los archivos de una versión de paquete específica, haz lo siguiente:

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

Reemplaza los siguientes valores:

  • LOCATION: Es la ubicación regional del repositorio.
  • PROJECT: Es el Google Cloud ID del proyecto.
  • REPOSITORY: Es el nombre del repositorio en el que se almacena la imagen.
  • PACKAGE: Es el nombre del paquete.
  • VERSION: Es la versión del paquete.

Ejemplos

Considera la siguiente información del paquete:

  • Proyecto: my-project
  • Repositorio: my-repo
  • Ubicación del repositorio:
  • Paquete: my-app

El siguiente comando enumera todos los archivos del repositorio my-repo en la ubicación dentro del proyecto predeterminado:

gcloud artifacts files list \
    --location= \
    --repository=my-repo
El siguiente comando enumera los archivos en la versión 1.0 del paquete.

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

Instala paquetes

Modos de repositorio: estándar, remoto y virtual

Usa el comando pip para instalar paquetes.

Para instalar la versión estable más reciente de un paquete, ejecuta el siguiente comando:

pip install PACKAGE

En el caso de los repositorios estándar, descargas un paquete directamente desde el repositorio.

En el caso de un repositorio remoto, descargas una copia almacenada en caché del paquete y sus dependencias. Si no existe una copia almacenada en caché, el repositorio remoto descarga el paquete de la fuente upstream y lo almacena en caché antes de entregártelo. Para verificar que el repositorio remoto recuperó los paquetes de la fuente upstream, consulta la lista de paquetes en el repositorio.

En el caso de un repositorio virtual, Artifact Registry busca el paquete solicitado en los repositorios upstream.

  • Los repositorios remotos upstream descargarán y almacenarán en caché el paquete solicitado si no existe una copia en caché. Los repositorios virtuales solo entregan los paquetes solicitados, no los almacenan.
  • Si solicitas una versión que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream para usarlo según la configuración de prioridad establecida para el repositorio virtual.

Por ejemplo, considera un repositorio virtual con los siguientes parámetros de configuración de prioridad para los repositorios upstream:

  • main-repo: La prioridad se estableció en 100
  • secondary-repo1: La prioridad se estableció en 80.
  • secondary-repo2: La prioridad se estableció en 80.
  • test-repo: La prioridad se estableció en 20.

main-repo tiene el valor de prioridad más alto, por lo que el repositorio virtual siempre lo busca primero.

Tanto secondary-repo1 como secondary-repo2 tienen la prioridad establecida en 80. Si un paquete solicitado no está disponible en main-repo, Artifact Registry buscará en estos repositorios a continuación. Dado que ambos tienen el mismo valor de prioridad, Artifact Registry puede optar por entregar un paquete desde cualquiera de los repositorios si la versión está disponible en ambos.

test-repo tiene el valor de prioridad más bajo y publicará un artefacto almacenado si ninguno de los otros repositorios upstream lo tiene.

Información adicional

De forma predeterminada, pip instala versiones estables de un paquete y omite las versiones previas al lanzamiento. La PEP 440 define la especificación del identificador de versión de Python que pip usa para analizar los números de versión, incluidas las versiones preliminares.

Para incluir versiones previas al lanzamiento cuando pip busca un paquete para instalar, agrega la marca --pre a tu comando.

pip install --pre PACKAGE

Para especificar una versión o un rango de versiones requeridos, incluye un especificador de requisitos. Puedes incluir el requisito de versión directamente en el comando o usar un archivo de requisitos.

Por ejemplo, este comando especifica que la versión mínima de my-package es la versión de desarrollo 1.0.dev0.

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

Las versiones estables se consideran más recientes que las versiones preliminares, por lo que, si la versión 1.0 está en el repositorio, pip elegirá la versión 1.0 en lugar de una versión preliminar.

Si no especificas un repositorio, la configuración de pip en pip.conf determina cómo pip busca el paquete.

  • Si configuraste el repositorio de Artifact Registry con el parámetro de configuración index-url y no se configuraron otros índices de paquetes, pip solo buscará el paquete en tu repositorio de Artifact Registry.
  • Si usas un repositorio virtual, Artifact Registry usa las prioridades configuradas en la política upstream para elegir un paquete cuando varios repositorios upstream tienen la versión del paquete solicitada. Si dos repositorios con el paquete tienen la misma prioridad, Artifact Registry lo entrega desde cualquiera de los dos.
  • Si configuraste pip con el parámetro de configuración extra-index-url o si configuraste varios índices de paquetes, pip busca en pypi.org y en cualquier otro índice de paquetes configurado, y elige la versión más reciente del paquete.

Puedes anular la configuración de index-url o extra-index-url en tu archivo de requisitos. También puedes usar marcas para estos parámetros de configuración en tu comando pip. Por ejemplo, este comando reemplaza index-url por un repositorio de Artifact Registry.

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

Para obtener más información sobre la instalación de paquetes, consulta la documentación de Python Packaging.

Borra paquetes y versiones

Modos de repositorio: estándar, remoto

Puedes borrar un paquete y todas sus versiones, o bien borrar una versión específica.

  • Una vez que borres un paquete, no podrás deshacer la acción.
  • En el caso de los repositorios remotos, solo se borra la copia almacenada en caché del paquete. La fuente upstream no se ve afectada. Si borras un paquete almacenado en caché, Artifact Registry lo volverá a descargar y almacenar en caché la próxima vez que el repositorio reciba una solicitud para la misma versión del paquete.

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

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

控制台

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

    Abrir la página repositorios

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

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

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

  4. 点击删除。

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

gcloud

运行以下命令：

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

替换以下内容：

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

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

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

控制台

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

    Abrir la página repositorios

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

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

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

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

  5. 点击删除。

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

gcloud

运行以下命令：

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

替换以下内容：

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

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

¿Qué sigue?