From dcea26c4926f4f95a5bfd945f8cf167ea1895fc6 Mon Sep 17 00:00:00 2001 From: Dev-iL Date: Tue, 2 Jul 2024 15:05:11 +0300 Subject: [PATCH] Add a note and an example clarifying the usage of DAG-level params (#40541) (cherry picked from commit 8bdd0e72ffef0461b4d0828de7fe49def2515804) --- docs/apache-airflow/core-concepts/params.rst | 32 ++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/docs/apache-airflow/core-concepts/params.rst b/docs/apache-airflow/core-concepts/params.rst index 621e289cb6ba3..e1949cafe2f39 100644 --- a/docs/apache-airflow/core-concepts/params.rst +++ b/docs/apache-airflow/core-concepts/params.rst @@ -36,9 +36,10 @@ To add Params to a :class:`~airflow.models.dag.DAG`, initialize it with the ``pa Use a dictionary that maps Param names to either a :class:`~airflow.models.param.Param` or an object indicating the parameter's default value. .. code-block:: - :emphasize-lines: 6-9 + :emphasize-lines: 7-10 from airflow import DAG + from airflow.decorators import task from airflow.models.param import Param with DAG( @@ -47,7 +48,34 @@ Use a dictionary that maps Param names to either a :class:`~airflow.models.param "x": Param(5, type="integer", minimum=3), "my_int_param": 6 }, - ): + ) as dag: + + @task.python + def example_task(params: dict): + # This will print the default value, 6: + dag.log.info(dag.params['my_int_param']) + + # This will print the manually-provided value, 42: + dag.log.info(params['my_int_param']) + + # This will print the default value, 5, since it wasn't provided manually: + dag.log.info(params['x']) + + example_task() + + if __name__ == "__main__": + dag.test( + run_conf={"my_int_param": 42} + ) + +.. note:: + + DAG-level parameters are the default values passed on to tasks. These should not be confused with values manually + provided through the UI form or CLI, which exist solely within the context of a :class:`~airflow.models.dagrun.DagRun` + and a :class:`~airflow.models.taskinstance.TaskInstance`. This distinction is crucial for TaskFlow DAGs, which may + include logic within the ``with DAG(...) as dag:`` block. In such cases, users might try to access the manually-provided + parameter values using the ``dag`` object, but this will only ever contain the default values. To ensure that the + manually-provided values are accessed, use a template variable such as ``params`` or ``ti`` within your task. Task-level Params -----------------