本文详解如何在 Python 中正确导入并调用定义在包的 __init__.py 文件中的函数，避免常见的 NameError 错误，并说明三种标准导入方式的适用场景与注意事项。
本文详解如何在 python 中正确导入并调用定义在包的 `__init__.py` 文件中的函数，避免常见的 `nameerror` 错误，并说明三种标准导入方式的适用场景与注意事项。
在 Python 包开发中，__init__.py 不仅用于标识目录为包，还可作为包的“入口接口”——集中定义公共函数、类或变量，并通过 __all__ 显式控制对外暴露的符号。但一个常见误区是：仅执行 import module1 并不等于将其中定义的函数自动注入当前命名空间。这正是问题中出现 NameError: name 'print_hello' is not defined 的根本原因。
✅ 正确做法：明确指定作用域
假设项目结构如下：
project/
├── main.py
└── module1/
└── __init__.py其中 module1/__init__.py 内容为：
def print_hello():
print('Hello')
__all__ = ["print_hello"]
print('Init loaded')此时在 main.py 中有三种合规且推荐的调用方式：
立即学习“Python免费学习笔记（深入）”；
1. 点号访问（推荐：显式、安全、可读性强）
import module1 module1.print_hello() # ✅ 正确：通过模块名限定作用域
✔️ 优点：避免命名冲突；清晰体现函数来源；符合 PEP 8 和大型项目工程规范。
❌ 注意：不可直接写 print_hello() —— 它不在全局命名空间中。
2. 显式导入指定名称（简洁且可控）
from module1 import print_hello print_hello() # ✅ 正确：已将函数名导入当前作用域
✔️ 优点：调用简洁；__all__ 可确保只导入预期符号（若未设 __all__，则导入所有公有名称）。
⚠️ 注意：若 module1 中存在同名变量（如 print_hello = "fallback"），会覆盖函数定义，引发静默错误。
3. 通配符导入（不推荐，仅限脚本调试）
from module1 import * print_hello() # ✅ 语法上可行，但……
❌ 强烈不建议在生产代码中使用：
- 破坏可读性（无法快速定位符号来源）；
- 可能意外覆盖已有变量；
- 绕过 __all__ 限制时行为不可控（如未定义 __all__，可能导入大量私有成员 _helper）；
- 静态分析工具（如 mypy、pylint）和 IDE 自动补全支持弱。
? 补充说明：__all__ 的作用与验证
__all__ 是一个字符串列表，*仅影响 `from module import 的行为**，对import module或from module import name` 无约束力。它本质是“包作者的接口声明”，用于明确向使用者传达“哪些是公开 API”。
你可以通过以下方式验证导出是否生效：
# 在 main.py 中 import module1 print(module1.__all__) # 输出: ['print_hello']
若忘记在 __init__.py 中定义 __all__，from module1 import * 将导入所有不以下划线开头的名称（包括意外暴露的辅助函数），增加维护风险。
✅ 最佳实践总结
| 场景 | 推荐方式 | 理由 |
|---|---|---|
| 生产代码、库开发、团队协作 | import module1; module1.func() | 命名空间隔离、可追溯、无副作用 |
| 单模块高频调用（如 CLI 工具主逻辑） | from module1 import func1, func2 | 平衡简洁性与可控性 |
| 交互式调试或临时脚本 | from module1 import *（慎用） | 快速验证，但务必及时重构 |
最后提醒：无论采用哪种方式，都需确保 module1/ 目录位于 Python 模块搜索路径（sys.path）中。若运行时报 ModuleNotFoundError，请检查当前工作目录或使用 PYTHONPATH 配置，而非依赖相对导入。
掌握这三种导入模式的本质区别，是写出健壮、可维护 Python 包的第一步。
