如何在包中包含示例或测试程序？

Question

Python Cookbook 为 "typical library package" 建议以下树结构：

projectname/
    README.txt
    Doc/
        documentation.txt
    projectname/
        __init__.py
        foo.py
        bar.py
        utils/
            __init__.py
            spam.py
            grok.py
    examples/
        helloworld.py

你会注意到 examples/ 不是实际包的一部分，它位于 projectname/projectname/ 下（你会在那里找到顶级 __init__.py包）。

嗯，examples/helloworld.py 显然需要导入 projectname 包。

我知道 Whosebug 中至少有 2-3 个相关问题。我不认为这是重复的，因为其他问题要么涉及包内导入，要么涉及从另一个 python 模块不在同一目录中的模块导入的一般情况。在打包库时，我特别询问建议的方法。

有没有不修改路径就可以实现的方法？如果修改路径是唯一的方法，有没有办法以优雅的方式完成此操作？

让我详细说明最后一点。在 Kenneth Reitz 的 Repository Structure and Python 中，出现了类似的结构，其中 tests/ 而不是 examples/。这是完全相同的问题。他建议使用 "a simple (but explicit) path modification to resolve the package properly." OK，但这是实际代码：

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

我真的不喜欢 .. 部分。我希望有一个更通用的解决方案，希望这个解决方案可以从我选择的任何目录运行到运行示例（或测试）。

Answer 1

虽然文件夹树看起来没问题，但我认为从开发人员和用户的角度来看，隐含地假设模块可用于导入是错误的。

从技术上讲，您确实可以使用 sys.path.insert(0, os.path.abspath('..')) 为 python 添加任何路径以允许从中导入，但这意味着您，开发人员，必须确保添加的路径始终是在正确的位置。

用户安装包来使用它们是很常见的。开发人员有一个清晰的工作流程：

安装 pip 和 virtualenv（更好的是，virtualenvwrapper）
使用 pip 的 -e 标志以可编辑模式安装包，这意味着您对代码所做的任何更改都将直接影响执行。您不必在每次更改代码时都重新安装。
由于您的代码总是被安装（具体来说，在 site-packages 下作为用户，但在您开发时处于可编辑模式），您始终可以使用任何示例或测试中的明确名称导入您的包。

一个常见的工作流程：

$ pip install virtualenv
...
$ virtualenv distro
New python executable in /home/nir0s/work/distro/bin/python3
Also creating executable in /home/nir0s/work/distro/bin/python
Installing setuptools, pip, wheel...done.

$ source distro/bin/activate

# install in editable mode
$ pip install -e ~/repos/nir0s/distro/
Obtaining file:///home/nir0s/repos/nir0s/distro
Installing collected packages: distro
  Running setup.py develop for distro
Successfully installed distro

(distro) $ pip freeze
appdirs==1.4.3
-e git+git@github.com:nir0s/distro@e8a182f9d1dbe6391f25...#egg=distro
packaging==16.8
pyparsing==2.2.0
six==1.10.0

包，以可编辑模式安装，意味着有一个egg-link文件指向包的目录：

$ cat distro/lib/python3.6/site-packages/distro.egg-link 
/home/nir0s/repos/nir0s/distro

用户将在不处理可编辑模式的情况下做同样的事情。只需创建虚拟环境并在其中安装包。然后，当他们完成工作后，他们将删除那些虚拟环境。简单易行。

如何在包中包含示例或测试程序？

How to include examples or test programs in a package?

python

python-import

python-packaging