Especificar dependências no Python

Há duas maneiras de especificar dependências para o Cloud Functions gravadas no Python: com o uso do arquivo requirements.txt do gerenciador de pacotes pip ou o com o empacotamento de dependências locais com a função.

A especificação de dependência que usa o padrão Pipfile/Pipfile.lock não é compatível. Seu projeto não deve incluir esses arquivos.

Como especificar dependências com pip

Dependências no Python são gerenciadas com pip e expressas em um arquivo de metadados chamado requirements.txt. O arquivo precisa estar no mesmo diretório que o arquivo main.py que contém o código da função.

Quando você implanta ou reimplanta a função, o Cloud Functions usa o pip para fazer o download e instalar a versão mais recente das dependências, conforme declarado no arquivo requirements.txt. 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.

Para evitar que seu build seja afetado por mudanças na versão de dependência, fixe os pacotes de dependência em uma versão específica.

A seguir, um exemplo de arquivo requirements.txt:

functions-framework
requests==2.20.0
numpy

O Functions Framework é uma dependência necessária para todas as funções. Embora o Cloud Functions o instale em seu nome quando a função é criada, recomendamos que você a inclua como uma dependência explícita para maior clareza.

Se a função depende de dependências particulares, recomendamos que você espelhe functions-framework no registro particular. Inclua o functions-framework espelhado como uma dependência da sua função para evitar a instalação do pacote pela Internet pública.

Como empacotar dependências locais

Também é possível empacotar e implantar dependências junto com sua função. Essa abordagem é útil se sua dependência não estiver disponível por meio do gerenciador de pacotes pip ou se o acesso à Internet do ambiente do Cloud Functions for restrito.

Por exemplo, é possível usar uma estrutura de diretório como a seguinte:

myfunction/
├── main.py
└── localpackage/
    ├── __init__.py
    └── script.py

Você pode importar o código normalmente de localpackage usando a seguinte instrução import.

# Code in main.py
from localpackage import script

Observe que essa abordagem não executará nenhum arquivo setup.py. Pacotes com esses arquivos ainda podem ser agrupados, mas podem não ser executados corretamente no Cloud Functions.

Dependências disponibilizadas por pacotes de terceiros

Dependências disponibilizadas por pacotes de terceiros são aquelas em que a origem é incluída diretamente no pacote de código-fonte e recriada com seu próprio código. Use a variável de ambiente de build GOOGLE_VENDOR_PIP_DEPENDENCIES para criar dependências pip disponibilizadas por pacotes de terceiros e para evitar a instalação delas durante a implantação.

Criar dependências disponibilizadas por pacotes de terceiros

  1. Verifique se python3 está instalado no sistema de desenvolvimento.

  2. Declare as dependências do aplicativo em um arquivo requirements.txt no diretório raiz da árvore de desenvolvimento.

  3. Declare o Functions Framework como um requisito incluindo functions-framework em uma linha separada no arquivo requirements.txt.

  4. Faça o download das dependências da função para o diretório local. As etapas para fazer isso dependem do tipo de arquivo de dependência: um arquivo wheel (*.whl) do Python ou um arquivo tar (*.tar.gz).

    1. Se a dependência for um wheel do Python (*.whl), faça o download dela no diretório raiz da árvore de desenvolvimento com este comando pip:

      python3 -m pip download -r requirements.txt --only-binary=:all: \
         -d DIRECTORY \
         --python-version PYTHON_RUNTIME_VERSION \
         --platform manylinux2014_x86_64 \
         --implementation cp
      

      Substitua:

      • DIRECTORY: o nome do diretório local para o download.
      • PYTHON_RUNTIME_VERSION: a versão do Python a ser usada para verificações de compatibilidade. Por exemplo, 311 para Python 3.11.
        Essa versão precisa corresponder a um dos ambientes de execução Python compatíveis

      A estrutura de diretórios resultante será semelhante a esta:

      myfunction/
      ├── main.py
      └── requirements.txt
      └── DIRECTORY
         ├── dependency1.whl
         └── dependency2.whl
      
    2. Se a dependência for um arquivo tar (*.tar.gz):

      1. Se a dependência estiver escrita em Python, use o pip para fazer o download dela:

        python3 -m pip download -r requirements.txt \
           -d DIRECTORY
        
      2. Se uma dependência consistir em códigos escritos em C ou C++, faça o download dela e a compile separadamente.

  5. Implante a função e as dependências disponibilizadas por pacotes de terceiros:

    gcloud functions deploy FUNCTION_NAME \
      --runtime PYTHON_RUNTIME_NAME \
      --set-build-env-vars GOOGLE_VENDOR_PIP_DEPENDENCIES=DIRECTORY
    

    Substitua:

    • FUNCTION_NAME: o nome da função do Cloud Functions que você está implantando.
    • PYTHON_RUNTIME_NAME: o nome de um dos ambientes de execução Python compatíveis para executar a função implantada em, por exemplo, python311. Precisa ser a mesma versão do ambiente de execução do Python usada no ambiente de desenvolvimento local.
    • DIRECTORY: o nome do diretório que contém as dependências disponibilizadas por pacotes de terceiros.

