Python包的API。在__init__.py中？

Question

我写了一个Python包，这个包里面有几个.py文件，里面包含了一些类等等。我想用“外观模式”来对外提供这个包的功能。也就是说，我不想让使用这个包的客户了解所有内部的类，只希望他们能使用这个API接口提供的方法。

我的问题是：我应该把这个API放在哪里呢？是应该在包里面定义一个api.py文件，还是可以把这个API放在包的__init__.py文件里呢？

我用一个例子来解释得更清楚一些

<my_module>\
     __init__.py
     core.py
     submodule1.py
     submodule2.py
     util.py
     ........

那么，我应该把公共API放在哪里呢？

Answer 1

把API放在 __init__.py 里有一些缺点：

• 可能会导致循环依赖的问题
• 在浏览代码时，这里并不是一个明显的查找位置

把API放在像 api.py 这样的专门模块里，可以避免这些问题。此外，还有一些优点：

• 你可以在后面再提供一个不同的API，放在第二个模块里（比如简化版或用于不同的场景等）
• 一些大型Python项目，比如Enthought的 traits.api 和Trac的 trac.api 都采用了这种做法

Answer 2

__init__.py 文件是一个合适的地方，可以放置公共接口或者一个包，而里面的其他模块则负责具体的实现。

Answer 3

最常用的做法是使用 __init__.py 文件。如果你的代码比较复杂，才值得把它拆分成一个或多个模块。否则，这样做就没什么意义了；更重要的是，如果你提供了不同的接口，比如一个简单易用但功能少的版本和一个功能丰富的复杂版本，那么把它们放在不同的模块里会让事情更有条理。

为了让使用你这个包的人知道他们不应该直接导入其他模块，你可以给你的“私有内部实现模块”起个名字，前面加个下划线：比如 _core.py，而不是 core.py。在Python中，这种命名规则是用来区分公共接口和内部实现细节的，花点小力气去遵循这个规则是非常值得的！