Desenvolver um arquivo wheel do Python usando os Pacotes de Ativos do Databricks

Este artigo descreve como compilar, implantar e executar um arquivo wheel do Python como parte de um projeto de Pacote de Ativos do Databricks. Confira O que são Pacotes de Ativos do Databricks?

Requisitos

• CLI do Databricks versão 0.218.0 ou superior. Para verificar a versão instalada da CLI do Databricks, execute o comando databricks -v. Para instalar a CLI do Databricks, consulte Instalar ou atualizar a CLI do Databricks.
• O espaço de trabalho remoto deve ter arquivos de espaço de trabalho habilitados. Consulte O que são Arquivos de workspace?.

Decisão: criar o pacote manualmente ou usando um modelo

Decida se deseja criar um pacote inicial usando um modelo ou criar o pacote manualmente. Criar o pacote usando um modelo é mais rápido e fácil, mas o pacote pode produzir conteúdo que não é necessário e as configurações padrão do pacote devem ser personalizadas ainda mais para aplicativos reais. Criar o pacote manualmente oferece controle total sobre as configurações do pacote, mas você deve estar familiarizado com como os pacotes funcionam, pois você está fazendo todo o trabalho desde o início. Escolha um dos seguintes conjuntos de etapas:

• Criar o pacote usando um modelo
• Criar o pacote manualmente

Criar o pacote usando um modelo

Nestas etapas, você cria o pacote usando o modelo de pacote padrão do Azure Databricks para Python. Essas etapas orientam você para criar um pacote que consiste em arquivos para compilar em um arquivo wheel do Python e a definição de um trabalho do Azure Databricks para compilar esse arquivo wheel do Python. Em seguida, você valida, implanta e compila os arquivos implantados em um arquivo wheel do Python a partir do trabalho do wheel do Python em seu workspace do Azure Databricks.

O modelo de pacote padrão do Azure Databricks para Python usa setuptools para compilar o arquivo wheel do Python. Se você quiser usar o Poetry para compilar o arquivo wheel do Python, siga as instruções mais adiante nesta seção para trocar a implementação do setuptools por uma implementação do Poetry.

Etapa 1: configurar a autenticação

Nesta etapa, você configura a autenticação entre a CLI do Databricks em sua máquina de desenvolvimento e seu workspace do Azure Databricks. Esse artigo pressupõe que você deseja usar a autenticação U2M (usuário para computador) do OAuth e um perfil de configuração correspondente do Azure Databricks chamado DEFAULT para autenticação.

Observação

A autenticação U2M é apropriada para testar essas etapas em tempo real. Para fluxos de trabalho totalmente automatizados, o Databricks recomenda que você use a autenticação M2M (máquina a máquina) do OAuth. Veja as instruções de configuração da autenticação M2M em Autenticação.

1. Use a CLI do Databricks para iniciar o gerenciamento de token OAuth localmente executando o comando a seguir para cada workspace de destino.

   No comando a seguir, substitua <workspace-url> pela URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. A CLI do Databricks solicita que você salve as informações inseridas como um perfil de configuração do Azure Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído pelas informações inseridas. Você pode usar perfis para alternar rapidamente seu contexto de autenticação em vários workspaces.

   Para obter uma lista de quaisquer perfis existentes, em um terminal ou prompt de comando separado, use a CLI do Databricks para executar o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

3. No seu navegador da Web, complete as instruções na tela para iniciar sessão no seu workspace do Azure Databricks.

4. Para visualizar o valor atual do token OAuth de um perfil e o carimbo de data/hora de expiração do token, execute um dos seguintes comandos:

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   Se você tiver vários perfis com o mesmo valor --host, talvez seja necessário especificar as opções --host e -p em conjunto para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

Etapa 2: Criar o pacote

Um pacote contém os artefatos que você deseja implantar e as configurações para os fluxos de trabalho que deseja executar.

