This is an automated email from the ASF dual-hosted git repository. ephraimanierobi pushed a commit to branch v2-6-test in repository https://gitbox.apache.org/repos/asf/airflow.git
commit e26702dc6f9287b40df5c3b6481cb65fad0119af Author: Jarek Potiuk <[email protected]> AuthorDate: Tue May 2 19:50:44 2023 +0200 Fix missing models in API documentation. (#31021) The Airflow models have been accidentally removed from the docs when #28300 was implemented. The whole models documentation have been removed accidentally, even if there were references to the actual classes and packages used as the models package was entirely excluded. This PR fixes it by selectively including the models that should be included and by linking the package indexes directly in the public interface documentation. (cherry picked from commit 6720a90af7d45088a6b08d8757eb258baa936afd) --- airflow/models/taskinstance.py | 4 +- docs/apache-airflow/public-airflow-interface.rst | 54 +++++++++++++++++++++++- docs/conf.py | 18 ++++++++ docs/spelling_wordlist.txt | 1 + 4 files changed, 74 insertions(+), 3 deletions(-) diff --git a/airflow/models/taskinstance.py b/airflow/models/taskinstance.py index d4e37741c3..3b56583b1e 100644 --- a/airflow/models/taskinstance.py +++ b/airflow/models/taskinstance.py @@ -194,8 +194,8 @@ def clear_task_instances( :param tis: a list of task instances :param session: current session - :param dag_run_state: state to set DagRun to. If set to False, dagrun state will not - be changed. + :param dag_run_state: state to set finished DagRuns to. + If set to False, DagRuns state will not be changed. :param dag: DAG object :param activate_dag_runs: Deprecated parameter, do not pass """ diff --git a/docs/apache-airflow/public-airflow-interface.rst b/docs/apache-airflow/public-airflow-interface.rst index 4718d18b54..6d36de5df1 100644 --- a/docs/apache-airflow/public-airflow-interface.rst +++ b/docs/apache-airflow/public-airflow-interface.rst @@ -58,7 +58,9 @@ DAGs ---- The DAG is Airflow's core entity that represents a recurring workflow. You can create a DAG by -instantiating the :class:`~airflow.models.dag.DAG` class in your DAG file. +instantiating the :class:`~airflow.models.dag.DAG` class in your DAG file. You can also instantiate +them via :class::`~airflow.models.dagbag.DagBag` class that reads DAGs from a file or a folder. DAGs +can also have parameters specified via :class::`~airflow.models.param.Param` class. Airflow has a set of example DAGs that you can use to learn how to write DAGs @@ -73,6 +75,17 @@ You can read more about DAGs in :doc:`DAGs <core-concepts/dags>`. .. _pythonapi:operators: +References for the modules used in DAGs are here: + +.. toctree:: + :includehidden: + :glob: + :maxdepth: 1 + + _api/airflow/models/dag/index + _api/airflow/models/dagbag/index + _api/airflow/models/param/index + Operators --------- @@ -114,6 +127,30 @@ Also you can learn how to write a custom operator in :doc:`howto/custom-operator .. _pythonapi:hooks: +References for the modules used in for operators are here: + +.. toctree:: + :includehidden: + :glob: + :maxdepth: 1 + + _api/airflow/models/baseoperator/index + + +Task Instances +-------------- + +Task instances are the individual runs of a single task in a DAG (in a DAG Run). They are available in the context +passed to the execute method of the operators via the :class:`~airflow.models.taskinstance.TaskInstance` class. + +.. toctree:: + :includehidden: + :glob: + :maxdepth: 1 + + _api/airflow/models/taskinstance/index + + Hooks ----- @@ -144,6 +181,19 @@ use the following classes: You can read more about the public Airflow utilities in :doc:`howto/connection`, :doc:`core-concepts/variables`, :doc:`core-concepts/xcoms` + +Reference for classes used for the utilities are here: + +.. toctree:: + :includehidden: + :glob: + :maxdepth: 1 + + _api/airflow/models/connection/index + _api/airflow/models/variable/index + _api/airflow/models/xcom/index + + Public Exceptions ----------------- @@ -348,6 +398,8 @@ Airflow can help track origins of data, what happens to it and where it moves ov about lineage in :doc:`administration-and-deployment/lineage`. + + What is not part of the Public Interface of Apache Airflow? =========================================================== diff --git a/docs/conf.py b/docs/conf.py index fb6c82c25b..5e0f81474a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -228,6 +228,7 @@ if PACKAGE_NAME == "apache-airflow": "decorators", "example_dags", "executors", + "models", "operators", "providers", "secrets", @@ -238,6 +239,17 @@ if PACKAGE_NAME == "apache-airflow": } browsable_utils: set[str] = set() + models_included: set[str] = { + "baseoperator.py", + "connection.py", + "dag.py", + "dagbag.py", + "param.py", + "taskinstance.py", + "variable.py", + "xcom.py", + } + root = ROOT_DIR / "airflow" for path in root.iterdir(): if path.is_file() and path.name not in _allowed_top_level: @@ -249,6 +261,12 @@ if PACKAGE_NAME == "apache-airflow": for path in (root / "utils").iterdir(): if path.name not in browsable_utils: exclude_patterns.append(_get_rst_filepath_from_path(path)) + + for path in (root / "models").iterdir(): + if path.name not in models_included: + exclude_patterns.append(_get_rst_filepath_from_path(path)) + + elif PACKAGE_NAME != "docker-stack": exclude_patterns.extend( _get_rst_filepath_from_path(f) for f in pathlib.Path(PACKAGE_DIR).glob("**/example_dags") diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index d7074f4cfd..373b5ff4a7 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -330,6 +330,7 @@ dagbags DagCallbackRequest DagFileProcessorManager dagmodel +DagParam Dagre dagre DagRun
