API reference

This reference is generated from public signatures and docstrings.

Configuration

Configuration.default_operator_args is a list of mappings. Each mapping contains an operator import path or class followed by default task arguments. The selector matches task model instances or subclasses of an installed Airflow operator class. Later matching entries override earlier entries. Explicit task values, including None, override these defaults. Values are validated against the task model and copied for each task. The rules apply to tasks in Configuration.dags.

Operator defaults become task arguments, taking precedence over the DAG’s default_args and global default_task_args during rendering and instantiation.

pydantic model airflow_config.configuration.base.Configuration

Bases: BaseModel

field default_task_args: TaskArgs [Optional]

Global default default_args (task arguments)

field default_dag_args: DagArgs [Optional]

Global default dag arguments

field default_operator_args: list[_OperatorDefaults] [Optional]

Default task arguments selected by task model or operator class

field dags: dict[str, Annotated[Dag, SerializeAsAny()]] [Optional]

List of dags statically configured via Pydantic

field templates: _Templates | None [Optional]

Templates for DAGs and Tasks

field extensions: dict[str, BaseModel] [Optional]

Any user-defined extensions

field env: str | None = ''

Environment to use for this configuration

field name: str | None = ''

Name of the configuration

field root: Path | None = None

Root path

field tags: dict[str, str] | None [Optional]

Generic Tags for config. NOTE: Not related to dag tags

property default_args

static load(config_dir: str = 'config', config_name: str = '', overrides: list[str] | None = None, *, basepath: str = '', _offset: int = 3) → Configuration

pre_apply(dag, dag_kwargs)

apply(dag, dag_kwargs)

generate_in_mem(dir: Path | str | None = None, placeholder_dag_id: str = 'airflow-config-generate-dags')

generate(dir: Path | str | None = None, *, airflow_major_version: Literal[2, 3])

airflow_config.configuration.base.load_config(config_dir: str = 'config', config_name: str = '', overrides: list[str] | None = None, *, basepath: str = '', _offset: int = 3) → Configuration

DAG creation

class airflow_config.dag.DAG(config: Configuration | None = None, **kwargs)

Bases: DAG

airflow_config.dag.create_dag(arg, **kwargs: Any) → DAG

airflow_config.dag.create_dag(config: Configuration, dag_id: str = '', _offset: int = 3) → DAG

airflow_config.dag.create_dag(config_dir: str = 'config', config_name: str = '', overrides: list[str] | None = None, dag_id: str = '', **kwargs: Any) → DAG

airflow_config.dag.create_dags(arg, **kwargs: Any) → list[DAG]

airflow_config.dag.create_dags(configs: list, dag_ids: list[str] | None = None, **kwargs: Any) → list[DAG]

airflow_config.dag.create_dags(config_dir: str = 'config', config_names: list[str] | None = None, overrides: list[str] | None = None, dag_id_base: str = '', **kwargs: Any) → list[DAG]

airflow_config.dag.generate_dag_id(name: str = '', dag_root: str = '', offset: int = 2) → str

Utilities

Configuration testing

airflow_config.testing provides database-free assertions over stored model definitions. DAG and task IDs refer to mapping keys. Disabled definitions are included; DAGs produced by extensions are outside these assertions.

• assert_dag_ids(config, expected) checks the exact set of configuration DAG keys.

• assert_task_ids(dag, expected) checks the exact set of task keys in a DAG model.

• assert_task_type(dag, task_id, expected) accepts a task model class or an installed Airflow operator base class. Subclasses match. A missing task reports the available keys; a type mismatch reports the actual model and operator.

ID mismatches raise AssertionError with missing and unexpected keys. These assertions inspect definitions and do not execute tasks or resolve connections.

Assertions for configuration models without an Airflow database.

airflow_config.testing.assert_dag_ids(config: Configuration, expected: Collection[str]) → None

Assert the exact set of DAG keys in a configuration.

airflow_config.testing.assert_task_ids(dag: Dag, expected: Collection[str]) → None

Assert the exact set of task keys in a DAG model.

airflow_config.testing.assert_task_type(dag: Dag, task_id: str, expected: type) → None

Assert a task model type or an installed Airflow operator base class.

airflow_config.utils.generate_dag_id(name: str = '', dag_root: str = '', offset: int = 2) → str

Exceptions

exception airflow_config.exceptions.ConfigFileExtensionError

Bases: ValueError

Raised when a configuration file uses an unsupported extension.

exception airflow_config.exceptions.ConfigNotFoundError(config_dir, dagfile)

Bases: RuntimeError

Viewer functions

airflow_config.ui.functions.get_configs_from_yaml(yaml: str | Path, overrides: Sequence[str]) → str

airflow_config.ui.functions.get_dags_folder() → str | None

Resolve the dags folder from the environment, falling back to the Airflow config.

Returns None when Airflow is unavailable, so the standalone viewer can supply its own default.

airflow_config.ui.functions.get_yaml_files(dags_folder: str | Path) → list[Path]