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

Question

Python烹饪本建议“典型库包”的树结构如下

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包。

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

在不修改路径的情况下，是否有实现这一目标的方法？如果修改路径是唯一的方法，那么是否有一种方法可以以一种优雅的方式完成？

让我详细说明最后一点。在肯尼思·里茨的“存储库结构和Python”中，出现了类似的结构，tests/代替了examples/。这是完全相同的问题。他建议使用“简单的(但显式的)路径修改来正确地解析包”。好的，但这是实际代码：

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

我真的不喜欢..那部分。我希望有一个更通用的解决方案，希望它能在我选择运行示例(或测试)的哪个目录下工作。

Answer 1

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

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

用户通常会安装使用它们的软件包。对于开发人员来说，有一个清晰的工作流：

1. 安装pip和virtualenv (更好的是，虚拟包装器)
2. 使用pip的-e标志以可编辑模式安装包，这意味着对代码所做的任何更改都将直接影响执行。您不必每次更改代码时都重新安装。
3. 由于您的代码总是安装的(特别是，在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

在可编辑模式下安装的包意味着有一个指向包目录的鸡蛋链接文件：

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

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