Crie um arquivo Python wheel usando Databricks ativo Bundles

Este artigo descreve como criar, implantar e executar um arquivo Python wheel como parte de um projeto Databricks ativo Bundle . Veja o que são Databricks ativo Bundles?

Para obter um exemplo de configuração que cria um arquivo JAR e o Unity Catalog carrega para, consulte Bundle that upload a JAR file Unity Catalog to.

Requisitos

• Databricks CLI versão 0.218.0 ou acima está instalado e a autenticação está configurada. Para verificar a versão instalada do Databricks CLI, execute o comando databricks -v. Para instalar a CLI da Databricks, consulte Instalar ou atualizar a CLI da Databricks. Para configurar a autenticação, consulte Configurar o acesso ao site workspace.
• O site workspace remoto deve ter os arquivos workspace ativados. Consulte O que são arquivos workspace?

Criar o pacote usando um padrão

Nessas etapas, o senhor cria o pacote usando o padrão Databricks default bundle para Python. Esse pacote consiste em arquivos a serem criados em um arquivo Python wheel e na definição de um trabalho Databricks para criar esse arquivo Python wheel. Em seguida, o senhor valida, implanta e cria os arquivos implantados em um arquivo Python wheel a partir do Python wheel Job em seu Databricks workspace.

nota

O padrão de pacote Databricks default para Python usa uv para criar o arquivo Python wheel. Para instalar o uv, consulte Instalando uv.

Se você quiser criar um pacote do zero, consulte Criar um pacote manualmente.

Etapa 1: criar o pacote

Um pacote contém os artefatos que o senhor deseja implantar e as configurações para o fluxo de trabalho que deseja executar.

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

2. Use a versão Databricks CLI para executar o comando bundle init:

   Bash

   databricks bundle init

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

4. Para Unique name for this project, deixe o valor default de my_project ou digite um valor diferente e pressione Enter. Isso determina o nome do diretório raiz desse pacote. Esse diretório raiz é criado dentro do seu diretório de trabalho atual.

5. Para Include a stub (sample) notebook, selecione no e pressione Enter. Isso instrui o site Databricks CLI a não adicionar um Notebook de amostra ao seu pacote.

6. Para Include a stub (sample) Delta Live Tables pipeline, selecione no e pressione Enter. Isso instrui a CLI do Databricks a não definir um pipeline de amostra em seu pacote.

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

8. Para Use serverless, selecione yes e pressione Enter. Isso instrui o Databricks CLI a configurar seu pacote para execução em serverless compute.

Etapa 2: explore o pacote

Para acessar view os arquivos gerados pelo padrão, vá para o diretório raiz do pacote recém-criado e abra esse diretório com o IDE de sua preferência. Os arquivos de interesse particular incluem o seguinte:

• databricks.yml: Esse arquivo especifica o nome do pacote, especifica as configurações de compilação do whl, inclui uma referência ao arquivo de configuração do trabalho e define as configurações do espaço de trabalho de destino.
• resources/<project-name>_job.yml: Esse arquivo especifica as configurações do Python wheel Job.
• src/<project-name>: Esse diretório inclui os arquivos que o trabalho Python wheel usa para criar o arquivo Python wheel.

nota

Se quiser instalar o arquivo Python wheel em um clustering com Databricks Runtime 12.2 LTS ou abaixo, o senhor deve adicionar o seguinte mapeamento de nível superior ao arquivo databricks.yml:

YAML

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

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

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

1. No diretório raiz, use o endereço Databricks CLI para executar o comando bundle validate, como segue:

   Bash

   databricks bundle validate

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

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

Etapa 4: Crie o arquivo Python wheel e implante o projeto local no remoto workspace

Nessa etapa, o arquivo Python wheel é criado e implantado no site remoto Databricks workspace e um trabalho Databricks é criado no site workspace.

1. Use o Databricks CLI para executar o bundle deploy comando da seguinte forma:

   Bash

   databricks bundle deploy -t dev

