Gerenciar pacotes do Python

Nesta página, descrevemos como adicionar, visualizar e excluir pacotes e versões do pacote Python.

Antes de começar

  1. Instale e inicialize a Google Cloud CLI.

    A versão 354.0.0 ou mais recente da Google Cloud CLI é necessária para executar comandos de repositórios Python. Verifique a versão com o comando:

    gcloud version

  2. Crie um novo repositório de pacotes do Python, caso ele não exista.

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

  4. (Opcional) Configure padrões para comandos gcloud.

  5. Se você estiver usando a autenticação de chave com credenciais do gcloud, faça login na Google Cloud CLI com sua conta de usuário ou conta de serviço.

Funções exigidas

Para receber as permissões necessárias para gerenciar pacotes, peça ao administrador para conceder a você os seguintes papéis de IAM no repositório:

Para mais informações sobre como conceder papéis, consulte Gerenciar o acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Como adicionar pacotes

Modos de repositório: padrão

Quando você cria um projeto do Python, os arquivos de distribuição são salvos em um subdiretório dist em seu projeto. Em seguida, use o Twine para fazer upload de pacotes para um repositório padrão.

Recomendamos as seguintes práticas para seus pacotes:

  • Use nomes exclusivos para seus pacotes privados para que eles não correspondam a nomes de pacotes em pypi.org, especialmente se a configuração do pip incluir vários índices de pacotes.
  • Use a especificação do identificador de versão no PEP 440 para saber os números de versão do pacote. Por padrão, o pip instala apenas versões estáveis. Ele usa a especificação do identificador de versão para diferenciar versões estáveis de versões de pré-lançamento e analisar os requisitos para a versão a ser instalada.

