Add compatibility lazy imports for Airflow 2 to 3 upgrade #56790
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
boring-cyborg
bot
added
area:dev-tools
area:providers
backport-to-v3-1-test
kaxil
force-pushed
the
add-comprehensive-compat-imports
branch
from
2eb2600 to
1bbd79b
Compare
kaxil
force-pushed
the
add-comprehensive-compat-imports
branch
from
1bbd79b to
f8abdd7
Compare
kaxil
changed the title
kaxil
force-pushed
the
add-comprehensive-compat-imports
branch
2 times, most recently
from
1acbf6e to
929f158
Compare
kaxil
removed
the
backport-to-v3-1-test
kaxil
force-pushed
the
add-comprehensive-compat-imports
branch
3 times, most recently
from
47224d1 to
ce29858
Compare
This change adds 94 compatibility imports to the common.compat provider to help
users and Provider Maintainers migrate from Airflow 2.x to Airflow 3.x. The
imports cover commonly used classes including hooks, sensors, operators,
decorators, models, exceptions, assets, utilities, and entire moved modules.
Key features:
- Lazy imports using __getattr__ to avoid loading unnecessary modules
- Multi-fallback support: tries Airflow 3 paths first, falls back to Airflow 2
- Separate maps for different import types:
* _RENAME_MAP: Classes renamed between versions (Asset/Dataset)
* _IMPORT_MAP: Classes/functions that moved but kept same name
* _MODULE_MAP: Entire modules that moved (timezone, io)
- Type stubs (.pyi) for full IDE autocomplete support
- Prek hook to keep type stubs in sync with import maps
- Optional import validation for developers with full Airflow installed
Users and Provider Authors/Maintainers can now import from
airflow.providers.common.compat.lazy_compat:
```py
from airflow.providers.common.compat.lazy_compat import (
BaseHook,
BaseOperator,
PythonOperator,
Asset, # was Dataset in 2.x, automatically handled
DAG,
task,
timezone, # entire module
io, # entire module
)
now = timezone.utcnow()
fs = io.get_fs("s3://bucket/path")
asset = Asset(uri="s3://bucket/key") # Dataset in 2.x, Asset in 3.x
```
This enables DAG code to work seamlessly across both Airflow 2.10+ and 3.x
without modification, supporting phased migration strategies.
Renamed classes supported (2.x → 3.x):
- Dataset → Asset
- DatasetAlias → AssetAlias
- DatasetAll → AssetAll
- DatasetAny → AssetAny
Benefits:
- Single source of truth for compatibility imports
- Cleaner, more maintainable code with explicit handling of renames vs. moves
- Easy to add more imports and renames in the future
- Better error messages for debugging
- Reduces boilerplate in provider code
Benefits:
- Single source of truth for compatibility imports
- Cleaner, more maintainable code with explicit handling of renames vs. moves
- Easy to add more imports and renames in the future
- Better error messages for debugging
- Reduces boilerplate in provider code
kaxil
force-pushed
the
add-comprehensive-compat-imports
branch
from
ce29858 to
6620f4c
Compare
Member
|
Indeed very nice :) thanks @kaxil |
kaxil
added a commit
that referenced
this pull request
Oct 18, 2025
Simplify version-specific imports in the Google provider by using lazy_compat from common.compat provider added in #56790 for components that are available since Airflow 3.0.
abdulrahman305 bot
pushed a commit
to abdulrahman305/airflow
that referenced
this pull request
Oct 19, 2025
abdulrahman305 bot
pushed a commit
to abdulrahman305/airflow
that referenced
this pull request
Oct 19, 2025
Simplify version-specific imports in the Google provider by using lazy_compat from common.compat provider added in apache#56790 for components that are available since Airflow 3.0.
kaxil
added a commit
to astronomer/airflow
that referenced
this pull request
Oct 20, 2025
Consolidate the Standard provider's compatibility logic by replacing imports from version_compat.py with direct imports from lazy_compat, providing a single source of truth for all Airflow 2.x ↔ 3.x compatibility. Follow-up of apache#56790 & apache#56793
kaxil
added a commit
to astronomer/airflow
that referenced
this pull request
Oct 20, 2025
Consolidate the Standard provider's compatibility logic by replacing imports from version_compat.py with direct imports from lazy_compat, providing a single source of truth for all Airflow 2.x ↔ 3.x compatibility. Follow-up of apache#56790 & apache#56793
nailo2c
pushed a commit
to nailo2c/airflow
that referenced
this pull request
Oct 20, 2025
nailo2c
pushed a commit
to nailo2c/airflow
that referenced
this pull request
Oct 20, 2025
Simplify version-specific imports in the Google provider by using lazy_compat from common.compat provider added in apache#56790 for components that are available since Airflow 3.0.
kaxil
added a commit
to astronomer/airflow
that referenced
this pull request
Oct 21, 2025
Consolidate the Standard provider's compatibility logic by replacing imports from version_compat.py with direct imports from lazy_compat, providing a single source of truth for all Airflow 2.x ↔ 3.x compatibility. Follow-up of apache#56790 & apache#56793
kaxil
added a commit
to astronomer/airflow
that referenced
this pull request
Oct 21, 2025
Consolidate the Standard provider's compatibility logic by replacing imports from version_compat.py with direct imports from lazy_compat, providing a single source of truth for all Airflow 2.x ↔ 3.x compatibility. Follow-up of apache#56790 & apache#56793
kaxil
added a commit
to astronomer/airflow
that referenced
this pull request
Oct 21, 2025
Consolidate the Standard provider's compatibility logic by replacing imports from version_compat.py with direct imports from lazy_compat, providing a single source of truth for all Airflow 2.x ↔ 3.x compatibility. Follow-up of apache#56790 & apache#56793
Jonpaco23
pushed a commit
to Jonpaco23/airflow
that referenced
this pull request
Oct 21, 2025
) Consolidate the Standard provider's compatibility logic by replacing imports from version_compat.py with direct imports from lazy_compat, providing a single source of truth for all Airflow 2.x ↔ 3.x compatibility. Follow-up of apache#56790 & apache#56793
amoghrajesh
reviewed
Oct 22, 2025
Contributor
amoghrajesh
left a comment
amoghrajesh
left a comment
There was a problem hiding this comment.
This is really nice, thanks for this @kaxil!
69 tasks
TyrellHaywood
pushed a commit
to TyrellHaywood/airflow
that referenced
this pull request
Oct 22, 2025
TyrellHaywood
pushed a commit
to TyrellHaywood/airflow
that referenced
this pull request
Oct 22, 2025
Simplify version-specific imports in the Google provider by using lazy_compat from common.compat provider added in apache#56790 for components that are available since Airflow 3.0.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change adds 89 compatibility imports to the
common.compatprovider to helpusers and Provider Maintainers migrate from Airflow 2.x to Airflow 3.x. The
imports cover commonly used classes including hooks, sensors, operators,
decorators, models, exceptions, assets, utilities, and entire moved modules.
Key features:
timezone,io).pyi) for full IDE autocomplete supportUsers (or Provider Authors/Maintainers) can now import from
airflow.providers.common.compat.lazy_compat:
This enables DAG code to work seamlessly across both Airflow 2.10+ and 3.x
without modification, supporting phased migration strategies.
TODO: