如何将多个 python 文件组织成一个模块而不像一个包？

Question

有没有办法使用 __init__.py 将多个文件组织到一个 模块 中？

原因：模块比包更容易使用，因为它们没有那么多的命名空间层。

通常它会制作一个包裹，我明白了。问题出在包上，’import thepackage’ 给了我一个空的命名空间。然后，用户必须要么使用“from thepackage import *”（不赞成），要么确切知道其中包含什么，然后手动将其拉出到可用的命名空间中。

我想要的是用户“导入包”并拥有看起来像这样的漂亮干净的命名空间，公开与项目相关的函数和类以供使用。

 current_module
\
  doit_tools/
  \
   - (class) _hidden_resource_pool
   - (class) JobInfo
   - (class) CachedLookup
   - (class) ThreadedWorker
   - (Fn) util_a
   - (Fn) util_b
   - (Fn) gather_stuff
   - (Fn) analyze_stuff

维护者的工作是避免在不同的文件中定义相同的名称，当项目像我这样的小项目时，这应该很容易。

如果人们可以做 from doit_stuff import JobInfo 并让它检索类，而不是包含类的模块，那也很好。

如果我所有的代码都在一个巨大的文件中，这很容易，但我喜欢在事情开始变大时进行组织。我在磁盘上的内容看起来像这样：

 place_in_my_python_path/
  doit_tools/
    __init__.py
    JobInfo.py
      - class JobInfo:
    NetworkAccessors.py
      - class _hidden_resource_pool:
      - class CachedLookup:
      - class ThreadedWorker:
    utility_functions.py
      - def util_a()
      - def util_b()
    data_functions.py
      - def gather_stuff()
      - def analyze_stuff()

我只将它们分开，这样我的文件就不会太大且无法导航。它们都是相关的，尽管有人（可能是我）可能想自己使用这些类而不导入所有内容。

我已经阅读了各种线程中的许多建议，以下是我可以找到的关于如何执行此操作的每条建议所发生的情况：

如果我 不使用 __init__.py ，我将无法导入任何内容，因为 Python 不会从 sys.path 进入文件夹。

如果我 使用空白 __init__.py ，当我使用 import doit_tools 时，它是一个空的名称空间，其中没有任何内容。我的文件都没有导入，这使得它更难使用。

如果我 在 __all__ 中列出子模块，我可以使用（不赞成？） from thing import * 语法，但我的所有类再次位于不必要的命名空间障碍之后。用户必须 (1) 知道他们应该使用 from x import * 而不是 import x ，(2) 手动重新排列类，直到它们可以合理地遵守线宽样式约束。

如果我 将 from thatfile import X 语句添加到 __init__.py ，我会更接近但我有名称空间冲突（？）和额外的名称空间用于我不想在那里的东西。在下面的示例中，您会看到：

1. JobInfo 类覆盖了名为 JobInfo 的模块对象，因为它们的名称相同。 Python 可以通过某种方式解决这个问题，因为 JobInfo 的类型是 <class 'doit_tools.JobInfo.JobInfo'> 。 （doit_tools.JobInfo 是一个类，但 doit_tools.JobInfo.JobInfo 是同一个类……这很纠结，看起来很糟糕，但似乎没有破坏任何东西。）
2. 每个文件名都进入了 doit_tools 命名空间，如果有人正在查看模块的内容，这会使查看更加混乱。我想要 doit_tools.utility_functions.py 来保存一些代码，而不是定义一个新的命名空间。

.

 current_module
\
  doit_tools/
  \
   - (module) JobInfo
      \
       - (class) JobInfo
   - (class) JobInfo
   - (module) NetworkAccessors
      \
       - (class) CachedLookup
       - (class) ThreadedWorker
   - (class) CachedLookup
   - (class) ThreadedWorker
   - (module) utility_functions
      \
       - (Fn) util_a
       - (Fn) util_b
   - (Fn) util_a
   - (Fn) util_b
   - (module) data_functions
      \
       - (Fn) gather_stuff
       - (Fn) analyze_stuff
   - (Fn) gather_stuff
   - (Fn) analyze_stuff

此外，仅导入数据抽象类的人在执行“from doit_tools import JobInfo”时会得到与他们预期不同的东西：

 current_namespace
\
 JobInfo (module)
  \
   -JobInfo (class)

instead of:

current_namespace
\
 - JobInfo (class)

那么，这只是一种组织 Python 代码的错误方式吗？如果不是，什么是拆分相关代码但仍然以类似模块的方式收集它的正确方法？

也许最好的情况是做“from doit_tools import JobInfo”会让使用这个包的人有点困惑？

也许是一个名为“api”的 python 文件，以便使用该代码的人执行以下操作？：

 import doit_tools.api
