Configuração do pacote no Python

Os Pacotes de Ativos do Python para Databricks estendem os Pacotes de Ativos do Databricks para que você possa:

Definir recursos no código do Python. Essas definições podem coexistir com 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 do Python para o pacote databricks-bundles do Databricks Asset Bundles está disponível em https://databricks.github.io/cli/python/.

Requisitos

Para usar o suporte do Python para pacotes de ativos do Databricks, primeiro você deve:

Instale a CLI do Databricks, versão 0.275.0 ou superior. Confira Instalar ou atualizar a CLI do Databricks.
Autentique-se no workspace do Databricks se você ainda não fez isso:
```
databricks configure
```
Instale uv. Consulte instalação do uv. Os Pacotes de Ativos do Python para Databricks usam 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 o venv.

Criar um projeto com base no modelo

Para criar um novo suporte do Python para o projeto Pacotes de Ativos do Databricks, inicialize um pacote usando o pydabs modelo:

databricks bundle init pydabs

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

Agora, crie um novo ambiente virtual em 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 de classe de dados:

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 por meio de um ponto de entrada especificado na 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'

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 trabalhos ou pipelines

Para implantar o pacote no destino de desenvolvimento, use o comando de implantação de pacote da raiz do projeto do pacote:

databricks bundle deploy --target dev

Esse comando implanta tudo 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 ao seu workspace. Você pode encontrar esse trabalho navegando até Jobs &Pipelines em seu workspace do Databricks.

Depois que o pacote for implantado, você poderá usar o comando resumo do pacote para examinar tudo o que é implantado:

databricks bundle summary --target dev

Por fim, para executar um trabalho ou pipeline, use o comando de execução do pacote:

databricks bundle run my_pydabs_project_job

Atualizar pacotes existentes

Para atualizar os pacotes existentes, modele a estrutura do modelo de projeto conforme descrito em Criar um projeto a partir de um modelo. Os pacotes existentes com 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 . Veja Exibir trabalhos como código.

Abra a página da tarefa existente no Databricks workspace.
Clique no kebab à esquerda do botão Executar agora e clique em Exibir como código:
Selecione Python e, em seguida, Pacotes de Ativos do Databricks
Clique em Copiar e salvar o Python gerado como um arquivo Python na pasta de recursos do projeto de pacote.

Dica

Você também pode exibir e copiar YAML para trabalhos e pipelines existentes que podem ser colados diretamente em seus arquivos YAML de configuração de pacote.

Criar recursos usando metadados

A implementação padrão da load_resources função carrega arquivos Python no resources pacote. Você pode usar o 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 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 de classe Recursos e Bundle para obter mais informações.

Modificar recursos definidos em YAML ou Python

Você pode referenciar funções mutadoras em databricks.yml, de forma semelhante a funções que carregam recursos. Esse recurso pode ser usado independentemente do carregamento de recursos definidos em Python e modifica os recursos definidos no YAML e no 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 pacote. Isso atualiza todas as tarefas definidas no pacote com notificações por email, caso elas estejam ausentes. As funções de mutador precisam ser especificadas databricks.ymle 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 modificadores também podem ser usados para outros campos, como configurar clusters padrão de trabalho ou SQL Warehouses.

python:
  mutators:
    - 'mutators:add_email_notifications'

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

Comentários

Esta página foi útil?

Last updated on 2025-11-14