Gerenciar pacotes Python

Nesta página, descrevemos como adicionar, visualizar e excluir pacotes e pacotes do Python mais recentes.

Antes de começar

  1. Instale e inicialize o Google Cloud CLI.

    É necessário ter a versão 354.0.0 ou mais recente da Google Cloud CLI para executar os comandos do repositórios do Python. É possível 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 do Python.

  3. Verifique se o Python 3 está instalado. Para instruções de instalação, consulte a Tutorial do Google Cloud para configurar o Python.

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

  5. Se você estiver usando a autenticação de keyring com credenciais da 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 do IAM no repositório:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Você também pode conseguir as permissões necessárias por meio de tags personalizadas ou outras funções predefinidas papéis.

Como adicionar pacotes

Modos de repositório: padrão

Quando você cria um projeto Python, os arquivos de distribuição são salvos em um dist em seu projeto. Depois, é possível usar a 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 particulares para que eles não correspondam ao pacote nomes em pypi.org, principalmente se A configuração de pip inclui vários índices de pacotes.
  • Use a especificação do identificador de versão no PEP 440 para os números de versão dos pacotes. Por padrão, o pip apenas instala versões estáveis lançamentos. Ele usa a especificação do identificador de versão para distinguir versões estáveis das versões de pré-lançamento e analisar os requisitos do a versão a ser instalada.

Para adicionar um pacote:

  1. Instale o Twine.

    pip install twine

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

  3. Faça upload dos arquivos de distribuição para o repositório do projeto dist . 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

To view packages and package versions using the Google Cloud console or gcloud:

Console

  1. Open the Repositories page in the Google Cloud console.

    Abrir a página Repositórios

  2. In the repository list, click the appropriate repository.

    The Packages page lists the packages in the repository.

  3. Click a package to view versions of the package.

gcloud

To list packages in a repository, run the following command:

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

Where

  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

To view versions of a package, run the following command:

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

Where

  • PACKAGE is the ID of the package or fully qualified identifier for the package.
  • REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
  • LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

Para repositórios remotos, a lista retornada deve incluir todos os repositórios dependências 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 ou arquivos em uma versão específica de um pacote.

Para todos os comandos a seguir, você pode 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, repositório e 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 regional ou multirregional local do repositório.
  • PROJECT: seuID de projeto no Google Cloud. Se o ID do projeto contiver dois pontos (`:`), consulte Projetos com escopo de domínio.
  • REPOSITORY: o nome do repositório em que a imagem são armazenados.
  • PACKAGE: o nome do pacote.
  • VERSION: a versão do pacote.

Exemplos

Considere as seguintes informações de pacote:

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

O comando a seguir lista todos os arquivos no repositório my-repo na Local us-west1 no projeto padrão:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
O comando a seguir lista os arquivos 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

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 dependências. Se uma cópia em cache não existir, o repositório remoto vai fazer o download do pacote da origem upstream e armazená-lo em cache antes de exibi-lo para você. É possível verificar se o repositório remoto recuperou os pacotes do origem upstream visualizando a lista de pacotes no repositório.

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

  • Os repositórios remotos upstream vão fazer o download e armazenar em cache o pacote solicitado se uma cópia em cache não existe. Os repositórios virtuais disponibilizam somente solicitações pacotes, eles não os armazenam.
  • Se você solicitar uma versão disponível em mais de um repositório, o Artifact Registry escolherá um repositório upstream para usar 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, então o repositório virtual sempre o pesquisa primeiro.

Tanto secondary-repo1 quanto secondary-repo2 têm prioridade definida como 80. Se um O pacote solicitado não está disponível em main-repo, o Artifact Registry pesquisa esses repositórios a seguir. Como ambas têm o mesmo valor de prioridade, O Artifact Registry pode disponibilizar um pacote de qualquer repositório se a versão estiver disponível em ambas.

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

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. PEP 440 define a versão do Python do identificador exclusivo para usuários com pip para analisar números de versão, incluindo versões de pré-lançamento.

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

pip install --pre PACKAGE

Para especificar uma versão ou um intervalo de versões, inclua um especificador de requisitos. É possível incluir o requisito de 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 é 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 os pré-lançamentos. Portanto, se a versão 1.0 estiver no repositório, o pip vai escolher a versão 1.0 em vez de uma de pré-lançamento.

Se você não especificar um repositório, sua configuração de pip em pip.conf determina como o pip procura o pacote.

  • Se você configurou o repositório do Artifact Registry com o index-url e nenhum outro índice de pacote estiver configurado, apenas pesquisas de pip repositório do Artifact Registry para o pacote.
  • Se você estiver usando um repositório virtual, o Artifact Registry usará o das prioridades configuradas na política upstream para escolher um pacote ao vários repositórios upstream têm a versão do pacote solicitada. Se dois repositórios com o pacote tiverem a mesma prioridade, o Artifact Registry vai servir o pacote de qualquer um dos repositórios.
  • Se você configurou o pip com a configuração extra-index-url ou se você configurou vários índices de pacotes, pesquisas de pip pypi.org (link em inglês) e qualquer outro arquivo configurado indexa o pacote e escolhe a versão mais recente dele.

É possível substituir index-url ou extra-index-url no arquivo de requisitos. Você pode use também flags para essas configurações no comando pip. Por exemplo, este comando modifica 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 de empacotamento do Python.

Como excluir pacotes e versões

Modos de repositório: padrão, remoto

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

  • Depois de excluir um pacote, não é possível desfazer a ação.
  • Para repositórios remotos, apenas a cópia em cache do pacote é excluída. O a origem não é afetada. Se você excluir um pacote armazenado em cache, o Artifact Registry vai fazer o download e armazená-lo 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. Use esta sinalização para ver repositórios em um local específico. Se você configurado um local padrão, é possível omitir essa sinalização para 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. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.
  • --async retorna imediatamente, sem aguardar a conclusão da operação em andamento.

A seguir