python 组织模块和包的 Pythonic 方式

The Pythonic way of organizing modules and packages

提问by carl

I come from a background where I normally create one file per class. I organize common classes under directories as well. This practice is intuitive to me and it has been proven to be effective in C++, PHP, JavaSript, etc.

我的背景是我通常为每个班级创建一个文件。我也在目录下组织公共类。这种做法对我来说很直观，并且在 C++、PHP、JavaSript 等中被证明是有效的。

I am having trouble bringing this metaphor into Python: files are not just files anymore, but they are formal modules. It doesn't seem right to just have one class in a module --- most classes are useless by themselves. If I have a automobile.pyand an Automobileclass, it seems silly to always reference it as automobile.Automobileas well.

我在将这个比喻引入 Python 时遇到了麻烦：文件不再只是文件，而是正式的模块。在一个模块中只包含一个类似乎是不正确的——大多数类本身是无用的。如果我有一个automobile.py和一个Automobile类，总是引用它似乎很愚蠢automobile.Automobile。

But, at the same time, it doesn't seem right to throw a ton of code into one file and call it a day. Obviously, a very complex application should have more than 5 files.

但是，与此同时，将大量代码放入一个文件并收工似乎是不正确的。显然，一个非常复杂的应用程序应该有 5 个以上的文件。

What is the correct---or pythonic---way? (Or if there is no correct way, what is your preferred way and why?) How much code should I be throwing in a Python module?

什么是正确的---或pythonic---方式？（或者，如果没有正确的方法，您的首选方法是什么？为什么？）我应该在 Python 模块中投入多少代码？

采纳答案by Alex Martelli

Think in terms of a "logical unit of packaging" -- which may be a single class, but more often will be a set of classes that closely cooperate. Classes (or module-level functions -- don't "do Java in Python" by always using static methods when module-level functions are also available as a choice!-) can be grouped based on this criterion. Basically, if most users of A also need B and vice versa, A and B should probably be in the same module; but if many users will only need one of them and not the other, then they should probably be in distinct modules (perhaps in the same package, i.e., directory with an __init__.pyfile in it).

从“包装的逻辑单元”的角度考虑——它可能是一个单一的类，但更多时候是一组紧密合作的类。类（或模块级函数——当模块级函数也可以作为一种选择时，不要通过总是使用静态方法“在 Python 中执行 Java”！-）可以基于这个标准进行分组。基本上，如果 A 的大多数用户也需要 B，反之亦然，那么 A 和 B 应该在同一个模块中；但是如果许多用户只需要其中一个而不需要另一个，那么它们可能应该在不同的模块中（可能在同一个包中，即其中包含一个__init__.py文件的目录）。

The standard Python library, while far from perfect, tends to reflect (mostly) reasonably good practices -- so you can mostly learn from it by example. E.g., the threadingmodule of course defines a Threadclass... but it also holds the synchronization-primitive classes such as locks, events, conditions, and semaphores, and an exception-class that can be raised by threading operations (and a few more things). It's at the upper bound of reasonable size (800 lines including whitespace and docstrings), and some crucial thread-related functionality such as Queue has been placed in a separate module, nevertheless it's a good example of what maximum amount of functionality it still makes sense to pack into a single module.

标准 Python 库虽然远非完美，但往往反映（大部分）合理的良好实践——因此您可以通过示例从中学习。例如，该threading模块当然定义了一个Thread类……但它也包含同步原语类，例如锁、事件、条件和信号量，以及一个可以由线程操作引发的异常类（以及一些其他的东西） ）。它处于合理大小的上限（800 行，包括空格和文档字符串），并且一些关键的线程相关功能（例如 Queue）已放置在单独的模块中，但它是一个很好的示例，说明它仍然有意义的最大功能量打包成一个模块。

回答by Conrad Meyer

If you want to stick to your one-class-per-file system (which is logical, don't get me wrong), you might do something like this to avoid having to refer to automobile.Automobile:

如果你想坚持你的一个类每个文件系统（这是合乎逻辑的，不要误会我的意思），你可以做这样的事情来避免参考automobile.Automobile：

from automobile import Automobile
car = Automobile()

However, as mentioned by cobbal, more than one class per file is pretty common in Python. Either way, as long as you pick a sensible system and use it consistently, I don't think any Python users are going to get mad at you :).

然而，正如 cobbal 所提到的，在 Python 中每个文件不止一个类是很常见的。无论哪种方式，只要您选择一个合理的系统并始终如一地使用它，我认为任何 Python 用户都不会对您生气:)。

回答by mtvee

If you are coming from a c++ point of view, you could view python modules akin to a .so or .dll. Yeah they look like source files, because python is scripted, but they are actually loadable libraries of specific functionality.

如果您从 C++ 的角度来看，您可以查看类似于 .so 或 .dll 的 python 模块。是的，它们看起来像源文件，因为 python 是脚本化的，但它们实际上是具有特定功能的可加载库。

Another metaphor that may help is you might look python modules as namespaces.

另一个可能有帮助的比喻是您可能将 python 模块视为名称空间。

回答by eswald

In a mid-sized project, I found myself with several sets of closely related classes. Several of those sets are now grouped into files; for example, the low-level network classes are all in a single networkmodule. However, a few of the largest classes have been split out into their own file.

在一个中等规模的项目中，我发现自己有几组密切相关的类。其中一些集合现在被分组到文件中；例如，低级网络类都在一个network模块中。但是，一些最大的类已被拆分到它们自己的文件中。

Perhaps the best way to start down that path from a one-class-per-file history is to take the classes that you would normally place in the same directory, and instead keep them in the same file. If that file starts looking too large, split it.

也许从每个文件一个类的历史开始沿着这条路径开始的最好方法是采用通常放置在同一目录中的类，而不是将它们保存在同一文件中。如果该文件看起来太大，请将其拆分。

回答by cobbal

As a vague guideline: more than 1 class per file is the norm for python

作为一个模糊的指导方针：每个文件超过 1 个类是 python 的规范

also, see How many Python classes should I put in one file?

另请参阅我应该在一个文件中放入多少个 Python 类？