Python绝对导入和相对导入的区别和用法详解

# 假设包结构：
# mypackage/
# ├── __init__.py
# ├── core.py
# ├── utils.py
# └── sub/
#     ├── __init__.py
#     └── helper.py

# ===== mypackage/sub/helper.py =====

# 绝对导入——从项目根开始的完整路径
from mypackage.core import some_function  # 绝对路径
from mypackage.utils import format_data   # 绝对路径

# 相对导入——使用.和..的相对路径
from ..core import some_function    # .. 表示上一级（mypackage）
from ..utils import format_data     # .. 表示上一级（mypackage）
from . import __init__ as sub_init  # . 表示当前包（sub）

# 相对导入的语法：
# from . import module        —— 从当前包导入module
# from .module import name    —— 从当前包的module中导入name
# from .. import module       —— 从上级包导入module
# from ..subpkg import module —— 从上级包的subpkg中导入module
# from ... import module      —— 从上上级包导入（很少用）

# 相对导入使用示例：

# 在 mypackage/sub/helper.py 中：
# .         → mypackage/sub/       (当前目录)
# ..        → mypackage/            (上级目录)
# ...       → 项目根目录             (上上级)
# .module   → mypackage/sub/module  (同目录下的模块)

# 具体使用：
# from . import sibling_module     # 同目录的兄弟模块
# from .. import core              # 上级目录的core模块
# from ..utils import format_data  # 上级目录utils模块中的format_data

# ⚠️ 相对导入只能在包内部使用！
# 不能直接在顶层脚本中使用相对导入

# ===== main.py (顶层脚本) =====
# from . import something  # ❌ 错误！
# ImportError: attempted relative import with no known parent package
# 顶层脚本不是包的一部分，没有"上级包"的概念

# ===== mypackage/module_a.py =====
# from .. import something  # ✅ 正确——module_a在包内部

# ⚠️ 另一个常见错误：
# python mypackage/module_a.py  # 直接运行包内的模块
# 这会把module_a当作顶层脚本——相对导入失败！
# 正确方式：python -m mypackage.module_a

# 绝对导入——从项目的"根"开始的完整路径

# 假设项目结构：
# myproject/
# ├── mypackage/
# │   ├── __init__.py
# │   ├── core.py
# │   └── utils.py
# └── main.py

# 在mypackage/core.py中：
# 绝对导入——完整的"地址"
from mypackage.utils import helper_function
import mypackage.utils

# 在main.py中：
from mypackage.core import CoreClass
import mypackage

# ✅ 绝对导入的优点：
# 1. 清晰——一眼看出导入的是什么
# 2. 可移植——把代码移到别处，导入路径不变
# 3. 可读——新人看代码容易理解
# 4. 安全——不容易因为文件移动而出错

# ❌ 绝对导入的缺点：
# 1. 路径可能很长（深层嵌套时）
# 2. 改包名时需要更新所有导入
# 3. 重命名顶层包名很痛苦

# 同一个导入，两种写法：

# 在 mypackage/sub/deep/nested/module.py 中
# 需要导入 mypackage/utils.py 中的函数

# 绝对导入：
from mypackage.utils import format_data
# 很长，但意图明确

# 相对导入：
from ...utils import format_data
# 简短的...但你需要数一下有几层

# 💡 直观对比：

# 绝对导入：写全了"地址"
# from myproject.users.models import User
# from myproject.users.services import UserService

# 相对导入：用"方位"描述
# from .models import User
# from ..services import UserService

# ✅ 使用绝对导入的场景：

# 1. 外部/公共API的导入
from mypackage import UserService  # 清晰明了

# 2. 跨大层级导入（避免写很多...）
from myproject.config import settings  # 比 ../../../config 好

# 3. 顶层脚本和测试文件
# tests/test_user.py:
from mypackage.services.user_service import UserService

# 4. 开源项目——绝对导入对用户更友好
# 用户更容易理解导入路径

# ✅ 使用相对导入的场景：

# 1. 包内部紧密关联的模块
# mypackage/models/user.py 导入 mypackage/models/base.py:
from .base import BaseModel  # 简短自然

# 2. 大型包内部——重构友好
# 移动整个子包时，内部相对导入不需要修改
# mypackage/sub/ 从 mypackage/ 移到 mypackage/core/
# 包内部的 . 和 .. 导入不受影响

# 3. __init__.py中的重新导出
# mypackage/__init__.py:
from .subpkg.module import Class  # 简洁

# 💡 团队建议：
# 大多数项目：优先使用绝对导入
# 大型包内部紧密关联时：使用相对导入
# 绝对不要混用——一个项目中保持一致！

# 问题一："Attempted relative import in non-package"
# 原因：在顶层脚本中使用了相对导入
# 解决：改用绝对导入，或用 python -m 运行模块

# 问题二："No module named 'xxx'"
# 原因：绝对导入时包名不对、或包不在sys.path中
# 解决：检查包名、检查目录结构

# 问题三：移动文件后导入全部失效
# 原因：使用了绝对导入，包名或路径变了
# 解决：如果是包内部移动，相对导入更健壮

# 问题四：循环导入
# 原因：两个模块互相导入对方
# 解决：重构代码、延迟导入（在函数内部import）