__all__ 必须是字符串列表，显式列出 __init__.py 中已定义的名称（如 from .submodule import X 或 X = submodule.X），才能控制 from xxx import * 的导入行为；未定义 __all__ 时，默认导入所有不以下划线开头的名称。
__init__.py 里直接 import 并赋值给 __all__ 才能控制 from xxx import * 的行为
很多人误以为只要在 __init__.py 中写 import module，外部就能直接用 from package import module —— 实际上这只能让模块被加载，但不会自动导出名字。真正决定“哪些名能被 from package import * 拿到”的是 __all__ 列表。
常见错误现象：from mypkg import * 后发现啥都没导入，或者意外导入了你不希望暴露的内部工具函数。
-
__all__必须是字符串列表，比如__all__ = ["Client", "connect", "DEFAULT_TIMEOUT"] - 列表里的每个字符串，必须对应
__init__.py中已存在的变量名（通常是通过from .submodule import X或X = submodule.X绑定的） - 如果没定义
__all__，from xxx import *会默认导入所有不以下划线开头的名称——这往往包含你不打算公开的辅助函数或测试类
用 from .module import name 而不是 import module 简化对外接口
假设包结构是 mypkg/ 下有 __init__.py、client.py、utils.py，你想让用户只写 from mypkg import Client，而不是 from mypkg.client import Client。
这时候在 __init__.py 中写 from .client import Client，比写 import mypkg.client 更直接有效——前者把 Client 名字注入到包命名空间，后者只是加载模块，Client 还得通过 mypkg.client.Client 访问。
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 推荐显式导入：
from .client import Client、from .utils import format_url - 避免
from .client import *，它会污染__all__控制，也掩盖了来源 - 如果模块里有大量要导出的符号，可以先
from .client import *再手动清掉不需要的：del _helper_func
__init__.py 中的相对导入路径容易写错
在 __init__.py 里用 from .submodule import X 是相对导入，点号数量和位置稍有偏差就会报 ImportError: attempted relative import with no known parent package 或 ModuleNotFoundError。
根本原因：Python 只有把一个目录当作包来运行（比如 python -m mypkg）或明确作为子模块导入时，才支持相对导入。直接运行 __init__.py 文件会失败。
- 确保包是通过
import mypkg或from mypkg import X方式导入，而不是python mypkg/__init__.py - 层级深时，用
from ..parent import X要小心——上级目录必须也是包（含__init__.py），且当前文件确实属于该包的子模块 - 调试时可临时加
print(__name__, __package__)看当前模块的全名和包上下文
别在 __init__.py 里做耗时初始化操作
有人习惯在 __init__.py 里连接数据库、读配置文件、初始化全局 client 实例——这会让任何一次 import mypkg 都变慢，甚至因环境缺失而失败，哪怕用户只想要其中某个工具函数。
典型问题场景：CI 环境没配 DB，但测试脚本只是 import mypkg.utils，却因 __init__.py 里执行了 init_db() 而崩溃。
- 把副作用操作移到单独函数里，比如
mypkg.init()，由用户显式调用 - 用懒加载模式：定义一个
_client = None，在首次访问属性时才创建实例 - 配置类可以预定义，但不要在导入时就解析
os.environ或读磁盘文件
最常被忽略的一点：__init__.py 的执行时机是模块首次导入时，且只执行一次。但它不是“包启动入口”，也不适合放业务逻辑——它只是命名空间的整理员。
