This is an automated email from the ASF dual-hosted git repository. ephraimanierobi pushed a commit to branch v3-1-test in repository https://gitbox.apache.org/repos/asf/airflow.git
commit 332310ef548172cb90c45a91054630cc319b2a5e Author: jaymasiwal <[email protected]> AuthorDate: Wed Jan 21 05:40:15 2026 +0530 Docs: clarify BaseSensorOperator parameters in Sensors guide (#60275) (cherry picked from commit 928d5b4ba29dec84b636c300fc1b6915aceef243) --- airflow-core/docs/core-concepts/sensors.rst | 64 +++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/airflow-core/docs/core-concepts/sensors.rst b/airflow-core/docs/core-concepts/sensors.rst index dfe94a50ff7..7897632860a 100644 --- a/airflow-core/docs/core-concepts/sensors.rst +++ b/airflow-core/docs/core-concepts/sensors.rst @@ -30,3 +30,67 @@ The ``poke`` and ``reschedule`` modes can be configured directly when you instan Much like Operators, Airflow has a large set of pre-built Sensors you can use, both in core Airflow as well as via our *providers* system. .. seealso:: :doc:`../authoring-and-scheduling/deferring` + +BaseSensorOperator parameters +----------------------------- + +All sensors in Airflow ultimately inherit from ``BaseSensorOperator`` (directly or indirectly). +This base class defines the common behavior and parameters that control +how a sensor waits, retries, and manages worker resources. + +As of the Task SDK refactor, ``BaseSensorOperator`` is implemented in the +Task SDK. Because provider documentation is generated separately, these +parameters may not always be directly visible on individual provider +sensor API pages. However, they apply to *all* sensors. + +Common parameters +^^^^^^^^^^^^^^^^^ + +The following parameters are provided by ``BaseSensorOperator`` and are +available on all sensors: + +``poke_interval`` + Time in seconds between successive checks. In ``poke`` mode, the sensor + sleeps between checks while occupying a worker slot. In ``reschedule`` + mode, the task is deferred and rescheduled after this interval. + +``timeout`` + Maximum time in seconds the sensor is allowed to run before failing. + This timeout is measured from the first execution attempt, not per poke. + +``mode`` + Determines how the sensor occupies worker resources. + + * ``poke`` (default): occupies a worker slot for the entire duration + * ``reschedule``: releases the worker slot between checks + +``soft_fail`` + If set to ``True``, the sensor will be marked as ``SKIPPED`` instead of + ``FAILED`` when the timeout is reached. + +``exponential_backoff`` + If enabled, the time between checks increases exponentially up to + ``max_wait``. This is useful when polling external systems with + unpredictable availability. + +``max_wait`` + Upper bound (in seconds) for the delay between checks when + ``exponential_backoff`` is enabled. + +For the authoritative API reference, see the Task SDK documentation for +``BaseSensorOperator``: + +https://airflow.apache.org/docs/task-sdk/stable/api.html#airflow.sdk.BaseSensorOperator + +Example +^^^^^^^ + +.. code-block:: python + + BashSensor( + task_id="wait_for_file", + bash_command="test -f /data/input.csv", + poke_interval=60, + timeout=60 * 60, + mode="reschedule", + )