2. Para verificar se o arquivo Python wheel criado localmente foi implantado:

   1. Na barra lateral do site Databricks workspace, clique em workspace .
   2. Clique na seguinte pasta: workspace > Usuários > <your-username> > .bundle > <project-name> > dev > artifacts >.internal > <random-guid> .

   O arquivo Python wheel deve estar nessa pasta.

3. Para verificar se o trabalho foi criado:

   1. Na barra lateral do site Databricks workspace, clique em Jobs & pipeline .
   2. Opcionalmente, selecione os filtros Empregos e de minha propriedade .
   3. Clique em [dev <your-username>] <project-name>Job .
   4. Clique na aba Tarefas .

   Deve haver uma tarefa: main_task .

Se você fizer alguma alteração em seu pacote após essa etapa, repita as etapas 3 a 4 para verificar se a configuração do pacote ainda é válida e, em seguida, reimplante o projeto.

Etapa 5: execução do projeto implantado

Nesta passo, você executa o Job do Databricks em seu workspace.

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

   Bash

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

2. Copie o valor de Run URL que aparece no terminal e cole-o no navegador da Web para abrir o site Databricks workspace.

3. Em seu site Databricks workspace, 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.

Crie o whl usando o Poetry ou o setuptools

Quando o senhor usa databricks bundle init com o padrão default-Python, é criado um pacote que mostra como configurar um pacote que constrói um Python wheel usando uv e pyproject.toml. No entanto, o senhor pode querer usar Poetry ou setuptools para construir uma roda.

Instalar o Poetry ou o setuptools

1. Instale o Poetry ou setuptools:

   aba :::tab-item[Poetry]

   • Instale Poetry o site, versão 1.6 ou acima, se ainda não estiver instalado. Para verificar a versão instalada do site Poetry, execute o comando poetry -V ou poetry --version.
   • Certifique-se de que o senhor tenha o Python versão 3.10 ou acima instalado. Para verificar sua versão do Python, execute o comando python -V ou python --version. :::

   tab-item[setuptools] Instale o pacote wheel e setuptools se ainda não estiverem instalados, executando o seguinte comando:

   Bash

   pip3 install --upgrade wheel setuptools

   ::: ::::

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

   aba :::tab-item[Poetry]

   .databricks
   dist

   :::

   :::tab-item[setuptools]

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

   ::: ::::

Adicionar arquivos de compilação

1. Na raiz do seu pacote, crie as seguintes pastas e arquivos, dependendo se o senhor usa Poetry ou setuptools para criar arquivos Python wheel:

   aba :::tab-item[Poetry]

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

   :::

   :::tab-item[setuptools]

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

   ::: ::::

2. Adicione o código a seguir ao arquivo pyproject.toml ou setup.py:

   tab :::tab-item[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 principal da sua organização em email.
   • Substitua <my-package-description> por uma descrição de exibição para seu arquivo Python wheel. :::

   :::tab-item[setup.py]

   Python

   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 principal da sua organização em email.
   • Substitua <my-package-description> por uma descrição de exibição para seu arquivo Python wheel. ::: ::::

Adicionar configuração de pacote de artefatos

1. Adicione a configuração de mapeamento artifacts ao seu databricks.yml para criar o artefato whl:

   tab :::tab-item[Poetry] Essa configuração executa o comando poetry build e indica que o caminho para o arquivo pyproject.toml está no mesmo diretório que o arquivo databricks.yml.

nota

Se o senhor já tiver criado um arquivo Python wheel e quiser apenas implantá-lo, modifique o seguinte arquivo de configuração do pacote omitindo o mapeamento artifacts. O Databricks CLI presumirá então que o arquivo Python wheel já foi criado e implantará automaticamente os arquivos especificados nas entradas whl do array libraries.

YAML

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: i3.xlarge
            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>

:::

tab-item[setuptools] Essa configuração executa o comando setuptools e indica que o caminho para o arquivo setup.py está no mesmo diretório que o arquivo databricks.yml.

YAML

bundle:
  name: my-wheel-bundle

artifacts:
  default:
    type: whl
    build: python3 setup.py bdist wheel
    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: i3.xlarge
            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>

::: ::::

:::