Apache Airflow 3.x 升级须知TaskInstance 移除 run、render_templates 等方法的完整解读【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文围绕 Airflow 变更公告59835.significant.rst展开说明在 Airflow 3.x 中TaskInstance类被移除的run()、render_templates()、get_template_context()等方法结合仓库源码与清理提交梳理这些方法原先的职责、执行路径的迁移去向以及用户代码升级时应采用的替代方案。读完本文你可以确认自己的 DAG 代码、Provider 扩展或测试脚本是否受影响并找到对应的替代调用方式。背景TaskInstance 从 3.0 起定位为内部类变更公告原文airflow-core/newsfragments/59835.significant.rst只有短短几行但给出的信息非常明确On classTaskInstance, functionsrun(),render_templates(),get_template_context(), and private members related to them have been removed. The class has been considered internal since 3.0, and should not be relied on in user code.要点有三受影响对象核心元数据模型TaskInstance源码位于 airflow-core/src/airflow/models/taskinstance.py当前版本约 2600 行是一个典型的 SQLAlchemy ORM 模型负责持久化任务实例的状态、心跳、依赖检查等移除内容三个公开方法run()、render_templates()、get_template_context()以及与它们配套的私有成员前提约束TaskInstance自 3.0 起即被视为内部internal类用户代码本不应依赖它。这次清理正是该定位的落地。之所以敢删除是因为 Airflow 3.0 引入了 Task SDK / Execution API 架构后任务的实际执行与模板渲染路径已经从TaskInstance模型迁出这些方法退化为只被内部测试使用的“死路径”。被移除的方法逐一解析通过仓库中对应的清理提交commit960973bfd8标题即 TaskInstance unused method cleanup (#59835)可以还原被删除代码的完整形态。1. run()仅保留给测试的旧执行入口被删除的run()方法签名及职责如下依据提交中的 diff 还原provide_session def run( self, verbose: bool True, ignore_all_deps: bool False, ignore_depends_on_past: bool False, wait_for_past_depends_before_skipping: bool False, ignore_task_deps: bool False, ignore_ti_state: bool False, mark_success: bool False, test_mode: bool False, pool: str | None None, session: Session NEW_SESSION, raise_on_defer: bool False, ) - None: Run TaskInstance (only kept for tests).从源码结构看该方法有三个值得注意的特征文档字符串直接注明only kept for tests且提交信息中写明Replace ti.run() with test util说明它的唯一消费者就是内部的ti.run、dag.test与task.test等测试辅助路径方法内部会先把原始 Operator 走一遍序列化/反序列化DagSerialization.to_dict/from_dict再调用check_and_change_state_before_execution做依赖与状态检查——这正是旧版2.x 时代ti.run的执行协议残留检查通过后会转入私有方法_run_raw_task后者直接调用airflow.sdk.definitions.dag._run_task并带有一段TODO (TaskSDK)注释This is the old ti execution path… likely by rewriting TI.run(...) to use the same mechanism as Operator.test()。这段注释本身就指明了迁移方向与Operator.test()采用同一套执行机制。2. _run_raw_task()被删除的私有成员与run()配套的私有方法_run_raw_task(mark_success, session, **kwargs)一并被删除。它的逻辑很简单# 被删除的代码还原自提交 diff provide_session def _run_raw_task(self, mark_success: bool False, sessionNEW_SESSION, **kwargs) - None: Only kept for tests. from airflow.sdk.definitions.dag import _run_task if mark_success: self.set_state(TaskInstanceState.SUCCESS) log.info([DAG TEST] Marking success for %s , self.task_id) return None taskrun_result _run_task(tiself, taskself.task) if taskrun_result is None: return None if taskrun_result.error: raise taskrun_result.error self.task taskrun_result.ti.task这正是公告中提到的private members related to them。注意它委托给_run_task而该函数在当前代码库中依然存在位置是 task-sdk/src/airflow/sdk/definitions/dag.py#L1491——也就是说真正的任务执行逻辑并未消失只是不再挂靠在TaskInstance模型上。3. render_templates()被标记为待删的死代码被删除的render_templates()带有明确的待删标记# 被删除的代码还原自提交 diff # TODO (GH-52141): We should remove this entire function (only makes sense at runtime). # This is intentionally left untyped so Mypy complains less about this dead code. def render_templates(self, contextNone, jinja_envNone): Render templates in the operator fields. If the task was originally mapped, this may replace self.task with the unmapped, fully rendered BaseOperator. ... from airflow.sdk.definitions.mappedoperator import MappedOperator if not context: context self.get_template_context() original_task self.task original_task.render_template_fields(context, jinja_env) if isinstance(self.task, MappedOperator): self.task context[ti].task return original_task从这段代码可以确认它的历史职责对 Operator 字段执行 Jinja 渲染并在任务来自expand()MappedOperator时把self.task替换为未映射、已渲染的BaseOperator。注释说得很直白——它only makes sense at runtime即只在旧版 worker 运行时才有意义而 Airflow 3.x 的运行时渲染已经发生在 Task SDK 一侧。这次清理还顺带触及了 Provider提交说明 Remove ti.render_templates() and clean up providers如果你的 Provider 代码曾调用ti.render_templates()属于受影响的场景。4. get_template_context()模板上下文的构建公告列出的第三个方法是get_template_context()。它与render_templates()是强耦合的后者在contextNone时即调用前者来构建包含ti、ds、conf等键的 Jinja 上下文。在当前代码库中taskinstance.py内已无此方法的定义模板渲染相关的模型能力由独立的 airflow-core/src/airflow/models/renderedtifields.py 承担其中的RenderedTaskInstanceFields类负责持久化/读取已渲染字段taskinstance.py中仍有RenderedTaskInstanceFields(tiself, render_templatesFalse, rendered_fieldsrendered_fields)这样的构造调用。可以推断面向用户的查看渲染结果能力没有被移除只是不再要求用户直接调TaskInstance实例上的方法而是通过 UI 与 REST API 访问已渲染字段。清理提交的实际改动范围commit960973bfd8#59835除删除taskinstance.py中约 100 行方法代码外还同步完成了配套重构其改动文件清单本身就是一份谁在依赖这些方法的清单测试侧全面替换airflow-core/tests/unit/models/test_taskinstance.py改动约 380 行大幅缩减test_renderedtifields.py、test_cleartasks.py、test_dagrun.py、test_trigger.py、test_xcom.py、test_scheduler_job.py等数十个测试文件同步调整——原依赖ti.run()的测试统一改写为走测试工具函数或 SDK 执行路径API 路由测试适配core_api/routes/public/test_task_instances.py与test_xcom.py调整确认 public API 不再经由被删方法取数renderedtifields.py微调配合渲染入口的收敛。这些改动共同验证了一个事实被删的三个方法在主干代码里已经没有任何生产调用链删除后仅影响直接调用它们的第三方/用户代码。升级影响与替代方案你的代码可能受影响的三种场景自定义 Operator / Provider 中调用了ti.render_templates()或ti.get_template_context()在 Airflow 3.x 下会直接AttributeError。模板渲染应由框架在运行时自动完成自定义 Operator 只需实现render_template_fields相关钩子即可测试脚本或 CLI 辅助逻辑里调用了ti.run(...)请改用 SDK 提供的本地执行入口。当前代码库中真正的任务执行入口是 task-sdk/src/airflow/sdk/definitions/dag.py 中的_run_task供框架内部调用而面向用户的本地快速执行推荐Operator.test()与dag.test()这类 API它们与旧ti.run()的目的在本地把任务跑一遍一致但走的是 3.x 的 Task SDK 执行机制直接 import 并依赖TaskInstance其他内部细节既然该类自 3.0 起即定位为 internal建议把读取任务状态的逻辑迁移到 REST API 或airflow.sdk公共接口。迁移检查清单全局搜索代码库中的ti.run(、render_templates(、get_template_context(确认无残留调用Provider 扩展代码按上述 Provider 清理的范围自查必要时参考仓库中providers/目录下同版本 Provider 的实现方式测试代码中原来通过TaskInstance.run驱动的场景改写为仓库测试套件采用的模式可参考 airflow-core/tests/unit/models/test_taskinstance.py 重构后的写法。小结59835这条 significant 公告虽然简短但它标记的是 Airflow 3.x API 收敛的一个明确信号TaskInstance彻底回归内部 ORM 模型角色任务执行、模板渲染等运行时职责已迁移到 Task SDKtask-sdk/与独立模型如RenderedTaskInstanceFields。对升级者而言只要不直接调用被删的三个方法这条变更是无感的若有调用则应按上述替代路径完成迁移。相关实现可继续在 airflow-core/src/airflow/models/taskinstance.py、task-sdk/src/airflow/sdk/definitions/dag.py 与 airflow-core/src/airflow/models/renderedtifields.py 中深入查看。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache Airflow 3.x 升级须知：TaskInstance 移除 run、render_templates 等方法的完整解读
Apache Airflow 3.x 升级须知TaskInstance 移除 run、render_templates 等方法的完整解读【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow本文围绕 Airflow 变更公告59835.significant.rst展开说明在 Airflow 3.x 中TaskInstance类被移除的run()、render_templates()、get_template_context()等方法结合仓库源码与清理提交梳理这些方法原先的职责、执行路径的迁移去向以及用户代码升级时应采用的替代方案。读完本文你可以确认自己的 DAG 代码、Provider 扩展或测试脚本是否受影响并找到对应的替代调用方式。背景TaskInstance 从 3.0 起定位为内部类变更公告原文airflow-core/newsfragments/59835.significant.rst只有短短几行但给出的信息非常明确On classTaskInstance, functionsrun(),render_templates(),get_template_context(), and private members related to them have been removed. The class has been considered internal since 3.0, and should not be relied on in user code.要点有三受影响对象核心元数据模型TaskInstance源码位于 airflow-core/src/airflow/models/taskinstance.py当前版本约 2600 行是一个典型的 SQLAlchemy ORM 模型负责持久化任务实例的状态、心跳、依赖检查等移除内容三个公开方法run()、render_templates()、get_template_context()以及与它们配套的私有成员前提约束TaskInstance自 3.0 起即被视为内部internal类用户代码本不应依赖它。这次清理正是该定位的落地。之所以敢删除是因为 Airflow 3.0 引入了 Task SDK / Execution API 架构后任务的实际执行与模板渲染路径已经从TaskInstance模型迁出这些方法退化为只被内部测试使用的“死路径”。被移除的方法逐一解析通过仓库中对应的清理提交commit960973bfd8标题即 TaskInstance unused method cleanup (#59835)可以还原被删除代码的完整形态。1. run()仅保留给测试的旧执行入口被删除的run()方法签名及职责如下依据提交中的 diff 还原provide_session def run( self, verbose: bool True, ignore_all_deps: bool False, ignore_depends_on_past: bool False, wait_for_past_depends_before_skipping: bool False, ignore_task_deps: bool False, ignore_ti_state: bool False, mark_success: bool False, test_mode: bool False, pool: str | None None, session: Session NEW_SESSION, raise_on_defer: bool False, ) - None: Run TaskInstance (only kept for tests).从源码结构看该方法有三个值得注意的特征文档字符串直接注明only kept for tests且提交信息中写明Replace ti.run() with test util说明它的唯一消费者就是内部的ti.run、dag.test与task.test等测试辅助路径方法内部会先把原始 Operator 走一遍序列化/反序列化DagSerialization.to_dict/from_dict再调用check_and_change_state_before_execution做依赖与状态检查——这正是旧版2.x 时代ti.run的执行协议残留检查通过后会转入私有方法_run_raw_task后者直接调用airflow.sdk.definitions.dag._run_task并带有一段TODO (TaskSDK)注释This is the old ti execution path… likely by rewriting TI.run(...) to use the same mechanism as Operator.test()。这段注释本身就指明了迁移方向与Operator.test()采用同一套执行机制。2. _run_raw_task()被删除的私有成员与run()配套的私有方法_run_raw_task(mark_success, session, **kwargs)一并被删除。它的逻辑很简单# 被删除的代码还原自提交 diff provide_session def _run_raw_task(self, mark_success: bool False, sessionNEW_SESSION, **kwargs) - None: Only kept for tests. from airflow.sdk.definitions.dag import _run_task if mark_success: self.set_state(TaskInstanceState.SUCCESS) log.info([DAG TEST] Marking success for %s , self.task_id) return None taskrun_result _run_task(tiself, taskself.task) if taskrun_result is None: return None if taskrun_result.error: raise taskrun_result.error self.task taskrun_result.ti.task这正是公告中提到的private members related to them。注意它委托给_run_task而该函数在当前代码库中依然存在位置是 task-sdk/src/airflow/sdk/definitions/dag.py#L1491——也就是说真正的任务执行逻辑并未消失只是不再挂靠在TaskInstance模型上。3. render_templates()被标记为待删的死代码被删除的render_templates()带有明确的待删标记# 被删除的代码还原自提交 diff # TODO (GH-52141): We should remove this entire function (only makes sense at runtime). # This is intentionally left untyped so Mypy complains less about this dead code. def render_templates(self, contextNone, jinja_envNone): Render templates in the operator fields. If the task was originally mapped, this may replace self.task with the unmapped, fully rendered BaseOperator. ... from airflow.sdk.definitions.mappedoperator import MappedOperator if not context: context self.get_template_context() original_task self.task original_task.render_template_fields(context, jinja_env) if isinstance(self.task, MappedOperator): self.task context[ti].task return original_task从这段代码可以确认它的历史职责对 Operator 字段执行 Jinja 渲染并在任务来自expand()MappedOperator时把self.task替换为未映射、已渲染的BaseOperator。注释说得很直白——它only makes sense at runtime即只在旧版 worker 运行时才有意义而 Airflow 3.x 的运行时渲染已经发生在 Task SDK 一侧。这次清理还顺带触及了 Provider提交说明 Remove ti.render_templates() and clean up providers如果你的 Provider 代码曾调用ti.render_templates()属于受影响的场景。4. get_template_context()模板上下文的构建公告列出的第三个方法是get_template_context()。它与render_templates()是强耦合的后者在contextNone时即调用前者来构建包含ti、ds、conf等键的 Jinja 上下文。在当前代码库中taskinstance.py内已无此方法的定义模板渲染相关的模型能力由独立的 airflow-core/src/airflow/models/renderedtifields.py 承担其中的RenderedTaskInstanceFields类负责持久化/读取已渲染字段taskinstance.py中仍有RenderedTaskInstanceFields(tiself, render_templatesFalse, rendered_fieldsrendered_fields)这样的构造调用。可以推断面向用户的查看渲染结果能力没有被移除只是不再要求用户直接调TaskInstance实例上的方法而是通过 UI 与 REST API 访问已渲染字段。清理提交的实际改动范围commit960973bfd8#59835除删除taskinstance.py中约 100 行方法代码外还同步完成了配套重构其改动文件清单本身就是一份谁在依赖这些方法的清单测试侧全面替换airflow-core/tests/unit/models/test_taskinstance.py改动约 380 行大幅缩减test_renderedtifields.py、test_cleartasks.py、test_dagrun.py、test_trigger.py、test_xcom.py、test_scheduler_job.py等数十个测试文件同步调整——原依赖ti.run()的测试统一改写为走测试工具函数或 SDK 执行路径API 路由测试适配core_api/routes/public/test_task_instances.py与test_xcom.py调整确认 public API 不再经由被删方法取数renderedtifields.py微调配合渲染入口的收敛。这些改动共同验证了一个事实被删的三个方法在主干代码里已经没有任何生产调用链删除后仅影响直接调用它们的第三方/用户代码。升级影响与替代方案你的代码可能受影响的三种场景自定义 Operator / Provider 中调用了ti.render_templates()或ti.get_template_context()在 Airflow 3.x 下会直接AttributeError。模板渲染应由框架在运行时自动完成自定义 Operator 只需实现render_template_fields相关钩子即可测试脚本或 CLI 辅助逻辑里调用了ti.run(...)请改用 SDK 提供的本地执行入口。当前代码库中真正的任务执行入口是 task-sdk/src/airflow/sdk/definitions/dag.py 中的_run_task供框架内部调用而面向用户的本地快速执行推荐Operator.test()与dag.test()这类 API它们与旧ti.run()的目的在本地把任务跑一遍一致但走的是 3.x 的 Task SDK 执行机制直接 import 并依赖TaskInstance其他内部细节既然该类自 3.0 起即定位为 internal建议把读取任务状态的逻辑迁移到 REST API 或airflow.sdk公共接口。迁移检查清单全局搜索代码库中的ti.run(、render_templates(、get_template_context(确认无残留调用Provider 扩展代码按上述 Provider 清理的范围自查必要时参考仓库中providers/目录下同版本 Provider 的实现方式测试代码中原来通过TaskInstance.run驱动的场景改写为仓库测试套件采用的模式可参考 airflow-core/tests/unit/models/test_taskinstance.py 重构后的写法。小结59835这条 significant 公告虽然简短但它标记的是 Airflow 3.x API 收敛的一个明确信号TaskInstance彻底回归内部 ORM 模型角色任务执行、模板渲染等运行时职责已迁移到 Task SDKtask-sdk/与独立模型如RenderedTaskInstanceFields。对升级者而言只要不直接调用被删的三个方法这条变更是无感的若有调用则应按上述替代路径完成迁移。相关实现可继续在 airflow-core/src/airflow/models/taskinstance.py、task-sdk/src/airflow/sdk/definitions/dag.py 与 airflow-core/src/airflow/models/renderedtifields.py 中深入查看。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考