from doit_tools.api import JobInfo

============================================

回应评论的例子：

在 python 路径中的文件夹“foo”中获取以下包内容。

foo/__init__.py

 __all__ = ['doit','dataholder','getSomeStuff','hold_more_data','SpecialCase']
from another_class import doit
from another_class import dataholder
from descriptive_name import getSomeStuff
from descriptive_name import hold_more_data
from specialcase import SpecialCase

foo/specialcase.py

 class SpecialCase:
    pass

foo/more.py

 def getSomeStuff():
    pass

class hold_more_data(object):
    pass

foo/stuff.py

 def doit():
    print "I'm a function."

class dataholder(object):
    pass

做这个：

 >>> import foo
>>> for thing in dir(foo): print thing
...
SpecialCase
__builtins__
__doc__
__file__
__name__
__package__
__path__
another_class
dataholder
descriptive_name
doit
getSomeStuff
hold_more_data
specialcase

another_class 和 descriptive_name 是杂乱无章的，并且在它们的名称空间下还有额外的 doit() 副本。

如果我在名为 Data.py 的文件中有一个名为 Data 的类，当我执行“from Data import Data”时，我会遇到命名空间冲突，因为 Data 是当前命名空间中的一个类，它位于模块 Data 中，不知何故也在当前命名空间。 （但 Python 似乎能够处理这个问题。）

原文由 Brian 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

您可以这样做，但这并不是一个好主意，并且您正在与 Python 模块/包的工作方式作斗争。通过在 __init__.py 中导入适当的名称，您可以使它们在包命名空间中可访问。通过删除模块名称，您可以使它们不可访问。 （为什么需要删除它们，请参阅 此问题）。所以你可以用这样的东西接近你想要的东西（在 __init__.py 中）：

 from another_class import doit
from another_class import dataholder
from descriptive_name import getSomeStuff
from descriptive_name import hold_more_data
del another_class, descriptive_name
__all__ = ['doit', 'dataholder', 'getSomeStuff', 'hold_more_data']

但是，这将破坏后续对 import package.another_class 的尝试。一般来说，你不能从 package.module 导入任何东西而不使 package.module 可作为对该模块的可导入引用访问（尽管使用 __all__ 可以控制 from package import * ）。

更一般地说，通过按类/函数拆分代码，您是在针对 Python 包/模块系统工作。 Python 模块通常应包含您要作为一个单元导入的内容。为了方便起见，直接在顶层包命名空间中导入子模块组件并不少见，但反过来——试图隐藏子模块并 只 允许通过顶层包命名空间访问它们的内容——将导致问题。此外，尝试“清理”模块的包名称空间也无济于事。这些模块应该在包命名空间中；那是他们属于的地方。

原文由 BrenBarn 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 2

在 __all__ = ['names', 'that', 'are', 'public'] __init__.py 例如：

 __all__ = ['foo']

from ._subpackage import foo

现实世界的例子： numpy/__init__.py 。

---

您对 Python 包的工作方式有一些误解：

如果我不使用 __init__.py ，我将无法导入任何内容，因为 Python 不会从 sys.path 进入文件夹。

在 Python 3.3 之前的 Python 版本中，您需要 __init__.py 文件来将目录标记为包含 Python 包。

如果我使用空白 __init__.py ，当我导入 doit_tools 时，它是一个空名称空间，其中没有任何内容。我的文件都没有导入，这使得它更难使用。

它不会阻止导入：

 from doit_tools import your_module

它按预期工作。

如果我在 __all__ 中列出子模块，我可以使用（不赞成？） from thing import * 语法，但我的所有类再次位于不必要的命名空间障碍之后。用户必须 (1) 知道他们应该使用 from x import * 而不是 import x ，(2) 手动重新排列类，直到它们可以合理地遵守线宽样式约束。

(1) 您的用户（在大多数情况下） 不应 在交互式 Python shell 之外使用 from your_package import * 。

(2) 你可以使用 () 来打破一个长的导入行：

 from package import (function1, Class1, Class2, ..snip many other names..,
                     ClassN)

如果我将 from thatfile import X 语句添加到 __init__.py ，我会更接近但我有名称空间冲突（？）和额外的名称空间用于我不想在那里的东西。

由您来解决命名空间冲突（具有相同名称的不同对象）。该名称可以指代任何对象：整数、字符串、包、模块、类、函数等。Python 无法知道您可能更喜欢哪个对象，即使可以，在这种特殊情况下忽略某些名称绑定也是不一致的关于在所有其他情况下名称绑定的使用。

要将名称标记为非公开，您可以在它们前面加上 _ 例如， package/_nonpublic_module.py 。

原文由 jfs 发布，翻译遵循 CC BY-SA 3.0 许可协议