# Программные вызовы

Программные вызовы позволяют вызывать команды dbt из скриптов и приложений на Python, а не запускать их в командной оболочке. Это полезно, когда нужно встроить запуски dbt в более крупное приложение или рабочий процесс, используя при этом тот же набор команд, что и в dbt CLI.

Типичные сценарии использования:

* Запуск dbt как части приложения или сервиса на Python
* Интеграция запусков dbt в процессы оркестрации
* Создание внутренних инструментов, которым нужно выполнять команды dbt и анализировать результаты

Если вы ещё не установили официальный пакет Python для dbt v1, перейдите на страницу [пакета dbt v1 на PyPI](https://pypi.org/project/dbt-core/) для его установки.

(Версии dbt: v2.0 и новее)

```python
from dbt.cli.main import dbtRunner, dbtRunnerResult

# initialize
dbt = dbtRunner()

# create CLI args as a list of strings
cli_args = ["run", "--select", "tag:my_tag"]

# run the command
res: dbtRunnerResult = dbt.invoke(cli_args)

# inspect the results
for r in res.result:
    print(f"{r.unique_id}: {r.status}")
```

Подробности реализации см. в [крейте `dbt-python`](https://github.com/dbt-labs/dbt/tree/main/crates/dbt-python) в репозитории dbt v1.

## Поддерживаемые аргументы

`dbtRunner.invoke` принимает те же аргументы, что и dbt CLI. Первый позиционный аргумент — это команда (например, `run`, `build`, `test`), за которой следуют флаги и параметры, которые вы обычно передаёте в командной строке.

Например, `dbt.invoke(["run", "--select", "tag:my_tag"])` эквивалентен выполнению `dbt run --select tag:my_tag`. Отдельного списка аргументов для dbtRunner нет; официальным источником информации о доступных параметрах служат справка CLI (`dbt --help`, `dbt run --help` и т. д.) и [справочник команд dbt](https://docs.getdbt.tech/reference/dbt-commands.md).

```python
from dbt.cli.main import dbtRunner
dbt = dbtRunner()
# equivalent ways to pass arguments
dbt.invoke(["run", "--select", "tag:my_tag"])
dbt.invoke(["run"], select="tag:my_tag")
```

## Параллельное выполнение не поддерживается

dbt не поддерживает [безопасное параллельное выполнение](https://docs.getdbt.tech/reference/dbt-commands.md#parallel-execution) нескольких вызовов в одном процессе. Одновременное выполнение нескольких команд dbt в одном процессе небезопасно и официально не рекомендуется; для этого требуется процесс-обёртка, управляющий подпроцессами. Причины следующие:

* Одновременно выполняемые команды могут непредвиденным образом взаимодействовать с платформой данных. Например, одновременное выполнение `dbt run` и `dbt build` для одних и тех же моделей может привести к непредсказуемым результатам.
* Каждая команда `dbt` взаимодействует с глобальными переменными Python. Для безопасной работы команды необходимо выполнять в отдельных процессах, например создавая подпроцессы или используя Celery для оркестрации.

Для [безопасного параллельного выполнения](https://docs.getdbt.tech/reference/dbt-commands.md#available-commands) можно использовать [dbt platform CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md) или [Studio IDE](https://docs.getdbt.tech/docs/platform/studio-ide/develop-in-studio.md): оба инструмента берут на себя дополнительную работу по управлению одновременным выполнением в нескольких процессах.

(Версии dbt: v2.0 и новее)

В v2 вызовы выполняются последовательно благодаря блокировкам на уровне потоков, поэтому несколько вызовов не могут выполняться одновременно в одном процессе. (В v1 параллельное выполнение не поддерживалось, но блокировок не было, поэтому вызовы всё же могли выполняться в многопоточном режиме.) Как и в v1, вы по-прежнему можете распараллеливать выполнение, используя несколько процессов и выполняя каждый вызов в отдельном процессе.

## `dbtRunnerResult`

Каждая команда возвращает объект `dbtRunnerResult` со следующими атрибутами:

* `success` (bool): Указывает, успешно ли выполнена команда.
* `result`: Когда команда завершается (успешно или с обработанными ошибками), содержит результат или результаты команды. Тип возвращаемого значения зависит от команды.
* `exception`: Когда при вызове dbt возникает необработанная ошибка и выполнение не завершается, содержит возникшее исключение.
* `catalog` (только v2): Каталог, который команда создаёт при запросе генерации каталога.

(Версии dbt: v2.0 и новее)

Движок v2 реализован на Rust, поэтому `exception` больше не содержит исходный объект исключения Python, возникшего в dbt. Вместо этого перехваченное сообщение об ошибке передаётся в исключении соответствующего типа:

* Если вызов завершается с ошибкой на границе интерфейса внешних функций (FFI), прежде чем движок начнёт его обрабатывать, `exception` содержит исключение без дополнительной обёртки, например `ValueError` или `RuntimeError`.
* Если вызов завершается с ошибкой внутри движка, `exception` содержит `DbtRunnerError`.

В v2 в `dbtRunnerResult` также добавляется атрибут верхнего уровня `catalog`, если запрошена генерация каталога.

В v1 файл `catalog.json` создавался только при запуске `dbt docs generate`. В v2 каталог можно сгенерировать при выполнении любой команды, передав [флаг `--write-catalog`](https://docs.getdbt.tech/reference/commands/cmd-docs.md?version=2.0#--write-catalog-flag). Например, `dbt run --write-catalog` заполняет и `dbtRunnerResult.result`, и `dbtRunnerResult.catalog`.

Между [кодами завершения CLI](https://docs.getdbt.tech/reference/exit-codes.md) и объектом `dbtRunnerResult`, возвращаемым при программном вызове, существует взаимно однозначное соответствие:

| Сценарий                                                                                                        | Код завершения CLI | `success` | `result`           | `exception` |
| --------------------------------------------------------------------------------------------------------------- | ------------------ | --------- | ------------------ | ----------- |
| Вызов завершился без ошибок                                                                                     | 0                  | `True`    | зависит от команды | `None`      |
| Вызов завершился как минимум с одной обработанной ошибкой (например, сбоем теста или ошибкой построения модели) | 1                  | `False`   | зависит от команды | `None`      |
| Необработанная ошибка. Вызов не завершился и не возвращает результатов.                                         | 2                  | `False`   | `None`             | Исключение  |

## Обязательства и оговорки

Мы берём на себя долгосрочное обязательство предоставлять точку входа Python, функционально эквивалентную CLI dbt v1. Мы оставляем за собой право менять внутреннюю реализацию, используемую для достижения этой цели. Мы ожидаем, что текущая реализация позволит решать реальные задачи в краткосрочной и среднесрочной перспективе, пока мы работаем над набором стабильных, долгосрочных интерфейсов, которые в конечном итоге её заменят.

В частности, для объектов, возвращаемых каждой командой в `dbtRunnerResult.result`, не определён полный контракт, поэтому они могут изменяться. Некоторые из возвращаемых объектов частично документированы, поскольку отчасти совпадают с содержимым [артефактов dbt](https://docs.getdbt.tech/reference/artifacts/dbt-artifacts.md). Как объекты Python, они содержат гораздо больше полей и методов, чем доступно в сериализованных артефактах JSON. Эти дополнительные поля и методы следует считать **внутренними и подлежащими изменению в будущих версиях dbt.**

## Расширенные шаблоны использования

предупреждение

Синтаксис и поддержка этих подходов могут измениться в будущих версиях dbt.

Цель `dbtRunner` — обеспечить в программной среде те же возможности, что и при работе через CLI. Существует несколько продвинутых подходов к использованию, которые расширяют возможности CLI.

(Версии dbt: v2.0 и новее)

### Повторное использование объектов

Передача готового манифеста не поддерживается в v2. Вы не можете передать предварительно созданный объект `Manifest` в `dbtRunner`.

### Регистрация обработчиков обратного вызова

Регистрация обработчиков обратного вызова в `EventManager` dbt не поддерживается в v2.

### Переопределение параметров

Передавайте параметры как именованные аргументы, а не в виде списка строк в стиле CLI. В настоящее время dbt не выполняет проверку или приведение типов входных значений. Команда должна быть указана в виде списка в первом позиционном аргументе.

```python
from dbt.cli.main import dbtRunner
dbt = dbtRunner()

# эти команды эквивалентны
dbt.invoke(["--fail-fast", "run", "--select", "tag:my_tag"])
dbt.invoke(["run"], select=["tag:my_tag"], fail_fast=True)
```
