如何编写好的/正确的包 __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

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

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

Answer 2

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

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

我认为在__init__.py 中使用import * 来导入包的最有力的原因之一是能够在不破坏现有应用程序的情况下重构已经发展为多个脚本的脚本。但是如果你从一开始就设计一个包。我认为最好将__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

那么初始化脚本可以说

__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 3

您的__init__.py 应该有一个文档字符串。

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

对于任何其他内容，请参阅 firecrow 和 Alex Martelli 的出色回答。