0
# Apache Airflow Providers Common Compat
1

2
A compatibility provider package that provides backward compatibility utilities and shims for Apache Airflow to maintain compatibility across different Airflow versions. It includes compatibility modules for standard operators, triggers, utilities, asset/dataset handling, lineage tracking, security permissions, and OpenLineage integration to ensure smooth migrations between Airflow versions.
3

4
## Package Information
5

6
- **Package Name**: apache-airflow-providers-common-compat
7
- **Language**: Python
8
- **Installation**: `pip install apache-airflow-providers-common-compat`
9
- **Minimum Airflow Version**: 2.10.0+
10

11
## Core Imports
12

13
```python
14
from airflow.providers.common.compat import __version__
15
```
16

17
Common compatibility utilities:
18

19
```python
20
from airflow.providers.common.compat.version_compat import (
21
    AIRFLOW_V_3_0_PLUS,
22
    AIRFLOW_V_3_1_PLUS,
23
    BaseOperator
24
)
25
```
26

27
Assets/Dataset compatibility:
28

29
```python
30
from airflow.providers.common.compat.assets import Asset, AssetAlias
31
```
32

33
## Basic Usage
34

35
```python
36
from airflow.providers.common.compat.version_compat import AIRFLOW_V_3_0_PLUS, BaseOperator
37
from airflow.providers.common.compat.assets import Asset
38
from airflow.providers.common.compat.check import require_provider_version
39

40
# Check Airflow version compatibility
41
if AIRFLOW_V_3_0_PLUS:
42
    # Use Airflow 3.0+ features
43
    pass
44

45
# Use version-compatible BaseOperator
46
class MyOperator(BaseOperator):
47
    def execute(self, context):
48
        pass
49

50
# Create assets with version compatibility
51
my_asset = Asset("s3://bucket/data.csv")
52

53
# Require minimum provider version
54
@require_provider_version("apache-airflow-providers-openlineage", "1.0.1")
55
def my_function():
56
    pass
57
```
58

59
## Architecture
60

61
The package provides compatibility across Airflow versions through several key patterns:
62

63
- **Version Detection**: Runtime detection of Airflow version to conditionally import appropriate modules
64
- **Compatibility Wrappers**: Unified interfaces that work across different Airflow versions
65
- **Asset/Dataset Bridging**: Handles the renaming from "Dataset" to "Asset" in Airflow 3.0
66
- **Provider Version Enforcement**: Decorators to ensure minimum provider versions are met
67
- **Graceful Fallbacks**: No-op implementations when optional dependencies aren't available
68

69
## Capabilities
70

71
### Package Information
72

73
Package version and metadata constants.
74

75
```python { .api }
76
__version__: str
77
```
78

79
### Version Compatibility
80

81
Core utilities for detecting Airflow versions and importing version-appropriate modules, including version constants and compatible BaseOperator imports.
82

83
```python { .api }
84
def get_base_airflow_version_tuple() -> tuple[int, int, int]: ...
85
AIRFLOW_V_3_0_PLUS: bool
86
AIRFLOW_V_3_1_PLUS: bool
87
BaseOperator: type
88
```
89

90
[Version Compatibility](./version-compatibility.md)
91

92
### Asset Management
93

94
Version-compatible asset and dataset handling with support for asset aliases, collections, and authorization details that work across Airflow versions.
95

96
```python { .api }
97
class Asset: ...
98
class AssetAlias: ...
99
class AssetAll: ...
100
class AssetAny: ...
101
def expand_alias_to_assets(...): ...
102
```
103

104
[Asset Management](./asset-management.md)
105

106
### Provider Verification
107

108
Decorators and utilities for enforcing minimum version requirements of provider packages and optional dependencies like OpenLineage.
109

110
```python { .api }
111
def require_provider_version(provider_name: str, provider_min_version: str): ...
112
def require_openlineage_version(provider_min_version: str | None = None, client_min_version: str | None = None): ...
113
```
114

115
[Provider Verification](./provider-verification.md)
116

117
### Lineage Entities
118

119
Data lineage entities including files, users, tables, columns, and tags with template field support for dynamic content rendering.
120

121
```python { .api }
122
class File: ...
123
class User: ...
124
class Table: ...
125
class Column: ...
126
class Tag: ...
127
def default_if_none(arg: bool | None) -> bool: ...
128
```
129

130
Lineage collection utilities:
131

132
```python { .api }
133
def get_hook_lineage_collector(): ...
134
```
135

136
[Lineage Entities](./lineage-entities.md)
137

138
### Standard Components
139

140
Version-compatible standard Airflow operators, triggers, and utilities including PythonOperator, TimeDeltaTrigger, and virtualenv preparation functions.
141

142
```python { .api }
143
class PythonOperator(BaseOperator): ...
144
class ShortCircuitOperator(BaseOperator): ...
145
class TimeDeltaTrigger: ...
146
def get_current_context(): ...
147
```
148

149
[Standard Components](./standard-components.md)
150

151
### OpenLineage Integration
152

153
OpenLineage facets, utilities, and compatibility functions for data lineage tracking, including SQL and Spark integration utilities.
154

155
```python { .api }
156
class BaseFacet: ...
157
class Dataset: ...
158
class RunFacet: ...
159
def get_openlineage_facets_with_sql(...): ...
160
def inject_parent_job_information_into_spark_properties(...): ...
161
```
162

163
[OpenLineage Integration](./openlineage-integration.md)
164

165
### Security Permissions
166

167
Security resource constants for assets, backfills, and DAG versions that maintain compatibility across Airflow security model changes.
168

169
```python { .api }
170
RESOURCE_ASSET: str
171
RESOURCE_ASSET_ALIAS: str
172
RESOURCE_BACKFILL: str
173
RESOURCE_DAG_VERSION: str
174
```
175

176
[Security Permissions](./security-permissions.md)
177

178
### Notifier Compatibility
179

180
Version-compatible base notifier class for creating custom notification handlers that work across different Airflow versions.
181

182
```python { .api }
183
class BaseNotifier: ...
184
```
185

186
[Notifier Compatibility](./notifier-compatibility.md)