datahub-airflow-plugin-lite 0.1.1__tar.gz

datahub_airflow_plugin_lite-0.1.1/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: datahub-airflow-plugin-lite
+Version: 0.1.1
+Summary: Dependency-free DataHub listener plugin for Apache Airflow
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: acryl-datahub[datahub-rest]; extra == "dev"
+
+# datahub-airflow-plugin-lite
+
+Airflow 실행 메타데이터와 lineage를 DataHub로 보내는 **런타임 의존성 0개** 플러그인입니다.
+표준 라이브러리와 이미 설치된 Airflow만 사용하므로 MWAA 등 Airflow constraints 파일과 충돌하지 않습니다.
+
+| 항목        | 지원 범위             | 검증한 조합                                        |
+| ----------- | --------------------- | -------------------------------------------------- |
+| Python      | 3.9 이상              | 3.9.6, 3.12.13                                     |
+| Airflow     | 2.9.1 이상 (3.x 포함) | 2.9.1, 2.11.2, 3.1.0                               |
+| DataHub GMS | 1.4.0.3 이상          | URN/aspect를 acryl-datahub 1.4.0.3 SDK 출력과 대조 |
+
+## 설치
+
+```bash
+pip install datahub-airflow-plugin-lite-0.1.1-py3-none-any.whl
+```
+
+공식 플러그인(`acryl-datahub-airflow-plugin`)과 동시에 설치하지 마세요. 두 리스너가 같은 엔티티를 중복 전송합니다.
+
+## 설정
+
+`airflow.cfg`의 `[datahub]` 섹션(또는 `AIRFLOW__DATAHUB__*` 환경변수)을 읽습니다. 키 이름은 공식 플러그인과 같습니다.
+
+```ini
+[datahub]
+# GMS 주소/토큰을 직접 지정하거나, 생략하면 conn_id 커넥션(host=GMS URL, password=토큰)을 사용
+gms_url = https://datahub-gms.example.com
+token = <personal access token>
+conn_id = datahub_rest_default
+cluster = prod
+platform_instance =
+capture_ownership_info = true
+capture_ownership_as_group = false
+capture_tags_info = true
+capture_executions = true
+materialize_iolets = true
+capture_airflow_assets = true
+enable_datajob_lineage = true
+enable_openlineage_facets = true
+openlineage_timeout_sec = 5
+supplement_with_sql_parser = true
+athena_include_result_location = false
+dag_filter_str = {"allow": [".*"], "deny": []}
+timeout_sec = 10
+retries = 2
+ssl_verify = true
+```
+
+운영 스위치도 공식 플러그인과 같습니다.
+
+- `AIRFLOW_VAR_DATAHUB_AIRFLOW_PLUGIN_DISABLE_LISTENER=true`: 리스너 즉시 중지 (kill switch)
+- `DATAHUB_AIRFLOW_PLUGIN_RUN_IN_THREAD`, `DATAHUB_AIRFLOW_PLUGIN_RUN_IN_THREAD_TIMEOUT`: 백그라운드 스레드 실행 여부와 대기 시간
+
+## 동작
+
+| Airflow 이벤트   | 전송 내용                                                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| DAG run 시작     | DataFlow (`dataFlowInfo`, `status`, `browsePathsV2`, `ownership`, `globalTags`, `dataPlatformInstance`), 태스크·태그 `status` |
+| 태스크 시작      | DataJob (`dataJobInfo`, `status`, `ownership`, `globalTags`), 실행 기록 (`dataProcessInstance*`, STARTED)                     |
+| 태스크 성공/실패 | DataJob + `dataJobInputOutput`(lineage), 실행 결과(COMPLETE, SUCCESS/FAILURE), 실행 입출력, 데이터셋 `status`                 |
+
+전송은 GMS의 `POST /aspects?action=ingestProposal` 하나만 사용합니다.
+모든 처리는 데몬 스레드에서 실행되고, 예외는 로그로만 남기므로 태스크 실패로 이어지지 않습니다.
+
+### Lineage 소스
+
+1. `inlets`/`outlets`의 `Dataset`/`Urn` 객체 또는 `urn:li:...` 문자열
+   - `datahub_airflow_plugin_lite.entities.Dataset`/`Urn`
+   - 공식 플러그인의 `datahub_airflow_plugin.entities` 객체도 `urn` 속성이 있어 그대로 인식합니다.
+2. Airflow 네이티브 Dataset(2.x)/Asset(3.x). URI 스킴으로 플랫폼을 판별합니다.
+3. **OpenLineage provider (기본 소스):** operator의 `get_openlineage_facets_on_complete/start()` 결과를 사용합니다. 몽키패치는 하지 않습니다.
+   - **정규화:** provider 버전마다 다른 결과를 DataHub ingestion URN으로 맞춥니다(`ol_normalize.py`).
+     - Athena: `AwsDataCatalog.` 접두어를 제거하고 소문자로 바꿉니다.
+     - S3: 버킷과 키를 합쳐 `make_s3_urn`과 같은 규칙을 적용합니다.
+     - Snowflake: 소문자로 바꿉니다.
+   - **버전 의존 값 제거:** 버전마다 다르게 나오는 Athena 쿼리 결과 위치는 제외합니다.
+   - **시간 제한:** OpenLineage 호출은 `openlineage_timeout_sec`(기본 5초)까지만 기다립니다.
+4. **내장 SQL 파서 (보완):** OpenLineage가 버전에 따라 놓친 테이블을 채웁니다. 예: provider 2.x의 CTE 입력 누락, amazon 8.x의 Athena 테이블 누락. 이 단계는 OpenLineage 결과를 지우지 않습니다.
+   - DB에 접속하지 않고 SQL 문과 Connection 정보(conn_type, 기본 DB/스키마)만 사용합니다.
+
+lineage 수집이 실패해서 결과가 불완전할 수 있으면 `dataJobInputOutput`을 보내지 않습니다. 이미 저장된 lineage를 덮어쓰지 않기 위해서입니다. 예: OpenLineage가 실패했고 SQL도 분석할 수 없는 경우.
+DataJob 정보와 실행 기록은 lineage보다 먼저 전송하므로, lineage 수집 결과와 관계없이 항상 기록됩니다.
+
+provider 1.7.0, 2.11.0, 2.20.2에서 같은 lineage가 저장되는지 비교한 결과는 [tests/compat/README.md](tests/compat/README.md)에 있습니다.
+
+## 공식 플러그인과의 차이
+
+URN 생성 규칙(DataFlow, DataJob, Dataset, DataProcessInstance)은 공식 플러그인과 같습니다. 따라서 공식 플러그인에서 전환해도 엔티티가 중복 생성되지 않습니다.
+`tests/unit/test_sdk_parity.py`가 이를 검증합니다.
+
+| 기능                                                            | 공식              | lite                                           |
+| --------------------------------------------------------------- | ----------------- | ---------------------------------------------- |
+| DataFlow/DataJob/실행 이력, 소유자, 태그                        | O                 | O                                              |
+| inlets/outlets, Airflow Dataset/Asset lineage                   | O                 | O                                              |
+| OpenLineage 기반 테이블 lineage                                 | O (SQL 파서 패치) | O (패치 없이 결과 정규화 + 내장 SQL 파서 보완) |
+| 컬럼 단위 lineage (DataHub SQL 파서)                            | O                 | X                                              |
+| Kafka/File emitter, 다중 커넥션                                 | O                 | X (REST만)                                     |
+| `Datahub_Cleanup` DAG, DatahubEmitterOperator, assertion sensor | O                 | X                                              |
+| Jinja 템플릿 렌더링 후 속성 수집                                | O                 | X (원본 값 사용)                               |
+
+## 개발
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+`test_sdk_parity.py`는 `acryl-datahub`가 설치된 경우에만 실행됩니다. `test_listener.py`는 설치된 Airflow의 실제 listener manager(pluggy)에 등록해 훅 시그니처 호환성을 검증합니다.