1. Use seu terminal ou prompt de comando para alternar para um diretório em seu computador de desenvolvimento local que conterá o pacote gerado do modelo.

2. Use a versão da CLI do Databricks para realizar a execução do comando bundle init:

   databricks bundle init
   

3. Para Template to use, deixe o valor padrão default-python pressionando Enter.

4. Para Unique name for this project, deixe o valor padrão de my_project, ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz para esse pacote. Esse diretório raiz é criado no diretório de trabalho atual.

5. Para Include a stub (sample) notebook, selecionar no e pressionar Enter. Isso instrui a CLI do Databricks a não adicionar um bloco de anotações de exemplo ao seu pacote.

6. Para Include a stub (sample) DLT pipeline, selecionar no e pressionar Enter. Isso instrui a CLI do Databricks a não definir um pipeline de tabelas dinâmicas delta de exemplo em seu pacote.

7. Para Include a stub (sample) Python package, deixe o valor padrão yes pressionando Enter. Isso instrui a CLI do Databricks a adicionar arquivos de pacote do wheel do Python de exemplo e instruções de build relacionadas ao seu pacote.

Etapa 3: explorar o pacote

Para exibir os arquivos que o modelo gerou, alterne para o diretório raiz do pacote recém-criado e abra esse diretório com seu IDE preferido, por exemplo, o Visual Studio Code. Os arquivos de interesse específico incluem o seguinte:

• databricks.yml: este arquivo especifica o nome programático do pacote, inclui uma referência à definição do trabalho do wheel do Python e especifica as configurações sobre o workspace de destino.
• resources/<project-name>_job.yml: este arquivo especifica as configurações do trabalho do wheel do Python.
• src/<project-name>: este diretório inclui os arquivos que o trabalho do wheel do Python usa para compilar o arquivo wheel do Python.

Observação

Se quiser instalar o arquivo roda Python em um cluster de destino que tenha o Databricks Runtime 12.2 LTS ou inferior instalado, você deverá adicionar o seguinte mapeamento de nível superior ao arquivo databricks.yml:

# Applies to all tasks of type python_wheel_task.
experimental:
  python_wheel_wrapper: true

Esse mapeamento instrui a CLI do Databricks a fazer o seguinte:

• Implante uma cópia do arquivo wheel do Python em segundo plano. Esse caminho de implantação normalmente é ${workspace.artifact_path}/.internal/<random-id>/<wheel-filename>.whl.
• Crie um notebook em segundo plano que contenha instruções para instalar o arquivo wheel do Python implantado anteriormente no cluster de destino. Normalmente, o caminho desse notebook é ${workspace.file_path}/.databricks/bundle/<target-name>/.internal/notebook_<job-name>_<task-key>.
• Quando você executa um trabalho que contém uma tarefa do wheel do Python e essas tarefas fazem referência ao arquivo wheel do Python anterior, um trabalho é criado em segundo plano que executa o notebook anterior.

Você não precisa especificar esse mapeamento para clusters de destino com o Databricks Runtime 13.1 ou superior instalado, pois as instalações de wheel do Python do sistema de arquivos do workspace do Azure Databricks serão instaladas automaticamente nesses clusters de destino.

Etapa 4: Atualizar o pacote do projeto para usar o Poetry

Por padrão, o modelo de pacote especifica a criação do arquivo wheel do Python usando setuptools junto com setup.py e requirements-dev.txt dos arquivos. Se você quiser manter esses padrões, vá para a Etapa 5: Validar o arquivo de configuração do pacote do projeto.

Para atualizar o pacote do projeto para usar o Poetry em vez de setuptools, verifique se o computador de desenvolvimento local atende aos seguintes requisitos:

• Poetry versão 1.6 ou superior. Para verificar sua versão instalada do Poetry, execute o comando poetry -V ou poetry --version. Para instalar ou atualizar o Poetry, consulte Instalação.
• Python versão 3.10 ou posterior. Para verificar sua versão do Python, execute o comando python -V ou python --version.
• CLI do Databricks versão 0.209.0 ou superior. Para verificar sua versão da CLI do Databricks, execute o comando databricks -v ou databricks --version. Confira Instalar ou atualizar a CLI do Databricks.

