Administra paquetes de Python

En esta página, se describe cómo agregar, ver y borrar versiones de paquetes y paquetes de Python.

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 repositorio de paquetes de Python nuevo.

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

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

5. Si usas la autenticación de keyring 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:

• Ver paquetes o archivos en paquetes: Lector de Artifact Registry (roles/artifactregistry.reader)
• Descargar o instalar paquetes: Lector de Artifact Registry (roles/artifactregistry.reader)
• Agregar paquetes a un repositorio: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Borrar paquetes: Administrador del repositorio de Artifact Registry (roles/artifactregistry.repoAdmin)

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 las siguientes prácticas recomendadas para tus paquetes:

• Usa nombres únicos para tus paquetes privados de modo que no coincidan con los nombres de paquete 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. Usa la especificación del identificador de versión para distinguir las versiones estables de las versiones previas al lanzamiento y analizar cualquier requisito para 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/*
   

Nota: De forma predeterminada, Twine no muestra mensajes de error detallados. Si encuentras un error, vuelve a ejecutar el comando de Twine con la marca --verbose para obtener un mensaje más detallado. Consulta Solución de problemas de paquetes de Python para obtener información sobre algunos códigos de error comunes.

Visualiza paquetes y versiones

Modos de repositorio: estándar, remoto

Para ver los paquetes y sus versiones con la Google Cloud consola o gcloud, haz lo siguiente:

Console

1. Abre la página Repositorios en la consola de Google Cloud .

   Abrir la página repositorios

2. En la lista de repositorios, haz clic en el repositorio correspondiente.

   En la página Paquetes, se enumeran los paquetes del repositorio.

3. Haz clic en un paquete para ver las versiones de este.

gcloud

Para generar una lista de los paquetes en un repositorio, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
• LOCATION es la ubicación regional o multirregional del repositorio. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

Para ver las versiones de un paquete, ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• PACKAGE es el ID del paquete o el identificador completamente calificado del paquete.
• REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
• LOCATION es la ubicación regional o multirregional del repositorio. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

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

Enumera archivos

Modos de repositorio: estándar, remoto

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

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

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

gcloud artifacts files list

Para enumerar 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 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 archivos de una versión específica de un paquete, haz lo siguiente:

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

Reemplaza los siguientes valores:

• LOCATION: la ubicación regional o multirregional del repositorio.
• PROJECT: El ID de tu Google Cloud proyecto. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con alcance de dominio.
• REPOSITORY: El nombre del repositorio en el que se almacena la imagen.
• PACKAGE: El nombre del paquete.
• VERSION: La versión del paquete.

Ejemplos

Considera la siguiente información del paquete:

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

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

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

El siguiente comando enumera los archivos de la versión 1.0 del paquete.

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

Instala paquetes

Modos de repositorio: estándar, remoto, 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 superior y lo almacena en caché antes de entregártelo. Puedes verificar que el repositorio remoto recuperó los paquetes de la fuente superior si ves la lista de paquetes en el repositorio.

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

• Los repositorios remotos superiores descargarán y almacenarán en caché el paquete solicitado si no existe una copia almacenada 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 superior, Artifact Registry elige un repositorio superior para usar según la configuración de prioridad configurada para el repositorio virtual.

Por ejemplo, considera un repositorio virtual con la siguiente configuración de prioridad para los repositorios superiores:

• main-repo: Prioridad establecida en 100
• secondary-repo1: Prioridad establecida en 80.
• secondary-repo2: Prioridad establecida en 80.
• test-repo: Prioridad establecida 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 busca estos repositorios a continuación. Como ambos tienen el mismo valor de prioridad, Artifact Registry puede elegir 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 entregará un artefacto almacenado si ninguno de los otros repositorios superiores lo tiene.

Información adicional

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

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

pip install --pre PACKAGE

Para especificar una versión o un rango de versiones obligatorios, incluye un especificador de requisitos. Puedes incluir el requisito de versión directamente en tu 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 previas al lanzamiento, 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 previa al lanzamiento.

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 index-url y no se configuraron otros índices de paquetes, pip solo busca el paquete en tu repositorio de Artifact Registry.
• Si usas un repositorio virtual, Artifact Registry usa las prioridades configuradas en la política superior para elegir un paquete cuando varios repositorios superiores tienen la versión de paquete solicitada. Si dos repositorios con el paquete tienen la misma prioridad, Artifact Registry lo entrega desde cualquiera de los repositorios.
• Si configuraste pip con el parámetro extra-index-url o si configuraste varios índices de paquetes, pip busca pypi.org y 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 en tu comando de pip. Por ejemplo, este comando anula index-url con 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.

Nota: De forma predeterminada, pip no muestra mensajes de error detallados. Si encuentras un error, vuelve a ejecutar el comando con la marca -v o -vv para obtener un resultado más detallado. Consulta Solución de problemas de paquetes de Python para obtener más información.

Borra paquetes y versiones

Modos de repositorio: estándar, remoto

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

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

Antes de borrar un paquete o una versión de un paquete, verifica que se haya comunicado o abordado cualquier dependencia importante en este.

Para borrar un paquete, haz lo siguiente:

Console

1. Abre la página Repositorios en la consola de Google Cloud .

   Abrir la página repositorios

2. En la lista de repositorios, haz clic en el repositorio correspondiente.

   En la página Paquetes, se enumeran los paquetes del repositorio.

3. Selecciona el paquete que quieres borrar.

4. Haz clic en BORRAR.

5. En el cuadro de diálogo de confirmación, haz clic en BORRAR.

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• PACKAGE es el nombre del paquete en el repositorio.
• REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
• LOCATION es la ubicación regional o multirregional del repositorio. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

La marca --async hace que el comando se muestre de inmediato, sin necesidad de esperar a que se complete la operación en curso.

Para borrar versiones de un paquete, haz lo siguiente:

Console

1. Abre la página Repositorios en la consola de Google Cloud .

   Abrir la página repositorios

2. En la lista de repositorios, haz clic en el repositorio correspondiente.

   En la página Paquetes, se enumeran los paquetes del repositorio.

3. Haz clic en un paquete para ver las versiones de este.

4. Selecciona las versiones que quieres borrar.

5. Haz clic en BORRAR.

6. En el cuadro de diálogo de confirmación, haz clic en BORRAR.

gcloud

Ejecuta el siguiente comando:

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

Reemplaza lo siguiente:

• VERSION es el nombre de la versión que se borrará.
• PACKAGE es el nombre del paquete en el repositorio.
• REPOSITORY es el nombre del repositorio. Si configuraste un repositorio predeterminado, puedes omitir esta marca para usarlo.
• LOCATION es la ubicación regional o multirregional del repositorio. Usa esta marca para ver los repositorios en una ubicación específica. Si configuraste una ubicación predeterminada, puedes omitir esta marca para usarla.

La marca --async hace que el comando se muestre de inmediato, sin necesidad de esperar a que se complete la operación en curso.

¿Qué sigue?

• Obtén información para administrar paquetes de Java.
• Obtén información para administrar paquetes de Node.js.
• Obtén información para administrar imágenes de contenedor.
• Descarga archivos individuales dentro de un paquete.