> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitra.atomo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# dag

# `orbitra.dags.airflow.dag`

`OrbitraDAG`: an Airflow DAG carrying uv settings that every `@orbitra_task` inherits.

## Functions

### `orbitra_dag`

```python theme={null}
orbitra_dag(dag_id_or_func: str | Callable[..., Any] | None = None, **kwargs: Any) -> Any
```

Decorator form of `OrbitraDAG`, mirroring `airflow.sdk.dag`.

Usage is identical to `@dag`, accepting the same arguments plus the task defaults `OrbitraDAG` takes.

**Examples:**

Nothing configured: uv tasks discover the DAGs folder's project on their own::

@orbitra\_dag(start\_date=..., schedule="@daily")
def reporting():
@orbitra\_task
def render(): ...

render()

dag = reporting()

A shared environment for every uv task in the DAG::

@orbitra\_dag(start\_date=..., schedule="@daily", uv\_project\_dir="envs/reporting")
def reporting():
@orbitra\_task
def render(): ...

render()

dag = reporting()

**Args:**

* `dag_id_or_func`: The DAG id, or the decorated function when used without parentheses.
* `**kwargs`: `OrbitraDAG` keyword arguments.

**Returns:**

* A factory that builds the `OrbitraDAG` when called.

## Classes

### `OrbitraDAG`

An Airflow DAG that distributes default settings to the orbitra tasks declared inside it.

Any setting accepted here that has the same name as an `@orbitra_task` argument becomes the DAG-wide
default for that argument: `uv_project_dir="envs/reporting"` on the DAG is the same as writing it on
every task. A task that sets the argument itself wins. Everything else behaves exactly like `DAG`.

**Examples:**

Nothing configured: a plain DAG whose uv tasks discover the project by walking up from the DAG
file (the DAGs folder's `pyproject.toml` + `uv.lock`)::

with OrbitraDAG("reporting", start\_date=..., schedule="@daily") as dag:

@orbitra\_task
def render(payload: dict) -> str: ...

A shared environment for every uv task in the DAG, with one task adding a group::

with OrbitraDAG("reporting", start\_date=..., schedule="@daily", uv\_project\_dir="envs/reporting") as dag:

@orbitra\_task                        # envs/reporting
def render(payload: dict) -> str: ...

@orbitra\_task(uv\_groups=\["plots"])   # envs/reporting + the plots group
def publish(report: str) -> None: ...

Under the hood the values go into the DAG's `default_args`, so Airflow applies them to every task
that accepts the argument; keys already present in `default_args` win.

**Args:**

* `uv_project_dir`: Directory with `pyproject.toml` + `uv.lock` for the uv tasks. Absolute, or
  relative to the DAG bundle root / DAG file directory. Unset keeps automatic discovery.
* `uv_sync_options`: `uv sync` flags.
* `uv_groups`: Dependency groups (`--group X`).
* `uv_extras`: Extras (`--extra X`).
* `venv_cache_path`: Venv cache directory. Unset keeps the operator default, the
  `orbitra_dags_venv_cache` setting; `None` disables caching for every uv task in the DAG.

**Methods:**

#### `orbitra_task_defaults`

```python theme={null}
orbitra_task_defaults(self) -> dict[str, Any]
```

Return the task defaults set on this DAG, keyed by task argument name.

Generic over the fields this class adds to `DAG`: every one whose value differs from its default
is included under its own name. Values are normalised to JSON-friendly types (paths to `str`,
sequences to `list`) because `default_args` is serialized with the DAG.

**Returns:**

* Mapping from task argument name to the configured default. Unset settings are omitted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.