Para mais detalhes sobre o uso de buildpacks, consulte Criar uma função com buildpacks.

Como usar dependências privadas

Dependências particulares do Artifact Registry

Um repositório Python do Artifact Registry pode hospedar dependências particulares para sua função Python. Ao implantar no Cloud Functions, o processo de compilação gera automaticamente 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:

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

Se o build precisar de vários repositórios, use um repositório virtual do Artifact Registry para controlar com segurança a ordem de pesquisa do pip nos repositórios.

Dependências particulares de outros repositórios

As dependências são instaladas em um ambiente Cloud Build, que não fornece acesso a chaves SSH. Os pacotes hospedados em repositórios que requerem autenticação baseada em SSH precisam ser fornecidos e carregados junto com o código do seu projeto, conforme descrito na seção anterior.

Use o comando pip install com a sinalização -t DIRECTORY para copiar dependências privadas em um diretório local antes de implantar o aplicativo, da seguinte maneira:

  1. Copie sua dependência em um diretório local:

    pip install -t DIRECTORY DEPENDENCY
  2. Adicione um arquivo __init__.py vazio ao diretório DIRECTORY para transformá-lo em um módulo.

  3. Importe deste módulo para usar sua dependência:

    import DIRECTORY.DEPENDENCY

Pacotes pré-instalados

Os seguintes pacotes do Python são instalados automaticamente junto com sua função durante a implantação. Se estiver usando qualquer um desses pacotes no código de função, recomendamos incluir as seguintes versões em seu arquivo requirements.txt:

Python 3.7

aiohttp==3.8.1
aiosignal==1.2.0
async-timeout==4.0.2
attrs==21.4.0
cachetools==4.2.4
certifi==2021.10.8
chardet==4.0.0
charset-normalizer==2.0.10
click==8.0.3
Flask==2.0.2
frozenlist==1.2.0
google-api-core==2.3.2
google-api-python-client==2.34.0
google-auth==2.3.3
google-auth-httplib2==0.1.0
google-cloud-core==2.2.1
google-cloud-trace==1.5.1
googleapis-common-protos==1.54.0
grpcio==1.43.0
grpcio-status==1.43.0
httplib2==0.20.2
idna==3.3
itsdangerous==2.0.1
Jinja2==3.0.3
MarkupSafe==2.0.1
multidict==5.2.0
opencensus==0.8.0
opencensus-context==0.1.2
packaging==21.3
proto-plus==1.19.8
protobuf==3.19.1
pyasn1==0.4.8
pyasn1-modules==0.2.8
pyparsing==3.0.6
pytz==2021.3
PyYAML==6.0
requests==2.27.1
rsa==4.8
setuptools==60.3.1
six==1.16.0
uritemplate==4.1.1
urllib3==1.26.7
Werkzeug==2.0.2
wrapt==1.13.3
yarl==1.7.2

Python 3.8 e posterior

click==8.1.7
cloudevents==1.9.0
deprecation==2.1.0
Flask==2.2.5
functions-framework==3.0.0
gunicorn==20.1.0
importlib-metadata==6.7.0
itsdangerous==2.1.2
Jinja2==3.1.2
MarkupSafe==2.1.3
packaging==23.1
typing_extensions==4.7.1
watchdog==1.0.2
Werkzeug==2.2.3
zipp==3.15.0

* `pip` (latest version)
* `setuptools` (latest version)
* `wheel` (determined by product requirements)

Além disso, o ambiente de execução do Python inclui vários pacotes do sistema no ambiente de execução. Se a função usar uma dependência que exija um pacote de sistema que não esteja listado, será possível solicitá-lo.