Configuração do pacote em Python

Python for Databricks Asset Bundles estende Databricks Asset Bundles para que você possa:

Defina recursos em código Python. Estas definições podem coexistir com os recursos definidos no YAML.
Crie recursos dinamicamente usando metadados. Consulte Criar recursos usando metadados.
Modifique os recursos definidos em YAML ou Python durante a implantação do pacote. Consulte Modificar recursos definidos em YAML ou Python.

A documentação de referência para o suporte Python para o pacote Databricks Asset Bundles databricks-bundles está disponível em https://databricks.github.io/cli/python/.

Requerimentos

Para usar o suporte Python para Databricks Asset Bundles, você deve primeiro:

Instale a CLI do Databricks, versão 0.275.0 ou superior. Consulte Instalar ou atualizar a CLI do Databricks.
Autentique-se em seu espaço de trabalho Databricks se ainda não tiver feito isso:
```
databricks configure
```
Instale uv. Consulte Instalação do uv. Python for Databricks Asset Bundles usa uv para criar um ambiente virtual e instalar as dependências necessárias. Como alternativa, você pode configurar seu ambiente Python usando outras ferramentas, como venv.

Criar um projeto a partir do modelo

Para criar um novo suporte Python para o projeto Databricks Asset Bundles, inicialize um pacote usando o pydabs modelo:

databricks bundle init pydabs

Quando solicitado, dê um nome ao seu projeto, como my_pydabs_project, e aceite a inclusão de um bloco de anotações e um pacote Python.

Agora crie um novo ambiente virtual na sua nova pasta de projeto:

cd my_pydabs_project
uv sync

Por padrão, o modelo inclui um exemplo de um trabalho definido como Python no resources/my_pydabs_project_job.py arquivo:

from databricks.bundles.jobs import Job


my_pydabs_project_job = Job.from_dict(
    {
        "name": "my_pydabs_project_job",
        "tasks": [
            {
                "task_key": "notebook_task",
                "notebook_task": {
                    "notebook_path": "src/notebook.ipynb",
                },
            },
        ],
    },
)

A Job.from_dict função aceita um dicionário Python usando o mesmo formato que YAML. Os recursos também podem ser construídos usando a sintaxe dataclass:

from databricks.bundles.jobs import Job, Task, NotebookTask


my_pydabs_project_job = Job(
    name="my_pydabs_project_job",
    tasks=[
        Task(
            task_key="notebook_task",
            notebook_task=NotebookTask(
                notebook_path="src/notebook.ipynb",
            ),
        ),
    ],
)

Os arquivos Python são carregados através de um ponto de entrada especificado na seção indicada em python no databricks.yml.

python:
  # Activate the virtual environment before loading resources defined in
  # Python. If disabled, it defaults to using the Python interpreter
  # available in the current shell.
  venv_path: .venv
  # Functions called to load resources defined in Python.
  # See resources/__init__.py
  resources:
    - 'resources:load_resources'

Por padrão, resources/__init__.py contém uma função que carrega todos os arquivos Python no pacote de recursos.

from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


def load_resources(bundle: Bundle) -> Resources:
    """
    'load_resources' function is referenced in databricks.yml and is responsible for loading
    bundle resources defined in Python code. This function is called by Databricks CLI during
    bundle deployment. After deployment, this function is not used.
    """

    # the default implementation loads all Python files in 'resources' directory
    return load_resources_from_current_package_module()

Implantar e executar tarefas ou pipelines

Para implantar o bundle no destino de desenvolvimento, use o comando bundle deploy da raiz do projeto bundle:

databricks bundle deploy --target dev

Este comando implanta tudo o que foi definido para o projeto de pacote. Por exemplo, um projeto criado usando o modelo padrão implanta um trabalho chamado [dev yourname] my_pydabs_project_job para seu espaço de trabalho. Você pode encontrar esse trabalho navegando até Jobs & Pipelines em seu espaço de trabalho Databricks.

Depois que o pacote for implantado, você poderá usar o comando bundle summary para revisar tudo o que for implantado:

databricks bundle summary --target dev

Finalmente, para executar um trabalho ou pipeline, utilize o comando bundle run:

databricks bundle run my_pydabs_project_job

Atualizar pacotes existentes

Para atualizar pacotes existentes, modele a estrutura do modelo de projeto conforme descrito em Criar um projeto a partir de um modelo. Os pacotes existentes com o YAML podem ser atualizados para incluir recursos definidos como código Python adicionando uma python seção em databricks.yml:

