1. 重导出在设计包入口时到底解决了什么问题很多人在第一次动手写自己的 Python 包时都会遇到同一个困惑我明明把Engine这个类写在了core.py里为什么用户却要写from mypackage.core import Engine而不是更自然的from mypackage import Engine答案就是标题里这个重导出re-export机制——一个模块把另一个模块里的名字再次暴露到自己的命名空间里让用户可以绕开内部层级、直接从包的最外层入口拿到它。重导出的本质是门面。拿现实里的公司前台打比方内部员工分布在各层各工位访客不需要知道想找的人具体坐哪一排只要到前台报个名字由前台把人带出来。包的__init__.py就是那个前台from .core import Engine就是把内部工位上的Engine带到大门口。用户永远不会关心Engine到底写在core.py、engine.py还是models/engine.py这是包作者自己消化掉的复杂度。标准库里有一个极佳的现实案例os.path。os模块本身并不实现任何路径操作在 POSIX 系统上它把posixpath绑到path这个属性上在 Windows 上则是ntpath。用户从头到尾就只跟os.path打交道底层的平台选择完全被重导出机制掩盖了。这就是重导出最有价值的使用场景适配内部差异、统一外部入口。对包作者来说重导出还承担着稳定公共 API的职责。内部模块是随时可以重排的 implementation detail今天Engine在core.py明天你可能想拆成engine/目录但用户写死的from mypackage import Engine不会因为你内部调整而崩掉。反过来如果一开始就让用户深入到mypackage.core.engine.Engine这一层那内部结构就变成了公共契约的一部分以后每动一次都是一次 breaking change。所以只要你写的包不只是一个单文件脚本只要你的项目里存在多个模块、但对外只需要一个简洁入口的情况重导出就不是可选项而是基本功。2.__init__.py的三种重导出写法从隐式到显式包的重导出工作通常都发生在__init__.py里因为这是包被 import 时最先执行、也天然握有包命名空间的文件。同一个重导出目标写法的差异比很多人以为的要大。2.1 写法一from .core import Engine最直白的形式直接把子模块里的对象导入到包的全局命名空间# mypackage/__init__.py from .core import Engine from .models import Model运行效果没有任何问题用户写from mypackage import Engine马上就通。但问题出在工具链怎么看它上。mypy 在--strict模式下会开启--no-implicit-reexport此时这种写法不会被当作刻意的公开重导出别的代码在from mypackage import Engine时静态检查可能直接报告模块没有显式导出该名字。pyright 在__init__.py里默认相对宽容但在普通模块里同样不保证把它视为导出。也就是说这种写法的行为在不同检查器、不同配置下不完全一致。2.2 写法二显式同名别名from .core import Engine as Engine运行时和写法一完全等价就是同一个对象、同一次导入区别只在于给人和工具一个明确的信号这个Engine是我故意暴露出去的公共名字。# mypackage/__init__.py from .core import Engine as Engine from .models import Model as Model这是我在所有面向外部使用的包里最推荐的写法。mypy、pyright 这类静态检查器看到X as X的形态就会明确把它标记为 re-export不再因为隐式重导出的语义分歧产生误报。它没有任何性能代价多出来的字符成本可以忽略不计但换来的是跨工具行为一致这笔账非常划算。2.3 写法三把整个子模块作为属性暴露有些情况你不想扁平化导出对象而是希望用户能按模块路径去使用# mypackage/__init__.py from . import utilsfrom . import utils会在包导入完成的瞬间把utils这个子模块作为包的属性挂好。用户之后既可以写from mypackage import utils也可以写mypackage.utils.helper()。需要注意import mypackage.utils这种写法在导入后同样会把utils挂到父包上但如果你的__init__.py自身没有主动导入它在包初始化期间访问mypackage.utils是拿不到的。显式from . import utils消除了这种时序上的不确定性。三种写法的取舍可以简单对照一下写法用户侧用法类型检查器识别适用场景from .core import Enginefrom mypackage import Engine部分工具不视为公开导出内部快速聚合、小项目from .core import Engine as Enginefrom mypackage import Engine明确视为重导出公共 API 入口最推荐from . import utilsfrom mypackage import utils子模块属性始终可用希望保留模块层级的场景有一点容易踩在__init__.py里写from . import utils时flake8 或 ruff 可能会提示 F401import 了但未使用。这其实是工具不知道你在做重导出。要么在行尾加# noqa: F401要么在工具的 per-file-ignores 里专门忽略__init__.py而不要因此放弃这种写法。3.__all__控制的是 export *而不是万能白名单聊完__init__.py的三种写法紧跟着就要面对__all__。这个特殊变量被误解得太深了很多人把它当成模块的唯一允许导出名单其实它的真正控制范围只有两个from module import *和交互环境里的dir()。3.1 没有__all__时的 star import 默认规则当模块没有定义__all__时from mypackage import *会导入模块里所有公有名字——即所有不以单下划线开头的全局属性。函数、类、变量、被导入的符号统统算数。这里有个隐蔽点哪怕你在__init__.py里只写了from .core import _internal_helper因为名字以下划线开头所以不会被 star import 带出去但如果你导入的是子模块本身比如from . import utils那么utils是一个不带下划线的属性会直接被 star import 曝光。3.2 定义__all__后的真实行为给模块加上__all__# mypackage/__init__.py from .core import Engine as Engine from .models import Model as Model __all__ [Engine, Model]此后from mypackage import *只能拿到__all__里列出的名字。同时CPython 的模块dir()实现也会优先使用__all__来生成排序后的属性列表——也就是说在交互终端里敲dir(mypackage)看到的将是__all__控制的集合而不是全部全局名字。这对收敛认知负担很有帮助但要注意它只是展示层面的过滤。__all__不是万能白名单的最有力证据是它拦不住普通的显式导入。即使Model没写进__all__只要Model确实存在于模块里用户写from mypackage import Model依然可以成功反过来如果__all__里写了MissingThing但模块里根本没有这个名字普通显式导入不受影响真正的雷会在from mypackage import *时爆出来——CPython 的IMPORT_STAR会逐个按__all__里的名字去取属性取不到就直接抛AttributeError。我建议把__all__当作对外公约而非代码逻辑上的闸门。它真正约束的是 star import 这一种用法但这是绝大多数用户第一次探索你包时最常触发的用法所以__all__仍然值得认真维护。3.3__all__与子模块__all__的联动包入口经常会把子模块的__all__作为自己的一部分。比如子模块models.py自己维护了__all__ [Model, Layer]那么__init__.py里写from .models import *时实际只会拿到Model和Layer子模块的__all__变成了包入口的过滤器。这套联动机制用好了很省心但有两个前提子模块必须真的维护了__all__否则 star import 会把子模块里所有不带下划线的名字全部倒出来其次__init__.py里如果同时from .core import *和from .models import *两个子模块同名符号会静默覆盖后面导入的赢。这个坑我在下一节详细展开。4. 重导出引发循环导入与名字遮蔽的完整排查重导出本身是个简单的机制但它一旦和模块初始化顺序纠缠起来就会变成最难排查的一类问题。我实际排查过的踩坑现场中循环导入和名字遮蔽占了绝大多数。4.1 循环导入重导出在最坏时机引爆最坏路径来看一个典型的失败结构包里有三个文件# mypackage/a.py from .b import B class A: def make_b(self): return B()# mypackage/b.py from .a import A class B: def use_a(self): return A()# mypackage/__init__.py from .a import A用户执行import mypackage时事件顺序是这样的包先执行__init__.py遇到from .a import A开始加载a.pya.py第一行执行from .b import B转去加载b.pyb.py第一行执行from .a import A但此时a.py只执行到了第一行A这个类还没定义出来Python 抛出ImportError: cannot import name A from partially initialized module。关键在于重导出把模块 imports 关系从业务逻辑里拎到了包入口原本分散在业务代码里的相互依赖会因为__init__.py的集中导入而全部提前触发。业务模块内部可能靠先用后导绕过了的问题在入口处全部现形。解决办法要看依赖方向。最直接的是把其中一个 import 挪进函数体# mypackage/b.py class B: def use_a(self): from .a import A return A()函数体内的 import 是在调用时才执行的到那时模块已经完全加载完毕不存在部分初始化的问题。第二种思路是把两个模块真正共同依赖的部分抽到第三个模块里消除环本身。第三种则是利用模块级__getattr__PEP 562做惰性重导出这部分我在下一节单独讲。4.2 名字遮蔽star import 的静默覆盖名字遮蔽最典型的现场就是__init__.py里的连续 star import# mypackage/__init__.py from .core import * from .models import *假设core.py定义了一个helpermodels.py也定义了一个helper那么第二次 star import 会悄悄把第一次导入的同名对象覆盖掉。没有任何错误提示唯一的结果是某些用户调用的mypackage.helper行为完全不符合预期。更麻烦的是这种问题在代码 review 时极难被发现因为 star import 本身就把导入了什么藏起来了。还有一类遮蔽是对内建名字的遮蔽。比如子模块里有人定义了class list如果你把它重导出到包顶层那么整个包的用户从此拿到的list都不是内建的那个。这种问题一旦出现就是灾难级的混乱所以在__init__.py里我强烈建议不要使用from .xxx import *所有名字用显式列表写清楚。4.3 IDE 和 lint 工具的提示谜题重导出还有一个让新手困惑的玄学现象明明__init__.py里from .core import Engine写得好好的VSCode 的自动补全就是不出Engine或者 flake8 一直报 F401 imported but unused。这两个现象其实是同一个根源工具默认不认为导入是为了重新暴露。F401 是静态代码规范层面的误报因为Engine确实没有被使用补全不出来则是因为 IDE 的解析器同样没有把Engine标记为包的公共属性。解法就是我前面说的显式别名Engine as Engine加上在__init__.py上对 F401 做豁免配置。这一行字符的差距能让你的编辑器体验和 CI 整洁度同时上一个台阶。5. 惰性重导出、PEP 562 和类型检查工具的配合重导出如果只是把名字提前倒到__init__.py里那它有一个天然代价凡是重导出的模块在包导入的那一刻就得全部加载完。一个包如果有二十个子模块哪怕用户只想用其中一个类也得先付出二十个模块的 import 成本。优化这个大包启动时间是另一个经典需求而模块级__getattr__把这件事实质上也变成了重导出的一种形态。5.1 利用模块级__getattr__实现惰性重导出PEP 562 从 Python 3.7 开始允许模块在找不到属性时触发一个自定义的__getattr__函数。这是标准库级的官方机制也是实现惰性加载最干净的手段# mypackage/__init__.py __all__ [HeavyService] def __getattr__(name): if name HeavyService: from .heavy import HeavyService return HeavyService raise AttributeError(fmodule {__name__!r} has no attribute {name!r}) def __dir__(): return sorted(set(globals()) | {HeavyService})当有人写from mypackage import HeavyService时Python 先在模块的全局字典里找找不到就调用__getattr__此时才真正导入heavy.py并返回对象。这个第一次访问才加载的语义让大包的用户体验好了很多只使用轻量功能的用户永远不必为重量级子模块买单。顺带说明一个容易忽略的细节如果__all__里列出了惰性名字from mypackage import *也会触发__getattr__。原因是 CPython 的IMPORT_STAR在处理__all__时逐个通过getattr去取属性并不是只查模块字典。所以在__all__里挂惰性名字是完全可行的前提是你的__getattr__对__all__中的每个名字都要有兜底否则 star import 会直接AttributeError。5.2 类型检查器如何识别重导出边界惰性重导出引入了另一个问题静态分析工具看不到运行时的__getattr__。mypy 和 pyright 不会执行你的代码它们在from mypackage import HeavyService时只能分析__init__.py的静态结构。如果HeavyService只存在于__getattr__的返回值里类型检查器就会报模块没有该属性。解决手段是提供一份.pyi存根文件明确声明惰性导出的类型# mypackage/__init__.pyi from .heavy import HeavyService as HeavyService这里同样用as HeavyService的同名别名让存根文件里的 import 也被类型检查器视为重导出而不是仅供内部使用。如果你的包在py.typed标记文件存在的前提下分发这份存根就是标准配置。再说回非惰性的普通重导出。mypy 的--strict模式自带--no-implicit-reexport在这个开关下任何没有写成X as X形式的导入都不会被当作公共 API。pyright 有自己的隐式重导出判定逻辑但结论一致不要依赖某个工具的默认宽容度显式写法是唯一不赌运气的方案。5.3 用__getattr__做渐进式废弃惰性重导出除了优化启动还有另一个妙用在删掉某个公共名字之前给用户一个平滑过渡期。# mypackage/__init__.py _LEGACY_NAMES {old_helper} def __getattr__(name): if name in _LEGACY_NAMES: import warnings warnings.warn( f{name} is deprecated, DeprecationWarning, stacklevel2, ) from .legacy import old_helper return old_helper raise AttributeError(fmodule {__name__!r} has no attribute {name!r})这样凡是访问旧名字的代码运行时都会收到明确的弃用警告而新名字不受影响。等过两个大版本再彻底移除用户迁移成本被压到最低。这个模式比在旧模块里堆deprecated装饰器要直观得多因为它作用在整个导出面上。6. 长期维护重导出 API 的几个习惯重导出机制本身只有几行代码真正决定它质量的是长期维护时的纪律性。我在自己的包里逐渐固化了这么几条规矩每一条都是用实际踩坑换来的第一条__init__.py里禁止from .xxx import *所有导出名字显式列出。这样 IDE 补全、类型检查、代码 review 都能看到精确的 API 面也不会被子模块悄悄新增的公有名字污染入口。第二条所有公共导出统一用X as X写法__all__紧随其后集中维护。让导出意图在代码里自解释而不是靠工具默认值去猜。第三条用一个测试脚本锁住 API 表面。比如在测试里断言__all__中的每个名字都能从包里正常导入且与globals()中的实际导出集合一致防止重构后名字漂移。这个测试成本极低但能避免我前面提到的__all__写了不存在的名字导致 star import 炸掉的经典事故。第四条公共名字只增不减。真要删先走__getattr__弃用警告过渡一个周期再在下一个大版本移除。对用户来说from mypackage import X一旦写进代码就是她和你的包之间的契约单方面撕毁的代价是社区信任。最后说一点个人体会。重导出这个机制翻译成一句话就是麻烦留在写包的人这边方便留给用包的人那边。只要你写的是一个会被人 import 的 Python 包那么今天多花十分钟把__init__.py的导出面设计清楚、把__all__和显式别名对齐未来能省下的是无数个为什么用户导不到这个类的深夜排查。