datahub_airflow_plugin_lite-0.1.1/README.md

@@ -0,0 +1,108 @@
+# datahub-airflow-plugin-lite
+
+Airflow 실행 메타데이터와 lineage를 DataHub로 보내는 **런타임 의존성 0개** 플러그인입니다.
+표준 라이브러리와 이미 설치된 Airflow만 사용하므로 MWAA 등 Airflow constraints 파일과 충돌하지 않습니다.
+
+| 항목        | 지원 범위             | 검증한 조합                                        |
+| ----------- | --------------------- | -------------------------------------------------- |
+| Python      | 3.9 이상              | 3.9.6, 3.12.13                                     |
+| Airflow     | 2.9.1 이상 (3.x 포함) | 2.9.1, 2.11.2, 3.1.0                               |
+| DataHub GMS | 1.4.0.3 이상          | URN/aspect를 acryl-datahub 1.4.0.3 SDK 출력과 대조 |
+
+## 설치
+
+```bash
+pip install datahub-airflow-plugin-lite-0.1.1-py3-none-any.whl
+```
+
+공식 플러그인(`acryl-datahub-airflow-plugin`)과 동시에 설치하지 마세요. 두 리스너가 같은 엔티티를 중복 전송합니다.
+
+## 설정
+
+`airflow.cfg`의 `[datahub]` 섹션(또는 `AIRFLOW__DATAHUB__*` 환경변수)을 읽습니다. 키 이름은 공식 플러그인과 같습니다.
+
+```ini
+[datahub]
+# GMS 주소/토큰을 직접 지정하거나, 생략하면 conn_id 커넥션(host=GMS URL, password=토큰)을 사용
+gms_url = https://datahub-gms.example.com
+token = <personal access token>
+conn_id = datahub_rest_default
+cluster = prod
+platform_instance =
+capture_ownership_info = true
+capture_ownership_as_group = false
+capture_tags_info = true
+capture_executions = true
+materialize_iolets = true
+capture_airflow_assets = true
+enable_datajob_lineage = true
+enable_openlineage_facets = true
+openlineage_timeout_sec = 5
+supplement_with_sql_parser = true
+athena_include_result_location = false
+dag_filter_str = {"allow": [".*"], "deny": []}
+timeout_sec = 10
+retries = 2
+ssl_verify = true
+```
+
+운영 스위치도 공식 플러그인과 같습니다.
+
+- `AIRFLOW_VAR_DATAHUB_AIRFLOW_PLUGIN_DISABLE_LISTENER=true`: 리스너 즉시 중지 (kill switch)
+- `DATAHUB_AIRFLOW_PLUGIN_RUN_IN_THREAD`, `DATAHUB_AIRFLOW_PLUGIN_RUN_IN_THREAD_TIMEOUT`: 백그라운드 스레드 실행 여부와 대기 시간
+
+## 동작
+
+| Airflow 이벤트   | 전송 내용                                                                                                                     |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| DAG run 시작     | DataFlow (`dataFlowInfo`, `status`, `browsePathsV2`, `ownership`, `globalTags`, `dataPlatformInstance`), 태스크·태그 `status` |
+| 태스크 시작      | DataJob (`dataJobInfo`, `status`, `ownership`, `globalTags`), 실행 기록 (`dataProcessInstance*`, STARTED)                     |
+| 태스크 성공/실패 | DataJob + `dataJobInputOutput`(lineage), 실행 결과(COMPLETE, SUCCESS/FAILURE), 실행 입출력, 데이터셋 `status`                 |
+
+전송은 GMS의 `POST /aspects?action=ingestProposal` 하나만 사용합니다.
+모든 처리는 데몬 스레드에서 실행되고, 예외는 로그로만 남기므로 태스크 실패로 이어지지 않습니다.
+
+### Lineage 소스
+
+1. `inlets`/`outlets`의 `Dataset`/`Urn` 객체 또는 `urn:li:...` 문자열
+   - `datahub_airflow_plugin_lite.entities.Dataset`/`Urn`
+   - 공식 플러그인의 `datahub_airflow_plugin.entities` 객체도 `urn` 속성이 있어 그대로 인식합니다.
+2. Airflow 네이티브 Dataset(2.x)/Asset(3.x). URI 스킴으로 플랫폼을 판별합니다.
+3. **OpenLineage provider (기본 소스):** operator의 `get_openlineage_facets_on_complete/start()` 결과를 사용합니다. 몽키패치는 하지 않습니다.
+   - **정규화:** provider 버전마다 다른 결과를 DataHub ingestion URN으로 맞춥니다(`ol_normalize.py`).
+     - Athena: `AwsDataCatalog.` 접두어를 제거하고 소문자로 바꿉니다.
+     - S3: 버킷과 키를 합쳐 `make_s3_urn`과 같은 규칙을 적용합니다.
+     - Snowflake: 소문자로 바꿉니다.
+   - **버전 의존 값 제거:** 버전마다 다르게 나오는 Athena 쿼리 결과 위치는 제외합니다.
+   - **시간 제한:** OpenLineage 호출은 `openlineage_timeout_sec`(기본 5초)까지만 기다립니다.
+4. **내장 SQL 파서 (보완):** OpenLineage가 버전에 따라 놓친 테이블을 채웁니다. 예: provider 2.x의 CTE 입력 누락, amazon 8.x의 Athena 테이블 누락. 이 단계는 OpenLineage 결과를 지우지 않습니다.
+   - DB에 접속하지 않고 SQL 문과 Connection 정보(conn_type, 기본 DB/스키마)만 사용합니다.
+
+lineage 수집이 실패해서 결과가 불완전할 수 있으면 `dataJobInputOutput`을 보내지 않습니다. 이미 저장된 lineage를 덮어쓰지 않기 위해서입니다. 예: OpenLineage가 실패했고 SQL도 분석할 수 없는 경우.
+DataJob 정보와 실행 기록은 lineage보다 먼저 전송하므로, lineage 수집 결과와 관계없이 항상 기록됩니다.
+
+provider 1.7.0, 2.11.0, 2.20.2에서 같은 lineage가 저장되는지 비교한 결과는 [tests/compat/README.md](tests/compat/README.md)에 있습니다.
+
+## 공식 플러그인과의 차이
+
+URN 생성 규칙(DataFlow, DataJob, Dataset, DataProcessInstance)은 공식 플러그인과 같습니다. 따라서 공식 플러그인에서 전환해도 엔티티가 중복 생성되지 않습니다.
+`tests/unit/test_sdk_parity.py`가 이를 검증합니다.
+
+| 기능                                                            | 공식              | lite                                           |
+| --------------------------------------------------------------- | ----------------- | ---------------------------------------------- |
+| DataFlow/DataJob/실행 이력, 소유자, 태그                        | O                 | O                                              |
+| inlets/outlets, Airflow Dataset/Asset lineage                   | O                 | O                                              |
+| OpenLineage 기반 테이블 lineage                                 | O (SQL 파서 패치) | O (패치 없이 결과 정규화 + 내장 SQL 파서 보완) |
+| 컬럼 단위 lineage (DataHub SQL 파서)                            | O                 | X                                              |
+| Kafka/File emitter, 다중 커넥션                                 | O                 | X (REST만)                                     |
+| `Datahub_Cleanup` DAG, DatahubEmitterOperator, assertion sensor | O                 | X                                              |
+| Jinja 템플릿 렌더링 후 속성 수집                                | O                 | X (원본 값 사용)                               |
+
+## 개발
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+`test_sdk_parity.py`는 `acryl-datahub`가 설치된 경우에만 실행됩니다. `test_listener.py`는 설치된 Airflow의 실제 listener manager(pluggy)에 등록해 훅 시그니처 호환성을 검증합니다.

