Guia de início rápido do Python

Este guia de início rápido mostra como configurar um repositório Python do Artifact Registry, fazer upload de um pacote e instalar o pacote.

Antes de começar

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  4. Ative a API Artifact Registry.

    Ative a API

  5. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  6. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  7. Ative a API Artifact Registry.

    Ative a API

Inicie o Cloud Shell

Neste guia de início rápido, você usará o Cloud Shell, um ambiente de shell para gerenciar recursos hospedados no Google Cloud.

O Cloud Shell vem pré-instalado com a ferramenta de linha de comando gcloud e o Python. A ferramenta gcloud fornece a principal interface de linha de comando do Google Cloud.

Inicie o Cloud Shell

  1. Acesse o Console do Google Cloud.

    Console do Google Cloud

  2. Na barra de ferramentas do Console do Cloud, clique em Ativar o Cloud Shell:

Uma sessão do Cloud Shell é aberta dentro de um quadro inferior no console. Use esse shell para executar comandos gcloud.

Configurar um ambiente virtual

Nesta seção, você usará o venv para criar um ambiente virtual isolado.

No ambiente que você instalará:

O uso de um ambiente virtual isola as dependências do Python em um projeto das dependências em outros projetos. Recomendamos que você sempre use um ambiente virtual por projeto ao desenvolver localmente com o Python.

Para configurar um ambiente virtual:

  1. Use o comando venv para criar uma cópia virtual de toda a instalação do Python 3 em uma pasta chamada quickstart.

    python3 -m venv quickstart
    
  2. Configure o shell para usar os caminhos venv para Python ativando o ambiente virtual.

    source quickstart/bin/activate
    

    O prompt de comando é alterado para mostrar que você está usando o ambiente virtual do Python 3.

    (quickstart) user@~$ python --version
    
  3. Atualize o pip para a versão mais recente:

    python -m pip install -U pip
    
  4. Instale o Twine e o back-end do keyring do Artifact Registry com o comando:

    pip install twine keyrings.google-artifactregistry-auth
    
  5. Liste os back-ends para confirmar a instalação.

    keyring --list-backends
    

    A resposta tem a aparência do exemplo a seguir.

    keyring.backends.chainer.ChainerBackend (priority: -1)
    keyring.backends.fail.Keyring (priority: 0)
    keyrings.gauth.GooglePythonAuth (priority: 9)
    

Crie um repositório

Crie o repositório dos pacotes.

  1. Crie o repositório:

    Console

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

      Abrir a página Repositórios

    2. Clique em Criar repositório.

    3. Especifique quickstart-python-repo como o nome do repositório.

    4. Escolha Python como formato.

    5. Em Tipo de local, selecione Região e escolha o local us-central1.

    6. Clique em Criar.

    O repositório é adicionado à lista de repositórios.

    gcloud

    1. Execute o seguinte comando para criar um novo repositório de pacotes Python no projeto atual chamado quickstart-python-repo no local us-central1.

      gcloud artifacts repositories create quickstart-python-repo \
          --repository-format=python \
          --location=us-central1 \
          --description="Python package repository"
      
    2. Execute o seguinte comando para verificar se o repositório foi criado:

      gcloud artifacts repositories list
      

    Para mais informações sobre os comandos do Artifact Registry, execute o comando gcloud artifacts.

  2. Para simplificar os comandos gcloud, defina o repositório padrão como quickstart-python-repo e o local padrão como us-central1. Depois que os valores forem definidos, não será necessário especificá-los nos comandos gcloud que exigem um repositório ou local.

    Para definir o repositório, execute o comando:

    gcloud config set artifacts/repository quickstart-python-repo
    

    Para definir o local, execute o comando:

    gcloud config set artifacts/location us-central1
    

    Para mais informações sobre esses comandos, consulte a documentação do gcloud config set.

Configurar a autenticação

