如何编写正确/正确的包__init__.py文件

Question

我的包具有以下结构：

mobilescouter/
    __init__.py #1
    mapper/
        __init__.py  #2
        lxml/
            __init__.py #3
            vehiclemapper.py
            vehiclefeaturemapper.py
            vehiclefeaturesetmapper.py
        ...
        basemapper.py
   vehicle/
        __init__.py #4
        vehicle.py
        vehiclefeature.py
        vehiclefeaturemapper.py
   ...

我不确定__init__.py文件应该如何正确写入。
__init__.py #1看起来像：

__all__ = ['mapper', 'vehicle']
import mapper
import vehicle

但是，例如__init__.py #2应该怎么样？我的是：

__all__ = ['basemapper', 'lxml']
from basemaper import *
import lxml

什么时候应该使用__all__？

Answer 1

__all__非常好 - 它有助于引导导入语句而无需自动导入模块 http://docs.python.org/tutorial/modules.html#importing-from-a-package

使用__all__和import *是多余的，只需要__all__

我认为在import *中使用__init__.py导入包的最有力的原因之一是能够重构已经发展成多个脚本而不破坏现有应用程序的脚本。但是，如果你从一开始就设计一个包。我认为最好将__init__.py个文件留空。

例如：

foo.py - contains classes related to foo such as fooFactory, tallFoo, shortFoo

然后应用程序增长，现在它是一个完整的文件夹

foo/
    __init__.py
    foofactories.py
    tallFoos.py
    shortfoos.py
    mediumfoos.py
    santaslittlehelperfoo.py
    superawsomefoo.py
    anotherfoo.py

然后init脚本可以说

__all__ = ['foofactories', 'tallFoos', 'shortfoos', 'medumfoos',
           'santaslittlehelperfoo', 'superawsomefoo', 'anotherfoo']
# deprecated to keep older scripts who import this from breaking
from foo.foofactories import fooFactory
from foo.tallfoos import tallFoo
from foo.shortfoos import shortFoo

以便在更改期间写入以执行以下操作的脚本不会中断：

from foo import fooFactory, tallFoo, shortFoo

Answer 2

我自己的__init__.py文件经常是空的。特别是，我从来没有from blah import *作为__init__.py的一部分 - 如果“导入包”意味着获得所有类，函数等直接定义为包的一部分，那么我将词法复制将blah.py的内容改为包__init__.py，而删除blah.py（源文件的乘法在这里没有用。）

如果你确实坚持支持import *成语（eek），那么使用__all__（尽可能小的名字列表，你可以自己拥有它）可能有助于损害控制。一般来说，名称空间和显式导入是好的东西，我强烈建议重新考虑基于系统地绕过其中一个或两个概念的任何方法！ - ）

Answer 3

您的__init__.py应该具有 docstring 。

尽管所有功能都在模块和子包中实现，但包docstring是记录从何开始的地方。例如，考虑python email package。软件包文档是介绍性的介绍，描述了目的，背景以及软件包中各个组件如何协同工作。如果您使用sphinx或其他软件包从文档字符串自动生成文档，则文档字符串doc正是描述此类介绍的正确位置。

有关其他任何内容，请参见firecrow和Alex Martelli的出色答案。