diff --git a/task-sdk/docs/api.rst b/task-sdk/docs/api.rst index 8605b234792a6..8c6fc526b5f5f 100644 --- a/task-sdk/docs/api.rst +++ b/task-sdk/docs/api.rst @@ -33,6 +33,15 @@ Decorators .. autoapifunction:: airflow.sdk.dag .. autoapifunction:: airflow.sdk.task +Task Decorators: + +- ``@task.run_if(condition, skip_message=None)`` + Run the task only if the given condition is met; otherwise the task is skipped. The condition is a callable + that receives the task execution context and returns either a boolean or a tuple ``(bool, message)``. +- ``@task.skip_if(condition, skip_message=None)`` + Skip the task if the given condition is met, raising a skip exception with an optional message. +- Provider-specific task decorators under ``@task.``, e.g. ``@task.python``, ``@task.docker``, etc., dynamically loaded from registered providers. + .. autoapifunction:: airflow.sdk.task_group .. autoapifunction:: airflow.sdk.setup diff --git a/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py b/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py index 8df62d12aaadb..c53a84ea71bc8 100644 --- a/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py +++ b/task-sdk/src/airflow/sdk/definitions/decorators/setup_teardown.py @@ -35,6 +35,18 @@ def setup_task(func: Callable) -> Callable: + """ + Decorate a function to mark it as a setup task. + + A setup task runs before all other tasks in its DAG or TaskGroup context + and can perform initialization or resource preparation. + + Example:: + + @setup + def initialize_context(...): + ... + """ # Using FunctionType here since _TaskDecorator is also a callable if isinstance(func, types.FunctionType): func = python_task(func) @@ -45,6 +57,19 @@ def setup_task(func: Callable) -> Callable: def teardown_task(_func=None, *, on_failure_fail_dagrun: bool = False) -> Callable: + """ + Decorate a function to mark it as a teardown task. + + A teardown task runs after all main tasks in its DAG or TaskGroup context. + If ``on_failure_fail_dagrun=True``, a failure in teardown will mark the DAG run as failed. + + Example:: + + @teardown(on_failure_fail_dagrun=True) + def cleanup(...): + ... + """ + def teardown(func: Callable) -> Callable: # Using FunctionType here since _TaskDecorator is also a callable if isinstance(func, types.FunctionType):