Lee-W commented on code in PR #60203:
URL: https://github.com/apache/airflow/pull/60203#discussion_r2844277015
##########
devel-common/src/docs/provider_conf.py:
##########
@@ -276,6 +275,24 @@
if PACKAGE_NAME in ["apache-airflow-providers-google"]:
intersphinx_mapping.update(get_google_intersphinx_mapping())
+# Add task-sdk to intersphinx mapping for proper cross-referencing of SDK
classes
+# This allows proper linking to BaseSensorOperator and other SDK classes from
provider docs
+try:
+ # Import airflow.sdk at runtime to get version for intersphinx mapping
+ # We need to import it here rather than at the top because the SDK may not
be installed
+ # when building provider docs separately
+ import airflow.sdk as _airflow_sdk
+
+ task_sdk_version = parse_version(_airflow_sdk.__version__).base_version
+ intersphinx_mapping["task-sdk"] = (
+ f"https://airflow.apache.org/docs/task-sdk/{task_sdk_version}/";,
+
(f"https://airflow.apache.org/docs/task-sdk/{task_sdk_version}/objects.inv";,),
+ )
+except Exception:
Review Comment:
```suggestion
except ModuleNotFoundError:
```
##########
airflow-core/docs/core-concepts/sensors.rst:
##########
@@ -32,89 +32,62 @@ Much like Operators, Airflow has a large set of pre-built
Sensors you can use, b
.. seealso:: :doc:`../authoring-and-scheduling/deferring`
-BaseSensorOperator parameters
------------------------------
+BaseSensorOperator
+-------------------
-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.
+All sensors share common functionality through the ``BaseSensorOperator``
class. This base class provides
+standardized parameters that control timing behavior, execution modes, and
failure handling across
+every sensor implementation.
-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.
+.. note::
+ In the Task SDK architecture, ``BaseSensorOperator`` is defined in the
``airflow.sdk`` package.
+ Provider documentation is generated separately from the core documentation,
so sensor parameters
+ may not always appear in individual provider sensor API reference pages.
However, these parameters
+ are universally available to all sensors.
-Common parameters
-^^^^^^^^^^^^^^^^^
+Common Sensor Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~
-The following parameters are provided by ``BaseSensorOperator`` and are
-available on all sensors:
+The following parameters control sensor behavior across all implementations:
``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.
+ Specifies how long to wait (in seconds) between successive checks. In
``poke`` mode, the sensor
+ holds a worker slot while waiting. In ``reschedule`` mode, the task is
freed and rescheduled after
+ each interval. Accepts either a ``float`` (seconds) or ``timedelta``
object.
``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.
+ Maximum time (in seconds) before the sensor fails due to exceeding its
allowed runtime.
+ The timeout is calculated from the first execution attempt, not from
individual poke attempts.
+ This differs from ``execution_timeout`` which only measures active task
execution time.
+ Accepts either a ``float`` (seconds) or ``timedelta`` object.
``mode``
- Determines how the sensor occupies worker resources.
+ Controls how the sensor consumes worker resources:
- * ``poke`` (default): occupies a worker slot for the entire duration
- * ``reschedule``: releases the worker slot between checks
+ * ``poke`` (default): The sensor occupies a worker slot continuously while
waiting
+ * ``reschedule``: The sensor releases the worker slot between checks,
freeing resources for other tasks
``soft_fail``
- If set to ``True``, the sensor will be marked as ``SKIPPED`` instead of
- ``FAILED`` when the timeout is reached.
+ When ``True``, timeout causes the sensor to be marked as ``SKIPPED``
instead of ``FAILED``.
+ This is useful when you want non-critical sensors to timeout gracefully
without failing the DAG.
Review Comment:
```suggestion
This is useful when you want non-critical sensors to timeout gracefully
without failing the Dag.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