Para configurar a autenticação com o back-end do keyring do Artifact Registry:

  1. Execute o comando a seguir para imprimir a configuração do repositório para adicionar ao seu projeto do Python.

    gcloud artifacts print-settings python
    
  2. Crie ou atualize o arquivo .pypirc. Esse arquivo especifica repositórios para publicar pacotes Python.

    O local padrão é:

    • Linux e MacOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc

    No arquivo .pypirc, index-servers lista repositórios e cada repositório tem uma seção separada com configurações de repositório.

    [distutils]
    index-servers =
        quickstart-python-repo
    
    [quickstart-python-repo]
    repository: https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/
    

    Substitua PROJECT_ID pela ID do seu projeto.

  3. Crie um arquivo de configuração pip para seu ambiente virtual. As configurações nesse arquivo são combinadas com qualquer configuração no pip global.conf ou global por usuário.

    • Unix e macOS: $VIRTUAL_ENV/pip.conf
    • Windows: %VIRTUAL_ENV%\pip.ini

    Inclua o seguinte snippet no arquivo:

    [global]
    extra-index-url = https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/simple/
    

    A string /simple/ no final do caminho do repositório indica que o repositório implementa a API Python Repository simples.

  4. Faça login no SDK do Cloud com suas credenciais de usuário.

    gcloud auth login
    

Seu ambiente Python agora está configurado para fazer a autenticação com o Artifact Registry.

Receber um exemplo de pacote

Quando você cria um projeto Python, os arquivos de distribuição são salvos em um subdiretório dist no seu projeto Python. Para simplificar este guia de início rápido, faça o download dos arquivos dos pacotes pré-compilados.

  1. Crie uma pasta de projeto Python chamada python-quickstart.

    mkdir python-quickstart
    
  2. Crie um subdiretório chamado dist e altere para o diretório.

    mkdir python-quickstart/dist
    cd python-quickstart/dist
    
  3. Faça o download dos pacotes Python de amostra usados no tutorial Como empacotar projetos Python no Guia do usuário de empacotamento do Python.

    pip download sampleproject
    

    O comando faz o download do pacote sampleproject e da dependência dele, peppercorn.

Faça upload do pacote no repositório

Use o Twine para fazer upload dos pacotes para seu repositório.

  1. No diretório dist, mude para o diretório pai python-quickstart.

    cd ..
    
  2. Faça upload dos pacotes para o repositório a partir do diretório dist.

    twine upload --repository-url https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/ dist/*
    

O Twine faz upload do sampleproject e do peppercorn para o repositório.

Ver o pacote no repositório

Para verificar se o pacote foi adicionado ao repositório:

Console

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

    Abrir a página Repositórios

  2. Na lista de repositórios, clique no repositório quickstart-python-repo.

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

gcloud

Para listar os pacotes no repositório quickstart-python-repo, execute o seguinte comando:

gcloud artifacts packages list --repository=quickstart-python-repo

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

gcloud artifacts versions list --package=PACKAGE

Em que PACKAGE é o ID do pacote.

Instale o pacote

Execute o seguinte comando para instalar o pacote:

pip install --index-url https://us-central1-python.pkg.dev/PROJECT_ID/quickstart-python-repo/simple/ sampleproject

Solução de problemas

Por padrão, ferramentas como pip e Twine não retornam mensagens de erro detalhadas. Se você encontrar um erro, execute o comando novamente com a sinalização --verbose para ver uma saída mais detalhada. Para mais informações, consulte Solução de problemas de pacotes Python.

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta página, siga estas etapas:

Antes de remover o repositório, verifique se os pacotes que você quer manter estão disponíveis em outro local.

Para excluir o repositório:

Console

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

    Abrir a página Repositórios

  2. Na lista de repositórios, selecione o repositório quickstart-python-repo.

  3. Clique em Excluir.

gcloud

  1. Para excluir o repositório quickstart-python-repo, execute o seguinte comando:

    gcloud artifacts repositories delete quickstart-python-repo
    
  2. Se você quiser remover as configurações padrão de repositório e localização que definiu para a configuração ativa gcloud, execute os seguintes comandos:

    gcloud config unset artifacts/repository
    gcloud config unset artifacts/location
    

Se você quiser parar de usar o ambiente virtual e voltar para o Python global, execute o comando a seguir:

deactivate

Se você mantiver a pasta quickstart, poderá ativar o ambiente virtual novamente nas sessões atuais ou novas do Cloud Shell executando o comando ativar novamente. Como todos os pacotes necessários para o Artifact Registry já estão instalados no ambiente virtual, não será necessário configurá-los novamente.

source quickstart/bin/activate

A seguir