Faça a gestão de pacotes Python

Esta página descreve como adicionar, ver e eliminar pacotes Python e versões de pacotes.

Antes de começar

  1. Instale e inicialize a CLI Google Cloud.

    É necessária a versão 354.0.0 ou mais recente da Google Cloud CLI para executar comandos para repositórios Python. Pode verificar a versão com o comando:

    gcloud version

  2. Se o repositório de destino não existir, crie um novo repositório de pacotes Python.

  3. Confirme se o Python 3 está instalado. Para ver instruções de instalação, consulte o Google Cloud tutorial de configuração do Python.

  4. (Opcional) Configure as predefinições para os comandos gcloud.

  5. Se estiver a usar a autenticação de conjunto de chaves com credenciais do gcloud, inicie sessão na CLI do Google Cloud com a sua conta de utilizador ou conta de serviço.

Funções necessárias

Para receber as autorizações de que precisa para gerir pacotes, peça ao seu administrador para lhe conceder as seguintes funções do IAM no repositório:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Adicionar pacotes

Modos de repositório: padrão

Quando cria um projeto Python, os ficheiros de distribuição são guardados num subdiretório dist no seu projeto. Em seguida, pode usar o Twine para carregar pacotes para um repositório padrão.

Recomendamos as seguintes práticas recomendadas para os seus pacotes:

  • Use nomes únicos para os seus pacotes privados para que não correspondam aos nomes dos pacotes em pypi.org, especialmente se a sua configuração do pip incluir vários índices de pacotes.
  • Use a especificação do identificador de versão no PEP 440 para os números de versão do pacote. Por predefinição, o pip instala apenas versões estáveis. Usa a especificação do identificador de versão para distinguir as versões estáveis das versões de pré-lançamento e para analisar todos os requisitos para a versão a instalar.

