Airflow1.10.12环境下ClickHouseHook不同导入方式报错差异问题排查

异常场景复现 #

• 运行环境：Airflow 1.10.12
• 两种导入语法的表现差异：
  • 可正常无报错执行的导入写法：from airflow.hooks.clickhouse_hook import ClickHouseHook
  • 抛出ModuleNotFoundError: No module named 'airflow.hooks.clickhouse_hook'的导入写法：import airflow.hooks.clickhouse_hook
• 核对前提：手动检查airflow.hooks目录下，确实不存在名为clickhouse_hook.py的实体模块文件

核心成因：Python两种导入语法的执行逻辑本质差异 #

很多人会误以为两种导入语法检索的是同一样东西，但实际上二者的检查路径完全不同：

import 模块路径 语法的执行规则
严格按照路径层级，逐级在文件系统中检索对应的实体模块文件（即.py文件、或是带__init__.py的子目录），只有当所有层级都能定位到真实存在的模块实体时，才会完成导入。只要任意一层找不到对应实体，直接抛出模块不存在错误，全程不会读取当前包命名空间下的同名属性。
from 模块路径 import 目标对象 语法的执行规则
按层级加载路径上的每一级包，依次执行各包下的__init__.py初始化逻辑，在加载完倒数第二级包的命名空间后，会先检查命名空间中是否已经存在和路径最后一段同名的对象：如果存在，直接把这个对象作为导入目标返回，不会强制要求最后一段是文件系统中真实存在的模块实体。
举个最简单的本地测试用例就能复现这个差异：

1. 创建一个空的mypkg包，在mypkg/__init__.py中定义一个测试类，再把这个类的实例挂载到包的命名空间下，命名为submodule
2. 执行from mypkg.submodule import SomeClass可以正常导入，全程不报错
3. 执行import mypkg.submodule会直接抛出ModuleNotFoundError，因为文件系统中根本不存在submodule.py的实体文件

结合Airflow运行逻辑的具体触发过程 #

上述机制在Airflow 1.10.12环境下的具体触发链路：

• Airflow 1.10版本的airflow.hooks包初始化逻辑中，会在加载__init__.py的时候，动态扫描所有已安装的第三方Hook扩展（比如ClickHouse相关的插件包、老版本contrib模块），把对应的Hook类直接挂载到airflow.hooks的顶层命名空间中。
• 对于安装了ClickHouse扩展的环境，在airflow.hooks的命名空间里，已经存在名为clickhouse_hook的类对象——这个对象是类本身，不是可被文件系统检索到的模块文件。
• 当执行from airflow.hooks.clickhouse_hook import ClickHouseHook时，Python加载完airflow包、再加载airflow.hooks包之后，在airflow.hooks的命名空间里直接匹配到了名为clickhouse_hook的对象，根本不会继续去文件系统找有没有对应的py文件，自然可以正常完成导入。
• 当执行import airflow.hooks.clickhouse_hook时，Python加载完airflow、airflow.hooks两级真实包后，必须去文件系统的hooks目录下定位clickhouse_hook对应的实体模块，找不到匹配的文件就直接抛出模块不存在的错误。

快速验证方法 #

在对应环境的Python交互终端中执行如下命令，可直接看到问题根源：

import airflow.hooks
# 查看命名空间中clickhouse_hook对应的对象类型
print(type(airflow.hooks.__dict__.get('clickhouse_hook')))

输出结果不会是<class 'module'>，而是对应的Hook类本身，这就是两种导入行为出现差异的直接证据。

内容的提问来源于stack exchange，提问作者Vlad Aleshin