This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 8bdd0e72ff Add a note and an example clarifying the usage of DAG-level
params (#40541)
8bdd0e72ff is described below
commit 8bdd0e72ffef0461b4d0828de7fe49def2515804
Author: Dev-iL <[email protected]>
AuthorDate: Tue Jul 2 15:05:11 2024 +0300
Add a note and an example clarifying the usage of DAG-level params (#40541)
---
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 621e289cb6..e1949cafe2 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
-----------------
