diff --git a/providers/standard/src/airflow/providers/standard/example_dags/example_branch_operator_decorator.py b/providers/standard/src/airflow/providers/standard/example_dags/example_branch_operator_decorator.py index 3c8c2ba16057f..5648f3eab72c2 100644 --- a/providers/standard/src/airflow/providers/standard/example_dags/example_branch_operator_decorator.py +++ b/providers/standard/src/airflow/providers/standard/example_dags/example_branch_operator_decorator.py @@ -15,11 +15,19 @@ # KIND, either express or implied. See the License for the # specific language governing permissions and limitations # under the License. -"""Example DAG demonstrating the usage of the branching TaskFlow API decorators. +""" +### Branching TaskFlow Decorator Example + +This DAG demonstrates the branching TaskFlow API decorators, which let a +Python callable choose which downstream task(s) to run. + +**What this DAG shows:** -It shows how to use standard Python ``@task.branch`` as well as the external Python -version ``@task.branch_external_python`` which calls an external Python interpreter and -the ``@task.branch_virtualenv`` which builds a temporary Python virtual environment. +- `@task.branch` — branch on a standard Python task +- `@task.branch_external_python` — branch on a callable run with an external + Python interpreter +- `@task.branch_virtualenv` — branch on a callable run inside a temporary + Python virtual environment """ from __future__ import annotations @@ -42,6 +50,7 @@ catchup=False, schedule="@daily", tags=["example", "example2"], + doc_md=__doc__, ) as dag: run_this_first = EmptyOperator(task_id="run_this_first") diff --git a/providers/standard/src/airflow/providers/standard/example_dags/example_sensor_decorator.py b/providers/standard/src/airflow/providers/standard/example_dags/example_sensor_decorator.py index 64ea80400ceb8..623e1802fcf20 100644 --- a/providers/standard/src/airflow/providers/standard/example_dags/example_sensor_decorator.py +++ b/providers/standard/src/airflow/providers/standard/example_dags/example_sensor_decorator.py @@ -37,6 +37,19 @@ tags=["example"], ) def example_sensor_decorator(): + """ + ### Sensor TaskFlow Decorator Example + + This DAG demonstrates the `@task.sensor` decorator for building sensors as + TaskFlow tasks. A sensor task waits for an external condition before allowing + downstream tasks to run. + + **What this DAG shows:** + + - Defining a sensor task with `@task.sensor` (poke interval, timeout, mode) + - Returning a `PokeReturnValue` to signal completion and pass an XCom value + - Wiring the sensor to a downstream task with `>>` + """ # [END instantiate_dag] # [START wait_function] diff --git a/providers/standard/src/airflow/providers/standard/example_dags/example_short_circuit_decorator.py b/providers/standard/src/airflow/providers/standard/example_dags/example_short_circuit_decorator.py index 598778edfd82e..a6b7519f20e75 100644 --- a/providers/standard/src/airflow/providers/standard/example_dags/example_short_circuit_decorator.py +++ b/providers/standard/src/airflow/providers/standard/example_dags/example_short_circuit_decorator.py @@ -27,6 +27,21 @@ @dag(schedule=None, start_date=pendulum.datetime(2021, 1, 1, tz="UTC"), catchup=False, tags=["example"]) def example_short_circuit_decorator(): + """ + ### Short Circuit TaskFlow Decorator Example + + This DAG demonstrates the `@task.short_circuit()` TaskFlow decorator. A + short-circuit task evaluates a Python callable that returns a truthy or + falsy value: when falsy, downstream tasks are skipped without running. + + **What this DAG shows:** + + - Defining a short-circuit task with `@task.short_circuit()` + - Branching execution paths based on a Python condition + - Combining short-circuit decisions with explicit `trigger_rule`s on + downstream tasks via `ignore_downstream_trigger_rules=False` + """ + # [START howto_operator_short_circuit] @task.short_circuit() def check_condition(condition):