This is an automated email from the ASF dual-hosted git repository.
hussein-awala pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new dc9abd4c028 Document apache-airflow-mypy package in core docs (#68561)
dc9abd4c028 is described below
commit dc9abd4c02873a64aee64dfb35ab0f3907153fbf
Author: Hussein Awala <[email protected]>
AuthorDate: Mon Jun 15 13:59:37 2026 +0200
Document apache-airflow-mypy package in core docs (#68561)
* Document apache-airflow-mypy package in core docs
Add a "Static Type Checking for Dags" section to the best practices docs
pointing to the standalone apache-airflow-mypy distribution and explaining
when Dag authors would want to use it (accurate mypy results for typed
decorators and operator/@task outputs), with install and configuration
instructions.
* Move static type checking docs to a dedicated how-to page
Address review feedback: keep best-practices lean by moving the
apache-airflow-mypy details into a dedicated howto/static-type-checking
page and leaving only a short cross-reference in the best practices doc.
---
airflow-core/docs/best-practices.rst | 10 ++++
airflow-core/docs/howto/index.rst | 1 +
airflow-core/docs/howto/static-type-checking.rst | 75 ++++++++++++++++++++++++
3 files changed, 86 insertions(+)
diff --git a/airflow-core/docs/best-practices.rst
b/airflow-core/docs/best-practices.rst
index 0c37cbc6ede..9bcdc160613 100644
--- a/airflow-core/docs/best-practices.rst
+++ b/airflow-core/docs/best-practices.rst
@@ -356,6 +356,16 @@ Running ``ruff`` will produce:
By integrating ``ruff`` into your development workflow, you can proactively
address deprecations and maintain code quality, facilitating smoother
transitions between Airflow versions.
+.. _best_practices/static_type_checking:
+
+Static Type Checking for Dags
+-----------------------------
+
+If you type-check your Dags with ``mypy``, the optional
+`apache-airflow-mypy <https://pypi.org/project/apache-airflow-mypy/>`_ plugins
give accurate results for
+Airflow-specific patterns such as typed decorators and operator outputs. See
+:doc:`/howto/static-type-checking` for installation and configuration.
+
.. _best_practices/dynamic_dag_generation:
Dynamic Dag Generation
diff --git a/airflow-core/docs/howto/index.rst
b/airflow-core/docs/howto/index.rst
index 519d230342f..e8ced416586 100644
--- a/airflow-core/docs/howto/index.rst
+++ b/airflow-core/docs/howto/index.rst
@@ -46,6 +46,7 @@ configuring an Airflow environment.
customize-ui
custom-operator
create-custom-decorator
+ static-type-checking
export-more-env-vars
connection
variable
diff --git a/airflow-core/docs/howto/static-type-checking.rst
b/airflow-core/docs/howto/static-type-checking.rst
new file mode 100644
index 00000000000..0d8559434fc
--- /dev/null
+++ b/airflow-core/docs/howto/static-type-checking.rst
@@ -0,0 +1,75 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ .. http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+.. _howto/static-type-checking:
+
+Static Type Checking for Dags
+=============================
+
+Airflow publishes a set of `mypy <https://mypy-lang.org/>`_ plugins as a
standalone, independently
+versioned distribution: `apache-airflow-mypy
<https://pypi.org/project/apache-airflow-mypy/>`_.
+
+When to use it
+--------------
+
+If you run ``mypy`` over your Dags, custom operators, or hooks, install the
plugins to get accurate
+results for Airflow-specific patterns that plain ``mypy`` cannot reason about
and would otherwise report
+as false positives. The plugins teach ``mypy`` about:
+
+* **Typed decorators** -- decorators that inject keyword arguments at runtime
(for example
+ ``GoogleBaseHook.fallback_to_default_project_id``), so ``mypy`` does not
flag those arguments as missing.
+* **Operator outputs** -- the ``.output`` attribute of operators and the
return value of ``@task``-decorated
+ functions (an ``XComArg``) are resolved to the underlying runtime type. This
lets you wire a task's output
+ into a downstream task without spurious type errors:
+
+ .. code-block:: python
+
+ @task
+ def f(a: str) -> int:
+ return len(a)
+
+
+ @task
+ def g(b: int) -> None: ...
+
+
+ g(f("hello")) # mypy understands the output of f() is an int
+
+The package is entirely optional -- Airflow does not require it at runtime; it
only improves the accuracy
+of static type checking for Dag authors.
+
+Installation
+------------
+
+Install it alongside ``mypy``:
+
+.. code-block:: bash
+
+ pip install apache-airflow-mypy
+
+The package follows `SemVer <https://semver.org/>`_ and is released on its own
cadence, so you can adopt it
+independently of your Airflow version.
+
+Configuration
+-------------
+
+Enable the plugins in your ``mypy`` configuration (``mypy.ini``, ``setup.cfg``
or ``pyproject.toml``):
+
+.. code-block:: ini
+
+ [mypy]
+ plugins = airflow_mypy.plugins.decorators, airflow_mypy.plugins.outputs