Faça as seguintes alterações no pacote do projeto:

1. No diretório raiz do pacote, instrua poetry para inicializar os builds de wheel do Python para o Poetry executando o seguinte comando:

   poetry init
   

2. O Poetry exibe vários prompts para você concluir. Para os builds de wheel do Python, responda a esses prompts da seguinte maneira para corresponder às configurações padrão relacionadas no pacote do projeto:

   1. Para Package name, digite o nome da pasta filho em /src e pressione Enter. Esse também deve ser o valor do pacote name definido no arquivo do pacote setup.py.
   2. Para Version, digite 0.0.1 e pressione Enter. Isso corresponde ao número de versão definido no arquivo do pacote src/<project-name>/__init__.py.
   3. Para Description, digite wheel file based on <project-name>/src (substituindo <project-name> pelo nome do projeto) e pressione Enter. Isso corresponde ao valor description definido no arquivo do modelo setup.py.
   4. Para Author, pressione Enter. Esse valor padrão corresponde ao autor definido no arquivo do modelo setup.py.
   5. Para License, pressione Enter. Não há nenhuma licença definida no modelo.
   6. Para Compatible Python versions, insira a versão do Python que corresponde à de seus clusters do Azure Databricks de destino (por exemplo, ^3.10) e pressione Enter.
   7. Para Would you like to define your main dependencies interactively?, digite no e pressione Enter. Você definirá suas dependências mais tarde.
   8. Para Would you like to define your development dependencies interactively?, digite no e pressione Enter. Você definirá suas dependências mais tarde.
   9. Para Do you confirm generation? pressionar Enter.

3. Depois de concluir os prompts, o Poetry adiciona um arquivo pyproject.toml ao pacote do projeto. Para obter informações sobre o arquivo pyproject.toml, consulte O arquivo pyproject.toml.

4. No pacote do diretório raiz, instrua poetry a ler o arquivo pyproject.toml, resolver as dependências e instalá-las, criar um arquivo poetry.lock para bloquear as dependências e, por fim, criar um ambiente virtual. Para fazer isso, execute o seguinte comando:

   poetry install
   

5. Adicione a seção a seguir no final do arquivo pyproject.toml, substituindo <project-name> pelo nome do diretório que contém o arquivo src/<project-name>/main.py (por exemplo, my_project):

   [tool.poetry.scripts]
   main = "<project-name>.main:main"
   

   A seção especifica o ponto de entrada da wheel do Python para o trabalho.

6. Adicione o seguinte mapeamento no nível superior do arquivo do databricks.yml pacote:

   artifacts:
     default:
       type: whl
       build: poetry build
       path: .
   

   Esse mapeamento instrui a CLI do Databricks a usar o Poetry para compilar um arquivo wheel do Python.

7. Exclua do pacote os arquivos setup.py e requirements-dev.txt, pois o Poetry não precisa deles.

Etapa 5: Validar o arquivo de configuração do pacote do projeto

Nesta etapa, você verificará se a configuração do pacote é válida.

1. No diretório raiz, use a CLI do Databricks para executar o comando bundle validate, da seguinte maneira:

   databricks bundle validate
   

2. Se um resumo da configuração do pacote for retornado, então a validação foi bem-sucedida. Se algum erro for retornado, corrija-os e repita essa etapa.

Se você fizer quaisquer alterações em seu pacote após essa etapa, deverá repetir essa etapa para verificar se a configuração do pacote ainda é válida.

Etapa 6: compilar o arquivo wheel do Python e implantar o projeto local no workspace remoto

Nesta etapa, você cria o arquivo wheel do Python, implanta o arquivo wheel do Python criado em seu workspace remoto do Azure Databricks e cria o trabalho do Azure Databricks em seu workspace.

