Python 包导入与 __init__.py 机制：从循环导入到相对路径

1.1 三种身份#

很多教程告诉你：__init__.py 用来”把目录标记为包”。这是事实，但严重低估了它的能力。实际上，__init__.py 在 Python 包的导入流程中扮演着三种截然不同的角色：

我们一个一个看。

1.2 包标记：namespace package 与普通包#

从 Python 3.3 开始，没有 __init__.py 的目录也可以作为包导入，这叫 namespace package：

1
# 没有 __init__.py 的目录
2
mypkg/
3
├── a.py
4
└── b.py

1
# 依然可以导入！
2
import mypkg.a
3
import mypkg.b

听起来很美好对吧？但 namespace package 有一个致命缺陷：无法执行初始化代码。比如你想在包导入时打印日志、注册插件、设置默认配置，namespace package 做不到。

更糟的是，命名冲突时不会报错。如果你的项目目录和某个第三方包同名，namespace package 会默默合并，可能导致诡异的 bug。

生产环境建议：永远保留 __init__.py。即使它是空的。

1.3 包初始化代码：被打包成 .whl 也照常执行#

当你写 import mypkg 时，Python 会执行 mypkg/__init__.py 里的所有顶层代码，且只执行一次：

1
print("🚀 mypkg 被导入了！")
2
__version__ = "1.0.0"
3

4
# 初始化包级状态
5
_DEFAULT_CONFIG = {"debug": False, "timeout": 30}
6

7
def get_config():
8
    return _DEFAULT_CONFIG.copy()

1
import mypkg  # 第一次导入：执行 __init__.py
2
import mypkg  # 第二次导入：什么都不做（命中 sys.modules 缓存）

输出：

1
🚀 mypkg 被导入了！

这就是为什么很多 SDK 的初始化代码（注册插件、设置日志、加载配置）都放在 __init__.py 里。这层执行是 import 系统保证的，无论你最终用 wheel、zipapp 还是源码分发。

1.4 包门面：控制 from package import *#

如果包里有几十个内部模块，你希望用户只看到 5 个公共 API，怎么做？用 __all__：

1
from .core import Engine, Request
2
from .utils import logger
3
from .errors import APIError
4

5
# 控制 from mypkg import * 的行为
6
__all__ = ["Engine", "Request", "APIError"]  # logger 不在公共 API 中
7

8
__version__ = "1.0.0"

不设置 __all__ 时，from package import * 默认会导入所有不以下划线开头的名字，但这种行为很容易污染命名空间。最佳实践：永远显式定义 __all__。

1.5 动手验证：观察 __init__.py 的执行时机#

写一个最小的实验，亲眼看一下 __init__.py 到底在什么时候被执行的：

1
import time
2
print(f"[{time.time():.3f}] demo_pkg.__init__ 被执行")
3

4
# demo_pkg/core.py
5
import time
6
print(f"[{time.time():.3f}] demo_pkg.core 被加载")
7

8
def hello():
9
    return "hello from core"

1
import time
2
print(f"[{time.time():.3f}] 程序启动")
3

4
import demo_pkg
5
print(f"[{time.time():.3f}] import demo_pkg 完成")
6

7
import demo_pkg.core  # 触发 core.py 加载
8
print(f"[{time.time():.3f}] import demo_pkg.core 完成")
9

10
demo_pkg.core.hello()

输出（时间戳可能不同，但顺序一致）：

1
[1234567890.001] 程序启动
2
[1234567890.002] demo_pkg.__init__ 被执行
3
[1234567890.003] import demo_pkg 完成
4
[1234567890.004] demo_pkg.core 被加载
5
[1234567890.005] import demo_pkg.core 完成

可以看到：__init__.py 在第一次导入包时执行，而子模块 core.py 是在你显式导入它的时候才加载。这印证了我们前面的说法——import demo_pkg 不会自动加载所有子模块。

3.1 修改 sys.path 的四种方式（按推荐度排序）#

1
# 方式 1：设置 PYTHONPATH 环境变量（推荐用于开发）
2
# export PYTHONPATH=/path/to/your/libs
3

4
# 方式 2：使用 .pth 文件（推荐用于部署）
5
# 在 site-packages 下创建 myproject.pth，内容为项目根路径
6

7
# 方式 3：运行时修改（不推荐，会污染全局）
8
import sys
9
sys.path.insert(0, "/path/to/libs")
10