datahub_airflow_plugin_lite-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datahub-airflow-plugin-lite"
+version = "0.1.1"
+description = "Dependency-free DataHub listener plugin for Apache Airflow"
+readme = "README.md"
+requires-python = ">=3.9"
+# Intentionally empty: the plugin only uses the Python standard library and the
+# Airflow installation it runs inside, so it never conflicts with Airflow/MWAA
+# constraint files. Supported runtime: Airflow >= 2.9.1, DataHub GMS >= 1.4.0.3.
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    # Used only by the parity tests to prove URNs/aspects match the official SDK.
+    "acryl-datahub[datahub-rest]",
+]
+
+[project.entry-points."airflow.plugins"]
+datahub_lite = "datahub_airflow_plugin_lite.plugin:DatahubLitePlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+datahub_airflow_plugin_lite = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"

datahub_airflow_plugin_lite-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

datahub_airflow_plugin_lite-0.1.1/src/datahub_airflow_plugin_lite/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

datahub_airflow_plugin_lite-0.1.1/src/datahub_airflow_plugin_lite/aspects.py

@@ -0,0 +1,223 @@
+"""Aspect payloads as plain JSON dicts.
+
+Only aspects/fields that exist in DataHub 1.4.0.3 and later are produced. The
+shapes match what acryl-datahub serializes (see tests/unit/test_sdk_parity.py),
+including union encodings such as `{"string": "COMMAND"}` and timeseries
+defaults such as `partitionSpec`.
+"""
+
+import json
+from dataclasses import dataclass
+from typing import Dict, List, Mapping, Optional, Sequence
+
+from datahub_airflow_plugin_lite.urns import (
+    entity_type_of,
+    make_data_platform_urn,
+    make_dataplatform_instance_urn,
+    make_group_urn,
+    make_user_urn,
+    ORCHESTRATOR,
+)
+
+JsonDict = Dict[str, object]
+
+# Values accepted by DataHub's FabricType enum; DataJobInfo/DataFlowInfo only set
+# `env` when the Airflow cluster name is one of them (same rule as the SDK).
+_FABRIC_TYPES = {
+    "DEV",
+    "TEST",
+    "QA",
+    "UAT",
+    "EI",
+    "PRE",
+    "STG",
+    "NON_PROD",
+    "PROD",
+    "CORP",
+    "RVW",
+    "PRD",
+    "TST",
+    "SIT",
+    "SBX",
+    "SANDBOX",
+}
+
+_FULL_TABLE_PARTITION: JsonDict = {
+    "partition": "FULL_TABLE_SNAPSHOT",
+    "type": "FULL_TABLE",
+}
+
+
+@dataclass(frozen=True)
+class MetadataChangeProposal:
+    entity_urn: str
+    aspect_name: str
+    aspect: JsonDict
+
+    def to_proposal(self) -> JsonDict:
+        return {
+            "entityType": entity_type_of(self.entity_urn),
+            "entityUrn": self.entity_urn,
+            "changeType": "UPSERT",
+            "aspectName": self.aspect_name,
+            "aspect": {
+                "value": json.dumps(self.aspect),
+                "contentType": "application/json",
+            },
+        }
+
+
+def _drop_none(values: Mapping[str, Optional[object]]) -> JsonDict:
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def env_for_cluster(cluster: str) -> Optional[str]:
+    return cluster.upper() if cluster.upper() in _FABRIC_TYPES else None
+
+
+def status(removed: bool = False) -> JsonDict:
+    return {"removed": removed}
+
+
+def data_platform_instance(instance: str) -> JsonDict:
+    return {
+        "platform": make_data_platform_urn(ORCHESTRATOR),
+        "instance": make_dataplatform_instance_urn(ORCHESTRATOR, instance),
+    }
+
+
+def ownership(owners: Sequence[str], as_group: bool) -> JsonDict:
+    make_owner_urn = make_group_urn if as_group else make_user_urn
+    owner_urns = sorted({make_owner_urn(owner) for owner in owners})
+    return {
+        "owners": [
+            {"owner": urn, "type": "DEVELOPER", "source": {"type": "SERVICE"}}
+            for urn in owner_urns
+        ],
+        "ownerTypes": {},
+        "lastModified": {"time": 0, "actor": make_user_urn(ORCHESTRATOR)},
+    }
+
+
+def global_tags(tag_urns: Sequence[str]) -> JsonDict:
+    return {"tags": [{"tag": urn} for urn in sorted(set(tag_urns))]}
+
+
+def browse_paths_v2(dag_id: str, platform_instance: Optional[str]) -> JsonDict:
+    path: List[JsonDict] = []
+    if platform_instance:
+        path.append(
+            {
+                "id": platform_instance,
+                "urn": make_dataplatform_instance_urn(ORCHESTRATOR, platform_instance),
+            }
+        )
+    path.append({"id": dag_id})
+    return {"path": path}
+
+
+def data_flow_info(
+    name: str,
+    description: Optional[str],
+    custom_properties: Mapping[str, str],
+    external_url: Optional[str],
+    env: Optional[str],
+) -> JsonDict:
+    return _drop_none(
+        {
+            "customProperties": dict(custom_properties),
+            "externalUrl": external_url,
+            "name": name,
+            "description": description,
+            "env": env,
+        }
+    )
+
+
+def data_job_info(
+    name: str,
+    description: Optional[str],
+    custom_properties: Mapping[str, str],
+    external_url: Optional[str],
+    env: Optional[str],
+) -> JsonDict:
+    return _drop_none(
+        {
+            "customProperties": dict(custom_properties),
+            "externalUrl": external_url,
+            "name": name,
+            "description": description,
+            # Union[AzkabanJobType, string]; the SDK serializes it as the string branch.
+            "type": {"string": "COMMAND"},
+            "env": env,
+        }
+    )
+
+
+def data_job_input_output(
+    input_datasets: Sequence[str],
+    output_datasets: Sequence[str],
+    input_datajobs: Sequence[str],
+) -> JsonDict:
+    return {
+        "inputDatasets": sorted(set(input_datasets)),
+        "outputDatasets": sorted(set(output_datasets)),
+        "inputDatajobs": sorted(set(input_datajobs)),
+    }
+
+
+def data_process_instance_properties(
+    name: str,
+    created_millis: int,
+    process_type: str,
+    custom_properties: Mapping[str, str],
+    external_url: Optional[str],
+) -> JsonDict:
+    return _drop_none(
+        {
+            "customProperties": dict(custom_properties),
+            "externalUrl": external_url,
+            "name": name,
+            "type": process_type,
+            "created": {"time": created_millis, "actor": "urn:li:corpuser:datahub"},
+        }
+    )
+
+
+def data_process_instance_relationships(parent_template: str) -> JsonDict:
+    return {"parentTemplate": parent_template, "upstreamInstances": []}
+
+
+def data_process_instance_run_started(timestamp_millis: int, attempt: int) -> JsonDict:
+    return {
+        "timestampMillis": timestamp_millis,
+        "partitionSpec": dict(_FULL_TABLE_PARTITION),
+        "status": "STARTED",
+        "attempt": attempt,
+    }
+
+
+def data_process_instance_run_completed(
+    timestamp_millis: int,
+    attempt: int,
+    result_type: str,
+    duration_millis: Optional[int],
+) -> JsonDict:
+    return _drop_none(
+        {
+            "timestampMillis": timestamp_millis,
+            "partitionSpec": dict(_FULL_TABLE_PARTITION),
+            "status": "COMPLETE",
+            "attempt": attempt,
+            "result": {"type": result_type, "nativeResultType": ORCHESTRATOR},
+            "durationMillis": duration_millis,
+        }
+    )
+
+
+def data_process_instance_input(inputs: Sequence[str]) -> JsonDict:
+    return {"inputs": sorted(set(inputs))}
+
+
+def data_process_instance_output(outputs: Sequence[str]) -> JsonDict:
+    return {"outputs": sorted(set(outputs))}

