Skip to content

Add TypedDict type hints for AirflowPlugin list fields - #69761

Open
sivavarma-x wants to merge 7 commits into
apache:mainfrom
sivavarma-x:wip/issue#62222
Open

Add TypedDict type hints for AirflowPlugin list fields#69761
sivavarma-x wants to merge 7 commits into
apache:mainfrom
sivavarma-x:wip/issue#62222

Conversation

@sivavarma-x

@sivavarma-x sivavarma-x commented Jul 11, 2026

Copy link
Copy Markdown

Most AirflowPlugin list fields (external_views, react_apps, fastapi_apps, fastapi_root_middlewares, macros) were typed as list[Any], giving plugin authors no static signal about the shape of the entries they're expected to supply.

This PR introduces TypedDict definitions in airflow_shared.plugins_manager that mirror the corresponding API response models (ExternalViewResponse, ReactAppResponse, FastAPIAppResponse, FastAPIRootMiddlewareResponse) and re-exports them from airflow.plugins_manager so plugin authors can annotate their dict literals.

What's typed

  • ExternalViewDict — mirrors ExternalViewResponse.
  • ReactAppDict — mirrors ReactAppResponse.
  • FastAPIAppDict — mirrors FastAPIAppResponse.
  • FastAPIRootMiddlewareDict — mirrors FastAPIRootMiddlewareResponse.
  • _BaseUIDict factors the common UI fields (name, icon, icon_dark_mode, url_route, category, nav_top_level).
  • BaseDestinationLiteral factors the destination values shared between ExternalViewDict and ReactAppDict; ReactAppDict extends it with "dashboard", "dag_overview", "task_overview".
  • macros is narrowed from list[Any] to list[Callable[..., Any]].
  • _get_ui_plugins() return type is narrowed from tuple[list[Any], list[Any]] to tuple[list[ExternalViewDict], list[ReactAppDict]].

What's left as list[Any]

  • flask_blueprints — plugins pass flask.Blueprint instances, not dicts.
  • admin_views, menu_links — legacy Flask-Admin.
  • appbuilder_views, appbuilder_menu_items — deprecated in the API response in favor of external_views.
  • operator_extra_links, global_operator_extra_links, listeners, timetables, windows, partition_mappers, deadline_references, hook_lineage_readers, priority_weight_strategies — class instances, not dict-shaped.

Provider updates

common.ai (HITL Review) and edge3 pick up the new FastAPIAppDict / ReactAppDict types under TYPE_CHECKING guards — no runtime cost.

Backwards compatibility

Runtime behavior is unchanged — TypedDict is a plain dict, so every existing plugin continues to load and render as before. The changes are type-only.
Plugin authors running mypy will now see errors for missing required fields, misspelled keys, or destination values outside the documented set.

closes: #62222


Was generative AI tooling used to co-author this PR?
  • Yes — gpt-5.5 and Claude Opus 4.7

Generated-by: gpt-5.5 and Claude Opus 4.7 following the guidelines

@boring-cyborg

boring-cyborg Bot commented Jul 11, 2026

Copy link
Copy Markdown

Congratulations on your first Pull Request and welcome to the Apache Airflow community! If you have any issues or are unsure about any anything please check our Contributors' Guide
Here are some useful points:

  • Pay attention to the quality of your code (ruff, mypy and type annotations). Our prek-hooks will help you with that.
  • In case of a new feature add useful documentation (in docstrings or in docs/ directory). Adding a new operator? Check this short guide Consider adding an example Dag that shows how users should use it.
  • Consider using Breeze environment for testing locally, it's a heavy docker but it ships with a working Airflow and a lot of integrations.
  • Be patient and persistent. It might take some time to get a review or get the final approval from Committers.
  • Please follow ASF Code of Conduct for all communication including (but not limited to) comments on Pull Requests, Mailing list and Slack.
  • Be sure to read the Airflow Coding style.
  • Always keep your Pull Requests rebased, otherwise your build might fail due to changes not related to your commits.
    Apache Airflow is a community-driven project and together we are making it better 🚀.
    In case of doubts contact the developers at:
    Mailing List: dev@airflow.apache.org
    Slack: https://s.apache.org/airflow-slack

@sivavarma-x
sivavarma-x force-pushed the wip/issue#62222 branch 2 times, most recently from 4aed6ab to b2bee89 Compare July 17, 2026 16:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

More thorough type hinting for AirflowPlugin attributes

1 participant