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:

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 site Python, execute o comando python -V ou python --version.

Setuptools

Instale os pacotes wheel e setuptools caso ainda não estejam 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:

Poetry

.databricks
dist

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:

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. Adicione o código a seguir ao arquivo pyproject.toml ou setup.py:

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.

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:

Poetry

Esta 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

If you have already built a Python wheel file and just want to deploy it, then modify the following bundle configuration file by omitting the artifacts mapping. The Databricks CLI will then assume that the Python wheel file is already built and will automatically deploy the files that are specified in the libraries array's whl entries.

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: n2-highmem-4
            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

Esta 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: n2-highmem-4
            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>