python:
  # Activate the virtual environment before loading resources defined in
  # Python. If disabled, it defaults to using the Python interpreter
  # available in the current shell.
  venv_path: .venv
  # Functions called to load resources defined in Python.
  # See resources/__init__.py
  resources:
    - 'resources:load_resources'

O ambiente virtual especificado deve conter o pacote PyPi databricks-bundles instalado.

pip install databricks-bundles==0.275.0

A pasta de recursos deve conter __init__.py o arquivo:

from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


def load_resources(bundle: Bundle) -> Resources:
    """
    'load_resources' function is referenced in databricks.yml and
    is responsible for loading bundle resources defined in Python code.
    This function is called by Databricks CLI during bundle deployment.
    After deployment, this function is not used.
    """

    # default implementation loads all Python files in 'resources' folder
    return load_resources_from_current_package_module()

Converter trabalhos existentes em Python

Para converter trabalhos existentes em Python, você pode usar o recurso Exibir como código . Consulte Exibir trabalhos como código.

Abra a página do trabalho existente no espaço de trabalho Databricks.
Clique no kebab à esquerda do botão Executar agora e, em seguida, clique em Ver como código:
Selecione Python e, em seguida, Databricks Asset Bundles
Clique em Copiar e salve o Python gerado como um arquivo Python na pasta de recursos do projeto do pacote.

Sugestão

Você também pode visualizar e copiar o YAML para trabalhos e pipelines existentes que você pode colar diretamente em seus arquivos YAML de configuração do pacote.

Criar recursos usando metadados

A implementação padrão da load_resources função carrega arquivos Python no resources pacote. Você pode usar Python para criar recursos programaticamente. Por exemplo, você pode carregar arquivos de configuração e criar trabalhos em um loop:

from databricks.bundles.core import (
    Bundle,
    Resources,
    load_resources_from_current_package_module,
)


from databricks.bundles.jobs import Job


def create_job(country: str):
    my_notebook = {
        "task_key": "my_notebook",
        "notebook_task": {
            "notebook_path": "files/my_notebook.py",
        },
    }


    return Job.from_dict(
        {
            "name": f"my_job_{country}",
            "tasks": [my_notebook],
        }
    )


def load_resources(bundle: Bundle) -> Resources:
    resources = load_resources_from_current_package_module()


    for country in ["US", "NL"]:
        resources.add_resource(f"my_job_{country}", create_job(country))


    return resources

Acessar as variáveis do pacote

O bundle parâmetro pode ser usado para acessar variáveis de pacote e o destino de implantação:

from databricks.bundles.core import Bundle, Resources, Variable, variables

@variables
class Variables:
    warehouse_id: Variable[str]


def load_resources(bundle: Bundle) -> Resources:
    warehouse_id = bundle.resolve_variable(Variables.warehouse_id)

    ...

Consulte a referência das classes Resources e Bundle para obter mais informações.

Modificar recursos definidos em YAML ou Python

Você pode fazer referência a funções do mutador no databricks.yml, semelhante às funções que carregam recursos. Esse recurso pode ser usado independentemente do carregamento de recursos definidos em Python e muta recursos definidos em YAML e Python.

Primeiro, crie mutators.py na raiz do pacote com o seguinte conteúdo:

from dataclasses import replace


from databricks.bundles.core import Bundle, job_mutator
from databricks.bundles.jobs import Job, JobEmailNotifications


@job_mutator
def add_email_notifications(bundle: Bundle, job: Job) -> Job:
    if job.email_notifications:
        return job


    email_notifications = JobEmailNotifications.from_dict(
        {
            "on_failure": ["${workspace.current_user.userName}"],
        }
    )


    return replace(job, email_notifications=email_notifications)

Agora, use a seguinte configuração para executar a função add_email_notifications durante a implantação do bundle. Isso atualiza todos os trabalhos definidos no pacote com notificações por e-mail se eles estiverem ausentes. As funções do mutador devem ser especificadas em databricks.yml, e são executadas na ordem especificada. Os mutadores de trabalho são executados para cada trabalho definido em um pacote e podem retornar uma cópia atualizada ou uma entrada não modificada. Os mutadores também podem ser usados para outros campos, como a configuração de clusters de tarefas padrão ou armazéns SQL.

python:
  mutators:
    - 'mutators:add_email_notifications'

Se as funções lançarem uma exceção durante a execução do mutador, a implantação do pacote será anulada.

Feedback

Esta página foi útil?

Last updated on 2025-11-14