11
# 方式 4：用相对路径的 importlib（推荐用于脚本）
12
from pathlib import Path
13
import sys
14
sys.path.insert(0, str(Path(__file__).parent.parent))

3.2 实战：在 scripts 目录中导入上级包#

最常见的 ModuleNotFoundError 场景：

1
myproject/
2
├── mypkg/
3
│   ├── __init__.py
4
│   └── core.py
5
└── scripts/
6
    └── run.py   # 想 import mypkg.core

直接 python scripts/run.py 会失败，因为 sys.path[0] 是 scripts/，找不到 mypkg。

解决方案：在 scripts/run.py 顶部加入：

1
import sys
2
from pathlib import Path
3
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

或者用 -m 模式运行：

1
# 从项目根目录执行
2
cd myproject
3
python -m scripts.run  # 这样 sys.path[0] 是 myproject/

python -m 是最规范的运行方式，建议所有项目都用这个。

3.3 sys.path 顺序的”踩坑现场”#

一个真实的生产环境 bug：项目用了 request 库做 HTTP 调用，但生产环境报 AttributeError: module 'requests' has no attribute 'Session'。最后发现是项目里有个文件叫 request.py（少了个 s），导致 Python 在 sys.path[0] 找到了这个文件，import 进去的是一个空模块。

1
# 项目里有这样一个文件
2
# project_root/utils/request.py  ❌ 千万别这么命名
3

4
# 任何地方写 import requests 时
5
import requests  # 优先找到 ./utils/request.py

避免这种坑的纪律：

1. 永远不要用标准库或第三方库的同名文件（json.py、os.py、request.py）
2. 永远不要给项目根目录起和某个包冲突的名字
3. 在 CI 中加一个 find . -name "*.py" | xargs grep 检查可疑命名

sys.path 这个”看似简单”的列表，是 Python 项目 80% import 问题的根源。遇到 ModuleNotFoundError 第一反应应该是：打印 sys.path 看实际路径。

4.1 方案一：延迟导入（最常用）#

把 import 放进函数/方法内部，运行时再解析：

1
def func_a():
2
    from b import func_b  # 延迟到调用时
3
    return func_b()
4

5
# b.py
6
def func_b():
7
    from a import func_a
8
    return func_a()

优点：简单直接。缺点：每次调用都要做一次 import 检查（有缓存所以很快，但代码不优雅）。

4.2 方案二：重构模块结构（最根本）#

循环导入本质上是设计问题。如果 a 和 b 互相依赖，往往意味着有第三个模块 c 应该被抽出来：

1
重构前：
2
a.py ⇄ b.py
3

4
重构后：
5
a.py ─→ c.py ←─ b.py

1
# c.py（被两个模块共享）
2
def shared_logic():
3
    pass
4

5
# a.py
6
from .c import shared_logic
7

8
# b.py
9
from .c import shared_logic

这是根治的方法。如果你的项目出现循环导入，先尝试重构。

4.3 方案三：TYPE_CHECKING 守卫（类型提示专用）#

如果循环导入只是为了类型提示，用 typing.TYPE_CHECKING：

1
from __future__ import annotations
2
from typing import TYPE_CHECKING
3

4
if TYPE_CHECKING:
5
    from b import B  # 只在类型检查器运行时导入
6

7
def create_b() -> "B":  # 用字符串注解，运行时不需要 B
8
    from b import B
9
    return B()

TYPE_CHECKING 在运行时永远是 False，所以这段代码不会触发真正的 import，但 mypy/pylance 仍然能识别 B 的类型。

4.4 方案四：import 而不是 from（最简但有限）#

1
import b  # 这样写不会在加载 a 时执行 b 的 import 语句
2

3
def func_a():
4
    return b.func_b()

注意：import b 不会触发 b.py 里的顶层代码触发循环，但仍然会加载 b。这个方案只能解决一类特定的循环，不是万能药。

4.5 实战：诊断循环导入#

当生产环境报 ImportError: cannot import name 'X' from partially initialized module 'Y' 时，按这个流程诊断：

1
# 步骤 1：先看堆栈
2
"""
3
Traceback (most recent call last):
4
  File "a.py", line 1, in <module>
5
    from b import func_b
6
  File "b.py", line 1, in <module>
7
    from a import func_a  # 💥 a 还没加载完
8
ImportError: cannot import name 'func_a' from partially initialized module 'a'
9
"""
10

11
# 步骤 2：画依赖图
12
# 用 Python 自带的 modulefinder
13
import modulefinder
14
finder = modulefinder.ModuleFinder()
15
finder.run_script("main.py")
16
finder.report()  # 打印所有模块依赖
17