1. Se você usar setuptools, instale os pacotes wheel e setuptools se ainda não tiver feito isso, executando o seguinte comando:

   pip3 install --upgrade wheel setuptools
   

2. No terminal do Visual Studio Code, use a CLI do Databricks para executar o comando bundle deploy da seguinte maneira:

   databricks bundle deploy -t dev
   

3. Se você quiser verificar se o arquivo wheel do Python criada localmente foi implantada:

   1. Na barra lateral do espaço de trabalho do Azure Databricks, clique em Workspace.
   2. Clique na seguinte pasta: Workspace > Usuários ><your-username>> .bundle ><project-name>> dev > artefatos > .internal ><random-guid>.

   O arquivo wheel do Python deve estar nesta pasta.

4. Se você quiser verificar se o trabalho foi criado:

   1. Na barra lateral do espaço de trabalho do Azure Databricks, clique em Workflows.
   2. Na guia Trabalhos, clique em [dev <your-username>] <project-name>_job.
   3. Clique na guia Tarefas.

   Deve haver uma tarefa: main_task.

Se você fizer todas as alterações em seu pacote após esta etapa, deverá repetir as etapas 5 a 6 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplantar o projeto.

Etapa 7: Executar o projeto implantado

Nesta etapa, você executa o trabalho do Azure Databricks em seu workspace.

1. No diretório raiz, use a CLI do Databricks para executar o comando bundle run, da seguinte maneira, substituindo <project-name> pelo nome do projeto da Etapa 2:

   databricks bundle run -t dev <project-name>_job
   

2. Copie o valor de Run URL que aparece em seu terminal e cole esse valor em seu navegador da Web para abrir seu workspace do Azure Databricks.

3. No workspace do Azure Databricks, depois que a tarefa for concluída com êxito e mostrar uma barra de título verde, clique na tarefa main_task para ver os resultados.

Se você fizer todas as alterações no pacote após esta etapa, deverá repetir as etapas de 5 a 7 para verificar se a configuração do pacote ainda é válida, reimplantar o projeto e executar o projeto reimplantado.

Você chegou ao final das etapas para criar um pacote usando um modelo.

Criar o pacote manualmente

Nestas etapas, você cria o pacote desde o início à mão. Essas etapas orientam você para criar um pacote que consiste em arquivos para compilar em um arquivo wheel do Python e a definição de um trabalho do Databricks para compilar esse arquivo wheel do Python. Em seguida, você valida, implanta e cria os arquivos implantados em um arquivo wheel do Python a partir do trabalho do wheel do Python em seu workspace do Databricks.

Essas etapas incluem a adição de conteúdo a um arquivo YAML. Opcionalmente, talvez seja melhor usar um IDE (ambiente de desenvolvimento integrado) que fornece sugestões e ações de esquema automático em trabalhos com arquivos YAML. As etapas a seguir usam o Visual Studio Code com a extensão YAML instalada do Visual Studio Code Marketplace.

Estas etapas pressupõem que você já sabe:

• Como criar, compilar e trabalhar com arquivos wheel do Python com o Poetry ou setuptools. Para Poetry, consulte o Uso básico. Para setuptools, consulte o Guia do Usuário de Empacotamento do Python.
• Como usar arquivos wheel do Python como parte de um trabalho do Azure Databricks. Consulte Usar um arquivo wheel do Python em um trabalho do Azure Databricks.

Siga estas instruções para criar um pacote de exemplo que compila um arquivo wheel do Python com o Poetry ou setuptools, implanta o arquivo wheel do Python e executa o arquivo wheel do Python implantada.

Se você compilou um arquivo wheel do Python e quiser apenas implantá-lo e executá-lo, vá direto para a especificação das configurações do wheel do Python no arquivo de configuração do pacote na Etapa 3: criar o arquivo de configuração do pacote.