datahub_airflow_plugin_lite-0.1.1/src/datahub_airflow_plugin_lite/config.py

@@ -0,0 +1,151 @@
+"""Plugin configuration read from the `[datahub]` section of airflow.cfg.
+
+Key names match the official plugin so an existing airflow.cfg (or
+AIRFLOW__DATAHUB__* environment variables) keeps working unchanged.
+"""
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional, Tuple
+
+from datahub_airflow_plugin_lite.urns import DEFAULT_FLOW_CLUSTER
+
+ConfigGetter = Callable[[str], Optional[str]]
+
+_TRUE_VALUES = {"true", "1", "yes", "on"}
+_FALSE_VALUES = {"false", "0", "no", "off"}
+
+
+@dataclass(frozen=True)
+class DagFilter:
+    """Same semantics as datahub's AllowDenyPattern (ignore case, deny wins)."""
+
+    allow: Tuple[str, ...] = (".*",)
+    deny: Tuple[str, ...] = ()
+
+    def allowed(self, dag_id: str) -> bool:
+        if any(re.match(p, dag_id, re.IGNORECASE) for p in self.deny):
+            return False
+        return any(re.match(p, dag_id, re.IGNORECASE) for p in self.allow)
+
+
+@dataclass(frozen=True)
+class LiteConfig:
+    enabled: bool = True
+    # Connection: explicit gms_url/token win over the Airflow connection, which
+    # helps on Airflow 3 where some components cannot read connections.
+    conn_id: str = "datahub_rest_default"
+    gms_url: Optional[str] = None
+    token: Optional[str] = None
+    timeout_sec: float = 10.0
+    retries: int = 2
+    ssl_verify: bool = True
+
+    cluster: str = DEFAULT_FLOW_CLUSTER
+    platform_instance: Optional[str] = None
+    capture_ownership_info: bool = True
+    capture_ownership_as_group: bool = False
+    capture_tags_info: bool = True
+    capture_executions: bool = True
+    materialize_iolets: bool = True
+    capture_airflow_assets: bool = True
+    enable_datajob_lineage: bool = True
+    # Primary lineage source: operators' get_openlineage_facets_* methods
+    # (needs apache-airflow-providers-openlineage; skipped when not installed).
+    # Results are normalized to DataHub URNs so every provider version maps to
+    # the same datasets.
+    enable_openlineage_facets: bool = True
+    openlineage_timeout_sec: float = 5.0
+    # Add tables OpenLineage missed (version-specific gaps) using the built-in,
+    # connection-free SQL parser. Never removes OpenLineage results.
+    supplement_with_sql_parser: bool = True
+    # Athena query-result S3 location as an output dataset (version-dependent).
+    athena_include_result_location: bool = False
+    datajob_url_link: Optional[str] = None
+    dag_filter: DagFilter = field(default_factory=DagFilter)
+    log_level: Optional[str] = None
+
+
+def _parse_bool(raw: Optional[str], default: bool, key: str) -> bool:
+    if raw is None or raw.strip() == "":
+        return default
+    value = raw.strip().lower()
+    if value in _TRUE_VALUES:
+        return True
+    if value in _FALSE_VALUES:
+        return False
+    raise ValueError(f"[datahub] {key} must be a boolean, got {raw!r}")
+
+
+def _parse_dag_filter(raw: Optional[str]) -> DagFilter:
+    if not raw:
+        return DagFilter()
+    parsed = json.loads(raw)
+    if not isinstance(parsed, dict):
+        raise ValueError("[datahub] dag_filter_str must be a JSON object")
+    allow: List[str] = parsed.get("allow", [".*"])
+    deny: List[str] = parsed.get("deny", [])
+    return DagFilter(allow=tuple(allow), deny=tuple(deny))
+
+
+def load_config(get: ConfigGetter) -> LiteConfig:
+    defaults = LiteConfig()
+
+    def get_bool(key: str, default: bool) -> bool:
+        return _parse_bool(get(key), default, key)
+
+    def get_str(key: str, default: Optional[str]) -> Optional[str]:
+        raw = get(key)
+        return raw if raw not in (None, "") else default
+
+    return LiteConfig(
+        enabled=get_bool("enabled", defaults.enabled),
+        conn_id=get_str("conn_id", defaults.conn_id) or defaults.conn_id,
+        gms_url=get_str("gms_url", None),
+        token=get_str("token", None),
+        timeout_sec=float(get_str("timeout_sec", None) or defaults.timeout_sec),
+        retries=int(get_str("retries", None) or defaults.retries),
+        ssl_verify=get_bool("ssl_verify", defaults.ssl_verify),
+        cluster=get_str("cluster", defaults.cluster) or defaults.cluster,
+        platform_instance=get_str("platform_instance", None),
+        capture_ownership_info=get_bool(
+            "capture_ownership_info", defaults.capture_ownership_info
+        ),
+        capture_ownership_as_group=get_bool(
+            "capture_ownership_as_group", defaults.capture_ownership_as_group
+        ),
+        capture_tags_info=get_bool("capture_tags_info", defaults.capture_tags_info),
+        capture_executions=get_bool("capture_executions", defaults.capture_executions),
+        materialize_iolets=get_bool("materialize_iolets", defaults.materialize_iolets),
+        capture_airflow_assets=get_bool(
+            "capture_airflow_assets", defaults.capture_airflow_assets
+        ),
+        enable_datajob_lineage=get_bool(
+            "enable_datajob_lineage", defaults.enable_datajob_lineage
+        ),
+        enable_openlineage_facets=get_bool(
+            "enable_openlineage_facets", defaults.enable_openlineage_facets
+        ),
+        openlineage_timeout_sec=float(
+            get_str("openlineage_timeout_sec", None) or defaults.openlineage_timeout_sec
+        ),
+        supplement_with_sql_parser=get_bool(
+            "supplement_with_sql_parser", defaults.supplement_with_sql_parser
+        ),
+        athena_include_result_location=get_bool(
+            "athena_include_result_location", defaults.athena_include_result_location
+        ),
+        datajob_url_link=get_str("datajob_url_link", None),
+        dag_filter=_parse_dag_filter(get("dag_filter_str")),
+        log_level=get_str("log_level", None),
+    )
+
+
+def load_config_from_airflow() -> LiteConfig:
+    from airflow.configuration import conf
+
+    def get(key: str) -> Optional[str]:
+        return conf.get("datahub", key, fallback=None)
+
+    return load_config(get)