Para adicionar um pacote:

  1. Instale o Twine.

    pip install twine

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

  3. Faça upload dos arquivos de distribuição para o repositório do subdiretório dist do projeto. Execute este comando:

    twine upload dist/*

    É possível especificar um repositório específico com a sinalização --repository-url.

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

Como visualizar pacotes e versões

Modos de repositório: padrão, remoto

Para visualizar pacotes e versões de pacote usando o console do Google Cloud ou gcloud:

Console

  1. Abra a página Repositórios no Console do Google Cloud.

    Abrir a página Repositórios

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

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

  3. Clique em um pacote para visualizar as versões dele.

gcloud

Para listar pacotes em um repositório, execute o seguinte comando:

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

Onde

  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

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

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

Onde

  • PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.

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

Como listar arquivos

Modos de repositório: padrão, remoto

É possível listar arquivos em um repositório, arquivos em todas as versões de um pacote especificado ou arquivos em uma versão específica de um pacote.

Para todos os comandos a seguir, é possível definir um número máximo de arquivos a serem retornados adicionando a sinalização --limit ao comando.

Para listar todos os arquivos no projeto, no repositório e no local padrão quando os valores padrão estiverem configurados:

gcloud artifacts files list

Para listar arquivos em um projeto, repositório e local especificados, execute o comando:

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

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

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

Para listar arquivos de uma versão específica do pacote:

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

Substitua os seguintes valores:

  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY é o nome do repositório em que a imagem está armazenada.
  • PACKAGE é o nome do pacote.
  • VERSION é a versão do pacote.

Examples

Considere as seguintes informações do pacote:

  • Projeto: my-project
  • Repositório: my-repo
  • Local do repositório: us-central1
  • Pacote: my-app

O comando a seguir lista todos os arquivos no repositório my-repo no local us-central1 dentro do projeto padrão:

gcloud artifacts files list \
    --location=us-central1 \
    --repository=my-repo
O comando a seguir lista arquivos na versão 1.0 do pacote.

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

Como instalar pacotes

Modos de repositório: padrão, remoto, 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, faça o download de um pacote diretamente do repositório.

Para um repositório remoto, faça o download de uma cópia em cache do pacote e das dependências. Se uma cópia em cache não existir, o repositório remoto fará o download do pacote da origem upstream e o armazenará em cache antes de exibi-lo para você. É possível verificar se o repositório remoto recuperou os pacotes da origem upstream visualizando a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa o pacote solicitado em repositórios upstream.

  • Se uma cópia em cache não existir, os repositórios remotos upstream farão o download e armazenarão o pacote solicitado em cache. Os repositórios virtuais só veiculam pacotes solicitados, não os armazenam.
  • Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry escolherá um repositório upstream com base nas configurações de prioridade definidas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes configuraçõ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 alto. Portanto, o repositório virtual sempre o pesquisa primeiro.

Tanto secondary-repo1 quanto secondary-repo2 têm prioridade definida como 80. Se um pacote solicitado não estiver disponível em main-repo, o Artifact Registry pesquisará esses repositórios em seguida. Como ambos têm o mesmo valor de prioridade, o Artifact Registry pode optar por exibir um pacote de qualquer repositório se a versão estiver disponível em ambos.

test-repo tem o menor valor de prioridade e veiculará um artefato armazenado se nenhum dos outros repositórios upstream o tiver.

Mais informações

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

Para incluir versões de pré-lançamento quando o pip pesquisar um pacote a ser instalado, a sinalização --pre ao comando.

pip install --pre PACKAGE

Para especificar uma versão ou um intervalo de versões obrigatórios, inclua um especificador de requisitos. É possível incluir o requisito da versão diretamente no comando ou usar um arquivo de requisitos.

Por exemplo, este comando especifica que a versão mínima de 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 que as de pré-lançamento. Por isso, se a versão 1.0 estiver no repositório, o pip escolherá a versão 1.0 em vez da versão de pré-lançamento.

Se você não especificar um repositório, a configuração do pip em pip.conf determinará como o pip pesquisa o pacote.

  • Se você tiver configurado o repositório do Artifact Registry com a configuração index-url e nenhum outro índice de pacote estiver configurado, o pip só vai pesquisar o pacote do repositório do Artifact Registry.
  • Se você estiver usando um repositório virtual, o Artifact Registry usará as prioridades configuradas na política upstream para escolher um pacote quando vários repositórios upstream tiverem a versão do pacote solicitada. Se dois repositórios com o pacote tiverem a mesma prioridade, o Artifact Registry veiculará esse repositório a partir de qualquer repositório.
  • Se você configurou o pip com a configuração extra-index-url ou configurou vários índices de pacote, o pip pesquisa pypi.org e outros índices configurados e escolhe a versão mais recente do pacote.

É possível modificar as configurações de index-url ou extra-index-url no arquivo de requisitos. Também é possível usar sinalizações para essas configurações no comando pip. Por exemplo, esse 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 como instalar pacotes, consulte a documentação do pacote do Python.

Como excluir pacotes e versões

Modos de repositório: padrão, remoto

É possível excluir um pacote e todas as suas versões ou uma versão específica.

  • Depois de excluir um pacote, não é possível desfazer a ação.
  • Nos repositórios remotos, somente a cópia em cache do pacote é excluída. A origem upstream não é afetada. Se você excluir um pacote armazenado em cache, o Artifact Registry fará o download dele e o armazenará em cache novamente na próxima vez que o repositório receber uma solicitação para a mesma versão do pacote.

Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.

Para excluir um pacote:

Console

  1. Abra a página Repositórios no Console do Google Cloud.

    Abrir a página Repositórios

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

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

  3. Selecione o pacote que você quer excluir.

  4. Clique em EXCLUIR.

  5. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Onde

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • --async Retorna imediatamente, sem aguardar a conclusão da operação em andamento.

Para excluir versões de um pacote:

Console

  1. Abra a página Repositórios no Console do Google Cloud.

    Abrir a página Repositórios

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

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

  3. Clique em um pacote para visualizar as versões dele.

  4. Selecione as versões que você quer excluir.

  5. Clique em EXCLUIR.

  6. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

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

Onde

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
  • LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
  • --async retorna imediatamente, sem aguardar a conclusão da operação em andamento.

A seguir