Etapa 1: configurar a autenticação

Nesta etapa, você configura a autenticação entre a CLI do Databricks em sua máquina de desenvolvimento e seu workspace do Azure Databricks. Esse artigo pressupõe que você deseja usar a autenticação U2M (usuário para computador) do OAuth e um perfil de configuração correspondente do Azure Databricks chamado DEFAULT para autenticação.

Observação

A autenticação U2M é apropriada para testar essas etapas em tempo real. Para fluxos de trabalho totalmente automatizados, o Databricks recomenda que você use a autenticação M2M (máquina a máquina) do OAuth. Veja as instruções de configuração da autenticação M2M em Autenticação.

1. Use a CLI do Databricks para iniciar o gerenciamento de token OAuth localmente executando o comando a seguir para cada workspace de destino.

   No comando a seguir, substitua <workspace-url> pela URL por workspace do Azure Databricks, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

   databricks auth login --host <workspace-url>
   

2. A CLI do Databricks solicita que você salve as informações inseridas como um perfil de configuração do Azure Databricks. Pressione Enter para aceitar o nome de perfil sugerido ou digite o nome de um perfil novo ou existente. Qualquer perfil existente com o mesmo nome será substituído pelas informações inseridas. Você pode usar perfis para alternar rapidamente seu contexto de autenticação em vários workspaces.

   Para obter uma lista de quaisquer perfis existentes, em um terminal ou prompt de comando separado, use a CLI do Databricks para executar o comando databricks auth profiles. Para visualizar as configurações existentes de um perfil específico, execute o comando databricks auth env --profile <profile-name>.

3. No seu navegador da Web, complete as instruções na tela para iniciar sessão no seu workspace do Azure Databricks.

4. Para visualizar o valor atual do token OAuth de um perfil e o carimbo de data/hora de expiração do token, execute um dos seguintes comandos:

   • databricks auth token --host <workspace-url>
   • databricks auth token -p <profile-name>
   • databricks auth token --host <workspace-url> -p <profile-name>

   Se você tiver vários perfis com o mesmo valor --host, talvez seja necessário especificar as opções --host e -p em conjunto para ajudar a CLI do Databricks a encontrar as informações de token OAuth correspondentes corretas.

Etapa 2: Criar o pacote

Um pacote contém os artefatos que você deseja implantar e as configurações para os fluxos de trabalho que deseja executar.

1. Na raiz do pacote, crie as seguintes pastas e arquivos, dependendo de você usar o Poetry ou setuptools para compilar arquivos wheel do Python:

   Poetry

   ├── src
   │     └── my_package
   │           ├── __init__.py
   │           ├── main.py
   │           └── my_module.py
   └── pyproject.toml
   

   Setuptools

   ├── src
   │     └── my_package
   │           ├── __init__.py
   │           ├── main.py
   │           └── my_module.py
   └── setup.py
   

2. Deixe o arquivo __init__.py vazio.

3. Adicione o código a seguir ao arquivo main.py e, em seguida, salve o arquivo:

   from my_package.my_module import *
   
   def main():
   
     first = 200
     second = 400
   
     print(f"{first} + {second} = {add_two_numbers(first, second)}")
     print(f"{second} - {first} = {subtract_two_numbers(second, first)}")
     print(f"{first} * {second} = {multiply_two_numbers(first, second)}")
     print(f"{second} / {first} = {divide_two_numbers(second, first)}")
   
   if __name__ == "__main__":
     main()
   

4. Adicione o código a seguir ao arquivo my_module.py e, em seguida, salve o arquivo:

   def add_two_numbers(a, b):
     return a + b
   
   def subtract_two_numbers(a, b):
     return a - b
   
   def multiply_two_numbers(a, b):
     return a * b
   
   def divide_two_numbers(a, b):
     return a / b
   