Para adicionar um pacote:

  1. Instale o Twine.

    pip install twine

  2. Altere para o diretório do projeto Python.

  3. Carregue os ficheiros de distribuição para o repositório a partir da subdiretoria dist do projeto. Execute o seguinte comando:

    twine upload dist/*

    Pode especificar um repositório específico com o sinalizador --repository-url.

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

Visualizar pacotes e versões

Modos de repositório: padrão, remoto

Para ver pacotes e versões de pacotes através da Google Cloud consola ou da gcloud:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Na lista de repositórios, clique no repositório adequado.

    A página Pacotes apresenta os pacotes no repositório.

  3. Clique num pacote para ver as versões do pacote.

gcloud

Para listar os pacotes num repositório, execute o seguinte comando:

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

Substitua o seguinte:

  • REPOSITORY é o nome do repositório. Se tiver configurado um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é a localização regional ou multirregional do repositório. Se configurou uma localização predefinida, pode omitir esta flag para usar a predefinição.

Para ver as versões de um pacote, execute o seguinte comando:

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

Substitua o seguinte:

  • PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
  • REPOSITORY é o nome do repositório. Se tiver configurado um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é a localização regional ou multirregional do repositório. Use esta flag para ver repositórios numa localização específica. Se configurou uma localização predefinida, pode omitir esta flag para usar a predefinição.

Para repositórios remotos, a lista devolvida deve incluir todas as dependências diretas e transitivas.

Listar ficheiros

Modos de repositório: padrão, remoto

Pode listar ficheiros num repositório, ficheiros em todas as versões de um pacote especificado ou ficheiros numa versão específica de um pacote.

Para todos os comandos seguintes, pode definir um número máximo de ficheiros a devolver adicionando a flag --limit ao comando.

Para listar todos os ficheiros no projeto, repositório e localização predefinidos quando os valores predefinidos estão configurados:

gcloud artifacts files list

Para listar ficheiros num projeto, num repositório e numa localização especificados, execute o comando:

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

Para listar ficheiros de todas as versões de um pacote específico:

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

Para listar ficheiros de uma versão específica de um pacote:

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

Substitua os seguintes valores:

  • LOCATION: a localização regional ou multirregional do repositório.
  • PROJECT: o seu Google Cloud ID do projeto. Se o ID do projeto contiver dois pontos (:), consulte o artigo Projetos com âmbito de domínio.
  • REPOSITORY: o nome do repositório onde a imagem está armazenada.
  • PACKAGE: o nome do pacote.
  • VERSION: a versão do pacote.

Exemplos

Considere as seguintes informações do pacote:

  • Projeto: my-project
  • Repositório: my-repo
  • Localização do repositório: us-west1
  • Pacote: my-app

O comando seguinte lista todos os ficheiros no repositório my-repo na localização us-west1 no projeto predefinido:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
O seguinte comando lista os ficheiros na versão 1.0 do pacote.

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

Instalar pacotes

Modos de repositório: padrão, remoto e virtual

Use o comando pip para instalar pacotes.

Para instalar a versão estável mais recente de um pacote, execute o comando:

pip install PACKAGE

Para repositórios padrão, transfere um pacote diretamente do repositório.

Para um repositório remoto, transfere uma cópia em cache do pacote e das respetivas dependências. Se não existir uma cópia em cache, o repositório remoto transfere o pacote da origem a montante e coloca-o em cache antes de o disponibilizar. Pode verificar se o repositório remoto obteve os pacotes da origem a montante vendo a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa repositórios a montante para o pacote pedido.

  • Os repositórios remotos a montante transferem e colocam em cache o pacote pedido se não existir uma cópia em cache. Os repositórios virtuais apenas publicam pacotes pedidos e não os armazenam.
  • Se pedir uma versão que esteja disponível em mais do que um repositório a montante, o Artifact Registry escolhe um repositório a montante para usar com base nas definições de prioridade configuradas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes definições de prioridade para repositórios upstream:

  • main-repo: prioridade definida como 100
  • secondary-repo1: prioridade definida como 80.
  • secondary-repo2: prioridade definida como 80.
  • test-repo: prioridade definida como 20.

main-repo tem o valor de prioridade mais elevado, pelo que o repositório virtual é sempre pesquisado primeiro.

Ambos os elementos secondary-repo1 e secondary-repo2 têm a prioridade definida como 80. Se um pacote pedido não estiver disponível em main-repo, o Artifact Registry pesquisa estes repositórios em seguida. Uma vez que ambos têm o mesmo valor de prioridade, o Artifact Registry pode optar por publicar um pacote de qualquer um dos repositórios se a versão estiver disponível em ambos.

test-repo tem o valor de prioridade mais baixo e vai publicar um artefacto armazenado se nenhum dos outros repositórios a montante o tiver.

Informações adicionais

Por predefinição, o pip instala versões estáveis de um pacote e ignora as versões de pré-lançamento. A PEP 440 define a especificação do identificador da versão do Python que os utilizadores do pip usam para analisar os números das versões, incluindo versões de pré-lançamento.

Para incluir versões de pré-lançamento quando o pip pesquisa um pacote para instalar, adicione o flag --pre ao seu comando.

pip install --pre PACKAGE

Para especificar uma versão ou um intervalo de versões obrigatório, inclua um especificador de requisito. Pode incluir o requisito de versão diretamente no comando ou usar um ficheiro de requisitos.

Por exemplo, este comando especifica que a versão mínima do my-package é a versão de desenvolvimento 1.0.dev0.

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

As versões estáveis são consideradas mais recentes do que as pré-versões. Por isso, se a versão 1.0 estiver no repositório, o pip escolhe a versão 1.0 em vez de uma versão de pré-lançamento.

Se não especificar um repositório, a configuração do pip em pip.conf determina como o pip procura o pacote.

  • Se configurou o repositório do Artifact Registry com a definição index-url e não estiverem configurados outros índices de pacotes, o pip só pesquisa o seu repositório do Artifact Registry para o pacote.
  • Se estiver a usar um repositório virtual, o Artifact Registry usa as prioridades configuradas na política a montante para escolher um pacote quando vários repositórios a montante têm a versão do pacote pedida. Se dois repositórios com o pacote tiverem a mesma prioridade, o Artifact Registry disponibiliza-o a partir de qualquer um dos repositórios.
  • Se configurou o pip com a definição extra-index-url ou se configurou vários índices de pacotes, o pip procura pypi.org e quaisquer outros índices de pacotes configurados, e escolhe a versão mais recente do pacote.

Pode substituir as definições de index-url ou extra-index-url no ficheiro de requisitos. Também pode usar flags para estas definições no comando pip. Por exemplo, este comando substitui index-url por um repositório do Artifact Registry.

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

Para mais informações sobre a instalação de pacotes, consulte a documentação de embalagens Python.

Eliminar pacotes e versões

Modos de repositório: padrão, remoto

Pode eliminar um pacote e todas as respetivas versões ou eliminar uma versão específica.

  • Depois de eliminar um pacote, não pode anular a ação.
  • Para repositórios remotos, apenas a cópia em cache do pacote é eliminada. A fonte a montante não é afetada. Se eliminar um pacote em cache, o Artifact Registry transfere-o e coloca-o novamente em cache da próxima vez que o repositório receber um pedido para a mesma versão do pacote.

Antes de eliminar um pacote ou uma versão do pacote, verifique se comunicou ou resolveu quaisquer dependências importantes do mesmo.

Para eliminar um pacote:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Na lista de repositórios, clique no repositório adequado.

    A página Pacotes apresenta os pacotes no repositório.

  3. Selecione o pacote que quer eliminar.

  4. Clique em ELIMINAR.

  5. Clique em ELIMINAR na caixa de diálogo de confirmação.

gcloud

Execute o seguinte comando:

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

Substitua o seguinte:

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se configurou um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é a localização regional ou multirregional do repositório. Use esta flag para ver repositórios numa localização específica. Se tiver configurado uma localização predefinida, pode omitir esta flag para usar a predefinição.

A flag --async faz com que o comando seja devolvido imediatamente, sem aguardar a conclusão da operação em curso.

Para eliminar versões de um pacote:

Consola

  1. Abra a página Repositórios na Google Cloud consola.

    Abra a página Repositórios

  2. Na lista de repositórios, clique no repositório adequado.

    A página Pacotes apresenta os pacotes no repositório.

  3. Clique num pacote para ver as versões desse pacote.

  4. Selecione as versões que quer eliminar.

  5. Clique em ELIMINAR.

  6. Clique em ELIMINAR na caixa de diálogo de confirmação.

gcloud

Execute o seguinte comando:

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

Substitua o seguinte:

  • VERSION é o nome da versão a eliminar.
  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se configurou um repositório predefinido, pode omitir esta flag para usar o predefinido.
  • LOCATION é a localização regional ou multirregional do repositório. Use esta flag para ver repositórios numa localização específica. Se tiver configurado uma localização predefinida, pode omitir esta flag para usar a predefinição.

A flag --async faz com que o comando seja devolvido imediatamente, sem aguardar a conclusão da operação em curso.

O que se segue?