18
# 步骤 3：定位循环点
19
# 在堆栈中找到两次出现的模块名，就是循环的"接缝"

诊断时一个常用技巧：把 from X import Y 改成 import X，然后在用的时候 X.Y。这样不会触发 X 的初始化，但代价是每次都要写完整路径。

5.1 Python 2 的悲剧：隐式相对导入#

在 Python 2 时代，没有显式相对导入，包内的 import 默认为是”相对的”：

1
# python 2 - 同一个包内
2
import sibling_module  # 隐式相对

这个设计的代价是：你写 import json 时，Python 会先在当前包里找 json.py——容易和标准库或第三方包冲突。

Python 3 修复了这个问题：默认是绝对导入。

5.2 显式相对导入：. 和 ..#

1
from . import sibling           # mypkg/subpkg/sibling.py
2
from .. import utils            # mypkg/utils.py
3
from ..core import Engine       # mypkg/core.py
4
from .sibling import helper    # 明确导入子模块的成员

. 表示当前包，.. 表示父包。和文件系统路径完全一致。

5.3 相对导入的”必须条件”#

相对导入只能在包内使用。在脚本模式下（python script.py），文件没有”包”的归属，. 无意义。

这就是为什么：

1
python mypkg/subpkg/module.py  # 💥 ImportError: attempted relative import with no known parent package
2

3
python -m mypkg.subpkg.module  # ✅ 正常

python -m 让 Python 把 mypkg.subpkg.module 当作包内模块执行，. 才有意义。

5.4 选绝对导入还是相对导入？#

社区共识是：生产代码用绝对导入，测试和内部模块可以用相对导入。

1
# ✅ 推荐：绝对导入（更清晰，IDE 跳转更准）
2
from myproject.core.processor import Engine
3

4
# ✅ 适用于：包内部紧密耦合的模块
5
from .processor import Engine
6
from ..utils import logger
7

8
# ❌ 避免：跨多级相对导入
9
from ...legacy.deprecated import OldThing  # 太深，重构时易碎

绝对导入的优势是明确的”完全限定名”，一眼能看出模块来自哪个包。相对导入在包内重构（移动包路径）时不会失效，但深度不要超过两级。

6.1 src layout vs flat layout#

两种主流布局：

1
# Flat layout（老派）
2
myproject/
3
├── mypkg/
4
│   └── __init__.py
5
└── tests/
6

7
# Src layout（现代推荐）
8
myproject/
9
├── src/
10
│   └── mypkg/
11
│       └── __init__.py
12
└── tests/

强烈推荐 src layout。原因：在 flat layout 下，pytest 可能会优先导入当前目录的 mypkg/ 而不是安装的版本，导致”测试通过但打包后报错”。src layout 强制使用安装版本，避免这类坑。

6.2 init.py 的内容守则#

1
# ❌ 反模式：在 __init__.py 里做重活
2
import requests  # 顶层 import 整个第三方库
3
DATABASE = connect_to_db()  # 顶层副作用
4
for f in glob("*.json"):
5
    load_config(f)  # 顶层 I/O
6

7
# ✅ 正解：保持轻量
8
from .core import main_api  # 只暴露门面
9
__version__ = "1.0.0"
10
__all__ = ["main_api"]

为什么？ __init__.py 的执行时机很早，做重活会拖慢所有 import 链，还会让包难以测试。

6.3 一个完整的生产级包结构#

1
mycorp-data-utils/
2
├── pyproject.toml
3
├── src/
4
│   └── mycorp_data_utils/
5
│       ├── __init__.py        # 暴露门面 API
6
│       ├── _version.py        # 版本号（独立文件）
7
│       ├── core/
8
│       │   ├── __init__.py
9
│       │   └── processor.py
10
│       ├── utils/
11
│       │   ├── __init__.py
12
│       │   └── helpers.py
13
│       └── errors.py
14
├── tests/
15
│   ├── unit/
16
│   └── integration/
17
└── scripts/
18
    └── benchmark.py

__init__.py 应该是这样的：

1
"""mycorp-data-utils: 数据处理工具集"""
2
from .core.processor import DataProcessor, BatchProcessor
3
from .errors import ValidationError, ProcessingError
4
from ._version import __version__
5

6
__all__ = [
7
    "DataProcessor",
8
    "BatchProcessor",
9
    "ValidationError",
10
    "ProcessingError",
11
    "__version__",
12
]