Gestionar paquetes de Python

En esta página se describe cómo añadir, ver y eliminar paquetes y versiones de paquetes de Python.

Antes de empezar

1. Instala e inicializa la CLI de Google Cloud.

   Para ejecutar comandos de repositorios de Python, se necesita la versión 354.0.0 o una posterior de la CLI de Google Cloud. Puedes consultar la versión con el comando:

   gcloud version
   

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

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

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

5. Si usas la autenticación de llavero de claves con credenciales de gcloud, inicia sesión en la CLI de Google Cloud con tu cuenta de usuario o tu cuenta de servicio.

Roles obligatorios

Para obtener los permisos que necesitas para gestionar paquetes, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en el repositorio:

• Para ver los paquetes o los archivos de los paquetes, sigue estos pasos: Lector de Artifact Registry (roles/artifactregistry.reader)
• Descargar o instalar paquetes: Lector de Artifact Registry (roles/artifactregistry.reader)
• Añadir paquetes a un repositorio: Escritor de Artifact Registry (roles/artifactregistry.writer)
• Eliminar paquetes: Administrador de repositorios de Artifact Registry (roles/artifactregistry.repoAdmin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Añadir 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. Después, 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 para que no coincidan con los nombres de los paquetes de pypi.org, sobre todo si tu configuración de pip incluye varios índices de paquetes.
• Usa la especificación del identificador de versión de 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 preliminares y para analizar los requisitos de la versión que se va a instalar.

Para añadir un paquete, sigue estos pasos:

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 siguiente comando:

   twine upload dist/*
   

   Puedes especificar un repositorio concreto con la marca --repository-url.

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

Ver paquetes y versiones

Modos de repositorio: estándar y remoto

Para ver los paquetes y las versiones de los paquetes mediante la consola Google Cloud o gcloud, sigue estos pasos:

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

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

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

Mostrar archivos

Modos de repositorio: estándar y 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 concreta de un paquete.

En todos los comandos siguientes, puedes definir un número máximo de archivos que se devuelvan añadiendo la marca --limit al comando.

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

gcloud artifacts files list

Para enumerar los archivos de un proyecto, un repositorio y una ubicación específicos, 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 específica de un paquete, sigue estos pasos:

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

Sustituye los siguientes valores:

• LOCATION: la ubicación regional o multirregional del repositorio.
• PROJECT: tu Google Cloud ID de proyecto. Si el ID de tu proyecto contiene dos puntos (:), consulta Proyectos con ámbito 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

Tenga en cuenta la siguiente información del paquete:

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

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

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

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

Instalar 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 los repositorios estándar, los paquetes se descargan directamente del repositorio.

En el caso de un repositorio remoto, se descarga una copia 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 proporcionártelo. Para comprobar que el repositorio remoto ha obtenido los paquetes de la fuente de nivel superior, consulta la lista de paquetes del 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 sirven los paquetes solicitados, no los almacenan.
• Si solicita una versión que está disponible en más de un repositorio upstream, Artifact Registry elige un repositorio upstream que se va a usar en función de los ajustes de prioridad configurados para el repositorio virtual.

Por ejemplo, supongamos que tiene un repositorio virtual con los siguientes ajustes de prioridad para los repositorios upstream:

• main-repo: prioridad definida como 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 80. Si un paquete solicitado no está disponible en main-repo, Artifact Registry buscará en estos repositorios. Como ambos tienen el mismo valor de prioridad, Artifact Registry puede elegir servir un paquete de cualquiera de los dos repositorios si la versión está disponible en ambos.

test-repo tiene el valor de prioridad más bajo y servirá 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 e ignora las versiones preliminares. La PEP 440 define la especificación del identificador de versión de Python que usan los usuarios de pip para analizar los números de versión, incluidas las versiones preliminares.

Para incluir versiones preliminares cuando pip busque un paquete para instalarlo, la marca --pre en tu comando.

pip install --pre PACKAGE

Para especificar una versión o un intervalo de versiones obligatorios, incluye un especificador de requisito. 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 ningún repositorio, la configuración de pip en pip.conf determina cómo busca pip el paquete.

• Si ha configurado el repositorio de Artifact Registry con el ajuste index-url y no se ha configurado ningún otro índice de paquetes, pip solo buscará el paquete en su 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 sirve desde cualquiera de los dos.
• Si has configurado pip con el ajuste extra-index-url o si has configurado 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 los ajustes de index-url o extra-index-url en el archivo requirements. También puedes usar marcas para estos ajustes en tu comando pip. Por ejemplo, este comando sustituye 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 cómo instalar paquetes, consulta la documentación de empaquetado de Python.

Eliminar paquetes y versiones

Modos de repositorio: estándar y remoto

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

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

Antes de eliminar un paquete o una versión de un paquete, comprueba que has comunicado o resuelto las dependencias importantes que tenga.

Para eliminar un paquete, sigue estos pasos:

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

Para eliminar versiones de un paquete, sigue estos pasos:

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

Siguientes pasos

• Información sobre cómo gestionar paquetes de Java
• Más información sobre cómo gestionar paquetes de Node.js
• Consulta cómo gestionar imágenes de contenedor.
• Descargar archivos concretos de un paquete