需要适用于python软件包的正确目录结构以及有关良好API设计的准则

Question

我正在发布python软件包，并对包装的各个方面感到困惑。

首先，我的目录结构如下：

SamplePackage/
 - setup.py
 - README.rst
 - LICENSE.rst
 - sampledir/
    -__init__.py
    -sample.py
    -utils.py

当前__init__和setup尚未填充。 sample.py是软件包的任何用户都想要导入的文件。 它包含具有不同功能形式的api： foo1 ， foo2 。

utils.py包含帮手小说smaple.py 。 后者包含一条语句import utils

放在sampledir目录下的任何脚本都可以轻松import sample并将小说用作sample.foo1() 。 退出该目录，我可以调用import sampledir ，但不能调用import sample ，这是预期的。 所以我需要from sampledir import sample 。 这导致sample.py的import utils行出现错误

ImportError: No module named 'utils'

在某些地方，我看到了在同一目录中import .utils文件的信息。 但是，当我尝试这样做时，会导致语法错误。

为什么我不能从sampledir外部导入sample.py ？

同样，什么样的目录结构将允许已安装软件包的用户能够简单地调用import sample然后调用sample.foo1() ，而不必from sampledir import sample或import sampeldir.sample 。 例如，在使用HTTP库requests ，只需将其导入并调用requests.get(url) 。 像在urllib一样，不需要urllib requests.requests.get('url') 。 如果我想将该包命名为sample ，那么实现该目的的正确目录命名和安排是什么？

Answer 1

首先，我想你误解了包和项目之间的区别。 您的目录结构应该是这样的

arbitrary_name_of_project/
 - setup.py
 - README.rst
 - LICENSE.rst
 - package_name/
    -__init__.py
    -sample.py
    -utils.py

存在文件__init__.py来“标记” Python软件包。 Python在他的PYTHONPATH上搜索，并寻找文件__init__.py所有目录（简单地说，实际上要复杂得多）。 这些是您可以在运行时导入的程序包。

在我们的情况下，仅package_name目录将安装在PYTHONPATH某个位置。 因此，安装完成后（通过setup.py和disutils或setuptools ），您可以输入

import package_name

现在，您可以从此包中的任何模块调用任意类或函数，或诸如此类

package_name.sample.func1()

如果要避免在调用中键入package_name.sample ，可以将此行放在__init__.py

from .sample import func1

然后，在“导入时间”期间将函数func1放入您的全局名称空间。 在程序中执行import package_name时，会发生这种情况。 可以通过每次导入包时都执行__init__.py文件这一事实来解决此问题。

有时有必要吐更多的东西。 您可以具有“嵌套”包（即，需要导入的包中的包）。 还有名称空间包，您可以在其中将一个包“吐”到更多目录中。 世界是多元化的。 :)

免责声明

我写的是没有测试我提供的代码。 可能会有小的错别字，但我希望这个故事或多或少是正确的。 请，如果我错了，请纠正我。