5. Adicione o código a seguir ao arquivo pyproject.toml ou setup.py e, em seguida, salve o arquivo:

   Pyproject.toml

   [tool.poetry]
   name = "my_package"
   version = "0.0.1"
   description = "<my-package-description>"
   authors = ["my-author-name <my-author-name>@<my-organization>"]
   
   [tool.poetry.dependencies]
   python = "^3.10"
   
   [build-system]
   requires = ["poetry-core"]
   build-backend = "poetry.core.masonry.api"
   
   [tool.poetry.scripts]
   main = "my_package.main:main"
   

   • Substitua my-author-name pelo nome de contato principal da sua organização.
   • Substitua my-author-name>@<my-organization pelo endereço de contato de email principal da sua organização.
   • Substitua <my-package-description> por uma descrição de exibição para o arquivo wheel do Python.

   Setup.py

   from setuptools import setup, find_packages
   
   import src
   
   setup(
     name = "my_package",
     version = "0.0.1",
     author = "<my-author-name>",
     url = "https://<my-url>",
     author_email = "<my-author-name>@<my-organization>",
     description = "<my-package-description>",
     packages=find_packages(where='./src'),
     package_dir={'': 'src'},
     entry_points={
       "packages": [
         "main=my_package.main:main"
       ]
     },
     install_requires=[
       "setuptools"
     ]
   )
   

   • Substitua https://<my-url> pela URL da sua organização.
   • Substitua <my-author-name> pelo nome de contato principal da sua organização.
   • Substitua <my-author-name>@<my-organization> pelo endereço de contato de email principal da sua organização.
   • Substitua <my-package-description> por uma descrição de exibição para o arquivo wheel do Python.

Etapa 3: Criar o arquivo de configuração do pacote

Um arquivo de configuração de pacote descreve os artefatos que você deseja implantar e os fluxos de trabalho que você deseja executar.

