Criar um aplicativo em Python

Os buildpacks permitem a configuração idiomática de linguagem por meio de variáveis de ambiente.

Especificar a versão do Python

Por padrão, o buildpack do ambiente de execução Python usa a versão estável mais recente do interpretador de Python. Se seu aplicativo exigir uma versão específica, inclua um arquivo .python-version no diretório raiz do aplicativo especificando essa versão.

3.13

Usar GOOGLE_PYTHON_VERSION

Também é possível especificar a versão do Python usando a variável de ambiente GOOGLE_PYTHON_VERSION. Se as duas configurações forem definidas, o valor GOOGLE_PYTHON_VERSION terá prioridade sobre o arquivo .python-version. Por padrão, quando o arquivo .python-version e a variável de ambiente GOOGLE_PYTHON_VERSION não são especificados, a versão LTS mais recente do Python é usada.

Para configurar o buildpack para usar o Python 3.13 ao implantar o app:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env GOOGLE_PYTHON_VERSION="3.13.x"

Também é possível usar um descritor de projeto project.toml para codificar a variável de ambiente com os arquivos do projeto. Veja instruções sobre como criar o aplicativo com variáveis de ambiente.

Especificar dependências com pip

O buildpack do Python permite o gerenciamento de dependências de aplicativos usando o pip. As dependências do aplicativo precisam ser declaradas em um arquivo requirements.txt no diretório raiz.

O arquivo requirements.txt contém uma linha por pacote. Cada linha contém o nome do pacote e, como opção, a versão solicitada. Para mais detalhes, consulte a referência do requirements.txt.

A seguir, um exemplo de arquivo requirements.txt:

requests==2.20.0
numpy

Configurar o pip

É possível configurar o comportamento do pip usando variáveis de ambiente:

pack build sample-python --builder=gcr.io/buildpacks/builder \
  --env PIP_DEFAULT_TIMEOUT='60'

Dependências particulares do Artifact Registry

Um repositório Python do Artifact Registry pode hospedar dependências particulares para sua função Python. Ao criar um aplicativo no Cloud Build, o buildpack do Python gera automaticamente as credenciais do Artifact Registry para a conta de serviço do Cloud Build. Só é preciso incluir o URL do Artifact Registry no requirements.txt sem gerar outras credenciais. Exemplo:

--extra-index-url REPOSITORY_URL
sampleapp
Flask==0.10.1
google-cloud-storage

Ponto de entrada do aplicativo

A seção a seguir descreve o ponto de entrada padrão para o buildpack do Python.

Ponto de entrada para implantações de origem do Cloud Run.

Esse recurso só estará disponível se você implantar o código-fonte no Cloud Run com o ambiente de execução do Python. Esse recurso não é aplicável se você estiver criando a imagem de contêiner diretamente usando pack build fora do processo de implantação de origem do Cloud Run.

O buildpack do Python é compatível com frameworks da Web modernos, como FastAPI, Gradio e Streamlit.

Python versão 3.12 e anteriores

Se você estiver usando o Python 3.12 ou versões anteriores, o buildpack do Python usará o Gunicorn (em inglês) como o servidor HTTP WSGI padrão para sua carga de trabalho. O buildpack do Python define o ponto de entrada padrão como gunicorn -b :8080 main:app.

Python versão 3.13 e mais recente

Para o Python versão 3.13 e mais recentes, o buildpack do Python define o ponto de entrada padrão para implantações de origem do Cloud Run com base na configuração do servidor da Web ou do framework no arquivo requirements.txt. Essa configuração padrão se aplica apenas às implantações de origem de serviço do Cloud Run, não às funções do Cloud Run.

Ao implantar um serviço do Cloud Run da origem usando o ambiente de execução do Python, o buildpack determina a versão do Python e o ponto de entrada padrão das seguintes maneiras:

  • Se você não especificar uma versão do Python nos arquivos de origem, o buildpack do Python vai definir como padrão a versão mais recente compatível do Python. O buildpack determina o ponto de entrada padrão com base no servidor da Web ou no framework que você configurou no arquivo requirements.txt.

  • Se você não especificar um servidor da Web ou um framework no arquivo requirements.txt, o buildpack do Python usará o Gunicorn como o servidor HTTP WSGI padrão para sua carga de trabalho. O buildpack do Python define o ponto de entrada padrão como gunicorn -b :8080 main:app.

  • O buildpack do Python define o ponto de entrada padrão com base na seguinte ordem de precedência, conforme definido no arquivo requirements.txt:

    1. gunicorn
    2. uvicorn
    3. fastapi[standard]
    4. gradio
    5. streamlit

Configurar o servidor da Web ou o framework

Para cada configuração comum do Python no arquivo requirements.txt, a tabela a seguir mostra os pontos de entrada padrão ao implantar no Cloud Run da origem:

Configuração principal Ponto de entrada padrão Variáveis de ambiente
gunicorn gunicorn -b :8080 main:app
numpy gunicorn -b :8080 main:app
fastapi
uvicorn		 uvicorn main:app --host 0.0.0.0 --port 8080
fastapi[standard] uvicorn main:app --host 0.0.0.0 --port 8080
uvicorn
gunicorn		 gunicorn -b :8080 main:app
gradio python main.py GRADIO_SERVER_NAME=0.0.0.0
GRADIO_SERVER_PORT=8080
streamlit streamlit run main.py --server.address 0.0.0.0 --server.port 8080

Para evitar falhas de implantação, use uma versão compatível do Python nos arquivos de origem e especifique um servidor da Web no arquivo requirements.txt.

Como alternativa, especifique o ponto de entrada executando o seguinte comando de implantação de origem:

  gcloud run deploy SERVICE --source .  --set-build-env-vars GOOGLE_ENTRYPOINT="ENTRYPOINT"

Substitua:

  • SERVICE: o nome do serviço em que você quer implantar.
  • ENTRYPOINT: o ponto de entrada padrão que você quer usar para o código fonte.

Se você não conseguir implantar o código-fonte no Cloud Run ou encontrar erros nos registros, consulte o guia de solução de problemas do Cloud Run.

Ponto de entrada para todas as outras implantações

O buildpack do Python usa o Gunicorn (em inglês) como o servidor HTTP WSGI padrão para sua carga de trabalho. Os apps criados com o buildpack do Python iniciam o processo gunicorn com configurações padrão, semelhante à execução:

gunicorn --bind :8080 main:app

Personalizar o ponto de entrada do aplicativo

É possível personalizar o comando de inicialização dos aplicativos usando um Procfile ou uma variável de ambiente. Talvez seja necessário fazer isso para personalizar as configurações padrão de ponto de entrada.

Você pode criar um Procfile com suas configurações personalizadas no diretório raiz. Exemplo:

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Como alternativa, é possível usar a variável de ambiente GOOGLE_ENTRYPOINT com o comando pack. Exemplo:

pack build sample-python \
  --builder gcr.io/buildpacks/builder
  --env "GOOGLE_ENTRYPOINT='gunicorn --bind :$PORT main:app'"

Variáveis de ambiente

O buildpack do Python é compatível com as variáveis de ambiente a seguir para personalizar o contêiner.

PIP_<key>

Consulte a documentação do pip.

Exemplo: PIP_DEFAULT_TIMEOUT=60 define --default-timeout=60 para comandos pip.