This is an automated email from the ASF dual-hosted git repository.
pierrejeambrun pushed a commit to branch v2-5-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v2-5-test by this push:
new 32a2bb67fd Remove extra H1 & improve formatting of Listeners docs page
(#28450)
32a2bb67fd is described below
commit 32a2bb67fdd266732a5680f06a962b6d4c3fc15f
Author: nate contino <[email protected]>
AuthorDate: Mon Dec 19 11:23:03 2022 -0500
Remove extra H1 & improve formatting of Listeners docs page (#28450)
* Remove extra H1 & improve formatting of Listeners docs page
I noticed that the documentation has an unclickable "Usage" page in the
TOC. A little digging later, I discovered that this page contains an extra H1,
and since this page is in the top level of the TOC, all the H1s on this page
show up in the left docs sidebar.
Demoted the "Usage" section to an H2, and fixed the other headers on this
page to use consistent underlining with most other docs pages in this repo. I
also took the liberty of sprucing up the language on the page to follow docs
best practices, like shorter, highly readable sentences, title case in section
titles, and bulleted lists to draw attention to important collections.
* Remove extra newlines from specification discussion
* Remove single newlines from listener API discussion
* Remove nonexistent DagRun events from listeners page
(cherry picked from commit 672264b0af4874274bd130ba42a78e8e72f3d3ff)
---
docs/apache-airflow/listeners.rst | 54 +++++++++++++++++++--------------------
1 file changed, 27 insertions(+), 27 deletions(-)
diff --git a/docs/apache-airflow/listeners.rst
b/docs/apache-airflow/listeners.rst
index cee610d61e..c34689c53f 100644
--- a/docs/apache-airflow/listeners.rst
+++ b/docs/apache-airflow/listeners.rst
@@ -18,43 +18,43 @@
Listeners
=========
-Airflow gives you an option to be notified of events happening in Airflow
-by writing listeners. Listeners are powered by `pluggy
<https://pluggy.readthedocs.io/en/stable/>`__
+You can write listeners to enable Airflow to notify you when events happen.
+`Pluggy <https://pluggy.readthedocs.io/en/stable/>`__ powers these listeners.
-Right now Airflow exposes few types of events.
+Airflow supports notifications for the following events:
-Lifecycle events
-^^^^^^^^^^^^^^^^
-Those events - ``on_starting`` and ``before_stopping`` allow you to react to
-lifecycle to an Airflow ``Job``, like ``SchedulerJob`` or ``BackfillJob``.
+Lifecycle Events
+----------------
-TaskInstance state change events
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Those events - ``on_task_instance_running``, ``on_task_instance_success`` and
``on_task_instance_failed``
-once ``TaskInstance`` state changes to one of the respective states. This
generally happens on ``LocalTaskJob``.
+- ``on_starting``
+- ``before_stopping``
+
+Lifecycle events allow you to react to start and stop events for an Airflow
``Job``, like ``SchedulerJob`` or ``BackfillJob``.
+
+TaskInstance State Change Events
+--------------------------------
+
+- ``on_task_instance_running``
+- ``on_task_instance_success``
+- ``on_task_instance_failed``
+
+TaskInstance state change events occur when a ``TaskInstance`` changes state.
+You can use these events to react to ``LocalTaskJob`` state changes.
-DagRun state change events
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-Those events - ``on_dag_run_running``, ``on_dag_run_success`` and
``on_dag_run_failed``
-once ``DagRun`` state changes to one of the respective states. This generally
happens on ``SchedulerJob`` or ``BackfillJob``.
Usage
-=====
+-----
+
+To create a listener:
-To create a listener you will need to derive the import
-``airflow.listeners.hookimpl`` and implement the ``hookimpls`` for
-events you want to be notified at.
+- import ``airflow.listeners.hookimpl``
+- implement the ``hookimpls`` for events that you'd like to generate
notifications
-Their specification is defined as ``hookspec`` in ``airflow/listeners/spec``
directory.
-Your implementation needs to accept the same named parameters as defined in
hookspec, or Pluggy will complain about your plugin.
-On the other hand, you don't need to implement every method - it's perfectly
fine to have a listener that implements just one method, or any subset of
methods.
+Airflow defines the specification as `hookspec
<https://github.com/apache/airflow/tree/main/airflow/listeners/spec>`__. Your
implementation must accept the same named parameters as defined in hookspec. If
you don't use the same parameters as hookspec, Pluggy throws an error when you
try to use your plugin. But you don't need to implement every method. Many
listeners only implement one method, or a subset of methods.
-To include listener in your Airflow installation, include it as a part of an
:doc:`Airflow Plugin </plugins>`
+To include the listener in your Airflow installation, include it as a part of
an :doc:`Airflow Plugin </authoring-and-scheduling/plugins>`
-Listener API is meant to be called across all dags, and all operators - in
contrast to methods like
-``on_success_callback``, ``pre_execute`` and related family which are meant to
provide callbacks
-for particular dag authors, or operator creators. There is no possibility to
listen on events generated
-by particular dag.
+Listener API is meant to be called across all DAGs and all operators. You
can't listen to events generated by specific DAGs. For that behavior, try
methods like ``on_success_callback`` and ``pre_execute``. These provide
callbacks for particular DAG authors or operator creators.
|experimental|