1. Na raiz do pacote, adicione um arquivo de configuração de pacote chamado databricks.yml. Adicione o seguinte código a este arquivo:

   Poetry

   Observação

   Se você já tiver criado um arquivo wheel do Python e quiser apenas implantá-lo e executá-lo, modifique o seguinte arquivo de configuração do pacote omitindo o mapeamento artifacts. A CLI do Databricks assumirá que o arquivo wheel do Python já foi criado e implantará automaticamente os arquivos especificados na matriz libraries, nas entradas whl.

   bundle:
     name: my-wheel-bundle
   
   artifacts:
     default:
       type: whl
       build: poetry build
       path: .
   
   resources:
     jobs:
       wheel-job:
         name: wheel-job
         tasks:
           - task_key: wheel-task
             new_cluster:
               spark_version: 13.3.x-scala2.12
               node_type_id: Standard_DS3_v2
               data_security_mode: USER_ISOLATION
               num_workers: 1
             python_wheel_task:
               entry_point: main
               package_name: my_package
             libraries:
               - whl: ./dist/*.whl
   
   targets:
     dev:
       workspace:
       host: <workspace-url>
   

   Setuptools

   bundle:
     name: my-wheel-bundle
   
   resources:
     jobs:
       wheel-job:
         name: wheel-job
         tasks:
           - task_key: wheel-task
             new_cluster:
               spark_version: 13.3.x-scala2.12
               node_type_id: Standard_DS3_v2
               data_security_mode: USER_ISOLATION
               num_workers: 1
             python_wheel_task:
               entry_point: main
               package_name: my_package
             libraries:
               - whl: ./dist/*.whl
   
   targets:
     dev:
       workspace:
       host: <workspace-url>
   

   Substitua <workspace-url> por sua URL por workspace, por exemplo, https://adb-1234567890123456.7.azuredatabricks.net.

   O mapeamento artifacts é necessário para compilar arquivos wheel do Python com o Poetry e é opcional para compilar arquivos wheels do Python com setuptools. O mapeamento artifacts contém uma ou mais definições de artefato com os seguintes mapeamentos:

   • O mapeamento type deve estar presente e definido como whl para especificar que um arquivo wheel do Python deve ser criado. Para setuptools, whl será o padrão se nenhuma definição de artefato for especificada.
   • O mapeamento path indica o caminho para o arquivo pyproject.toml para Poetry ou para o arquivo setup.py para setuptools. Esse caminho é relativo ao arquivo databricks.yml. Para setuptools, esse caminho é . (o mesmo diretório que o arquivo databricks.yml) por padrão.
   • O mapeamento build indica todos os comandos de compilação personalizados a serem executados para compilar o arquivo wheel do Python. Para setuptools, esse comando é python3 setup.py bdist wheel por padrão.
   • O mapeamento files consiste em um ou mais mapeamentos source que especificam arquivos adicionais a serem incluídos no build da wheel do Python. Não há nenhum padrão.

   Observação

   Se quiser instalar o arquivo roda Python em um cluster de destino que tenha o Databricks Runtime 12.2 LTS ou inferior instalado, você deverá adicionar o seguinte mapeamento de nível superior ao arquivo databricks.yml:

   # Applies to jobs with python_wheel_task and that use
   # clusters with Databricks Runtime 13.0 or below installed.
   experimental:
     python_wheel_wrapper: true
   

   Esse mapeamento instrui a CLI do Databricks a fazer o seguinte:

   • Implanta uma cópia do arquivo wheel do Python em segundo plano. Esse caminho de implantação normalmente é ${workspace.artifact_path}/.internal/<random-id>/<wheel-filename>.whl.
   • Cria um notebook em segundo plano que contenha instruções para instalar o arquivo wheel do Python implantado anteriormente no cluster de destino. Normalmente, o caminho desse notebook é ${workspace.file_path}/.databricks/bundle/<target-name>/.internal/notebook_<job-name>_<task-key>.
   • Quando você executa um trabalho que contém uma tarefa do wheel do Python e essa tarefa faz referência ao arquivo wheel do Python anterior, um trabalho é criado em segundo plano que executa o notebook anterior.

   Você não precisa especificar esse mapeamento para clusters de destino com o Databricks Runtime 13.1 ou superior instalado, pois as instalações de wheel do Python do sistema de arquivos do workspace do Azure Databricks serão instaladas automaticamente nesses clusters de destino.

2. Se você usar Poetry, faça o seguinte:

   • Instale o Poetry, versão 1.6 ou superior, se ainda não estiver instalado. Para verificar sua versão instalada do Poetry, execute o comando poetry -V ou poetry --version.
   • Verifique se você tem o Python versão 3.10 ou superior instalado. Para verificar sua versão do Python, execute o comando python -V ou python --version.
   • Verifique se você tem a CLI do Databricks versão 0.209.0 ou superior. Para verificar sua versão da CLI do Databricks, execute o comando databricks -v ou databricks --version. Confira Instalar ou atualizar a CLI do Databricks.

3. Se você usar setuptools, instale os pacotes wheel e setuptools se eles ainda não estiverem instalados, executando o seguinte comando:

   pip3 install --upgrade wheel setuptools
   

4. Se você pretende armazenar esse pacote com um provedor Git, adicione um .gitignore arquivo na raiz do projeto e adicione as seguintes entradas a esse arquivo:

   Poetry

   .databricks
   dist
   

   Setuptools

   .databricks
   build
   dist
   src/my_package/my_package.egg-info
   

Etapa 4: validar o arquivo de configuração do pacote do projeto

Nesta etapa, você verificará se a configuração do pacote é válida.

1. No diretório raiz, valide o arquivo de configuração do pacote:

   databricks bundle validate
   

2. Se um resumo da configuração do pacote for retornado, então a validação foi bem-sucedida. Se algum erro for retornado, corrija-os e repita essa etapa.

Se você fizer quaisquer alterações em seu pacote após essa etapa, deverá repetir essa etapa para verificar se a configuração do pacote ainda é válida.

Etapa 5: compilar o arquivo wheel do Python e implantar o projeto local no workspace remoto

Crie o arquivo wheel do Python localmente, implante o arquivo wheel do Python criado em seu workspace, implante o notebook no workspace e crie o trabalho em seu workspace:

databricks bundle deploy -t dev

Etapa 6: executar o projeto implantado

1. Execute o trabalho implantado, que usa o notebook implantado para chamar o arquivo wheel do Python implantado:

   databricks bundle run -t dev wheel-job
   

2. No resultado, copie o Run URL e cole-o na barra de endereços do navegador da Web.

3. Na página Saída da execução do trabalho, os seguintes resultados são exibidos:

   200 + 400 = 600
   400 - 200 = 200
   200 * 400 = 80000
   400 / 200 = 2.0
   

Se você fizer alterações no pacote após essa etapa, deverá repetir as etapas de 3 a 5 para verificar se a configuração do pacote ainda é válida, reimplantar o projeto e executar o projeto reimplantado.

Compilar e instalar um arquivo wheel do Python para um trabalho

Para compilar um arquivo wheel do Python com o Poetry ou setuptools e, em seguida, usar esse arquivo wheel do Python em um trabalho, você deve adicionar um ou dois mapeamentos ao arquivo databricks.yml.

Se você usar o Poetry, deverá incluir o mapeamento de artifacts a seguir no arquivo databricks.yml. Esse mapeamento executa o comando poetry build e usa o arquivo pyproject.toml que está no mesmo diretório que o arquivo databricks.yml :

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

Observação

O mapeamento de artifacts é opcional para setuptools. Por padrão, para setuptools a CLI do Databricks executa o comando python3 setup.py bdist_wheel e usa o arquivo setup.py que está no mesmo diretório que o arquivo databricks.yml. A CLI do Databricks pressupõe que você já executou um comando, como pip3 install --upgrade wheel setuptools para instalar os pacotes wheel e setuptools, caso eles ainda não estejam instalados.

Além disso, o mapeamento libraries da tarefa de trabalho deve conter um valor whl que especifique o caminho para o arquivo wheel do Python criado em relação ao arquivo de configuração em que foi declarado. O exemplo a seguir mostra isso em uma tarefa de notebook (as reticências indicam conteúdo omitido para brevidade):

resources:
  jobs:
    my-notebook-job:
      name: my-notebook-job
      tasks:
        - task_key: my-notebook-job-notebook-task
          notebook_task:
            notebook_path: ./my_notebook.py
          libraries:
            - whl: ./dist/*.whl
          new_cluster:
            # ...

Compilar e instalar um arquivo wheel do Python para um pipeline

Para compilar um wheel do Python com o Poetry ou setuptools e, em seguida, fazer referência a esse wheel do Python em um pipeline de Tabelas Dinâmicas Delta, você deve adicionar um mapeamento ao arquivo databricks.yml se você usa Poetry e um comando %pip install ao seu notebook de pipeline, da seguinte maneira.

Se você usar o Poetry, deverá incluir o mapeamento de artifacts a seguir no arquivo databricks.yml. Esse mapeamento executa o comando poetry build e usa o arquivo pyproject.toml que está no mesmo diretório que o arquivo databricks.yml :

artifacts:
  default:
    type: whl
    build: poetry build
    path: .

Observação

O mapeamento de artifacts é opcional para setuptools. Por padrão, para setuptools a CLI do Databricks executa o comando python3 setup.py bdist_wheel e usa o arquivo setup.py que está no mesmo diretório que o arquivo databricks.yml. A CLI do Databricks pressupõe que você já executou um comando, como pip3 install --upgrade wheel setuptools para instalar os pacotes wheel e setuptools, caso eles ainda não estejam instalados.

Além disso, o notebook de pipeline relacionado deve incluir um comando %pip install para instalar o arquivo wheel do Python criado. Consulte Bibliotecas do Python.