pyctdev：python开发者打包常用任务

工具（以及文档）支持跨多个类似项目执行常见任务，重点在于组成HoloViz.org的项目。

注意：文档是草案/目前正在编写

pyctdev是什么？

pyctdev的主要部分是一个跨平台的类似make的工具，以及常用任务的库，允许项目管理员任务在本地或在各种CI系统、不同平台上以相同的方式运行，或者支持不同的Python包'生态系统'（pip和conda）。

$ doit list
build_docs        build docs
develop_install   python develop install with specified optional groups of dependencies.
ecosystem_setup   Common pip setup
env_capture       Report all information required to recreate current environment.
env_create        TODO: create named environment if it doesn't already exist.
env_export        TODO
list_envs
package_build     Build pip package, then install and test all_quick (or other
package_upload    Upload pip packages to pypi
test_all          Run "all" tests
test_examples     Run "examples" tests
test_flakes       Run "flakes" tests
test_unit         Run "unit" tests

$ doit ecosystem=conda list
build_docs           build docs
develop_install      python develop install, with specified optional groups of dependencies (installed by conda only).
ecosystem_setup      Common conda setup (must be run in base env).
env_capture          Report all information required to recreate current conda environment
env_create           Create named environment if it doesn't already exist
env_export           Generate a pinned environment.yaml from specified env, filtering against specified groups of deps.
list_envs
miniconda_download   Download Miniconda3-latest
miniconda_install    Install Miniconda3-latest to location if not already present
package_build        Build and then test conda.recipe/ (or specified alternative).
package_upload       Upload package built from conda.recipe/ (or specified alternative).
test_all             Run "all" tests
test_examples        Run "examples" tests
test_flakes          Run "flakes" tests
test_unit            Run "unit" tests

尽管必须安装doit+pyctdev才能运行这些任务，但该方法是尽可能调用标准的python和/或conda工具，以便人们可以独立运行命令而无需安装doit+pyctdev。这意味着pyctdev可以被视为

• 所有常用任务的文档

• 执行这些任务所需的命令的文档

• 一种暴露我们可能希望填补的底层工具空白的方式（或暴露我们可能对其使用方法缺乏了解，因此我们可以得到纠正 :) )

• 一种将相对不变的“高层任务”（例如，“运行单元测试”）映射到可能随时间变化的具体命令的方式（例如，随着Python打包生态系统的变化）或在不同项目之间变化的方式（例如，使用nose或pytest运行测试）。

• 我们对如何执行各种任务的当前最佳理解（在尽可能最好的方式与在一般意义上实际上可行的方式之间取得平衡，考虑到当前广泛可用的工具）。

附带的背景文档（甚至比这个还要草案！）包含更多详细信息，以及选择解释。它分为相同的部分，因此可以与本文档一起阅读。

还提供了一个设置新项目的说明文档（但当前只是一个占位符...）。

如果您有问题，请随时打开一个issue（首先检查常见问题解答）。

pyctdev涵盖了哪些内容？

pyctdev仍在开发中，当它稳定下来后，我们将需要扩展这个描述，包括pyctdev打算覆盖的内容和哪些包管理方面不在范围之内。

0. 所有任务有哪些？如何运行一个任务？

pyctdev显示了所有任务，例如“运行单元测试”、“构建conda包”、“上传conda包”、“作为开发者安装”等。

pyctdev还记录了如何执行这些任务，即执行任务所需的必要命令或哪些任务应该在其他任务之前运行。

要查看所有任务，您可以在使用pyctdev的项目中输入doit list来获取带描述的任务列表。doit info提供了任何特定任务的更多详细信息。或者，您可以阅读pyctdev源代码；大多数任务都是简单的命令。

1. 可在本地、CI和跨平台上运行项目管理任务

doit/pyctdev是用python编写的，因此应该可以在任何有python的地方工作（不仅仅是在类Unix系统上，这与许多项目配置文件不同）。一旦有任何python可用，doit可以用于安装其他python（目前是miniconda和anaconda）。在各个平台上使用相同的命令运行有助于确保测试、包构建和相关任务在各个平台上的一致性，这对于开发者在使用一个平台但用户将下载另一个平台的包时尤其重要。

pyctdev使用的其他建议工具也是跨平台的：tox、conda、pip等。

2. 支持Python和conda生态系统

pyctdev支持使用python/pip或conda生态系统执行大多数任务。例如，doit develop_install通常运行pip install -e .[tests]，使用pip安装依赖项然后进行可编辑安装。或者，doit ecosystem=conda develop install将使用conda安装依赖项，然后进行可编辑安装。项目可以设置默认生态系统。

使用pip或conda安装、使用python工具（virtualenv+pip或pipenv）或conda工具（conda env）创建可重复/隔离的环境、为pip或conda打包，这些功能帮助主要使用一个生态系统的开发者仍然支持另一个生态系统（例如，通过CI系统）。

3. 支持多个Python版本

类似于允许开发者支持pip和conda生态系统，pyctdev允许开发者支持多个Python版本。对于Python，doit使用tox在多个环境中运行相同的测试。对于conda，pyctdev在多个Python版本上运行conda build。

依赖项集中在一处

pyctdev允许开发者将项目的“抽象”依赖项集中在一个地方。目前这个地方是setup.py，因为它被python和conda工具广泛支持。setup.py中列出的依赖项用于

• 最终用户pip包

• 最终用户conda包

• 使用conda的开发者

• 使用pip的开发者

• 生成环境文件（例如，环境文件examples environment.yml）

抽象依赖项可以转换为更具体的依赖项，例如，对于教程示例环境，所有依赖项的版本可以固定以确保可重复性（见下面的10/environment文件）。

pyctdev支持转换依赖项并生成environment.yml（以及可能的pipenv或类似工具）。

5. 为不同目的标记的依赖项

pyctdev支持表达构建和安装/运行时依赖项，以及各种可选的依赖项组（例如，用于运行示例、构建文档等）。

pyctdev 使用标准/普遍支持的 python/pip/setuptools setup.py 参数来实现这一点（install_requires 和 extras_require）。pip 可以理解这些参数，因此用户可以使用相同的可选依赖组（例如，用户可以运行 pip install package[examples] 来获取软件包以及运行示例所需的依赖项）。

为了支持 conda 生态系统中的 'options'，会生成多个包——尽管我们的项目通常只有 "base" 和 "examples" 包。 package-examples 依赖于特定的固定 package（在构建时固定）。

6. 测试用户安装的内容

pyctdev 鼓励测试用户将要安装的包，而不仅仅是关注测试开发人员正在使用的内容。

在 Python 生态系统中，tox 用于构建包，创建干净的虚拟环境，安装包，然后运行测试。tox 还支持在多个环境中（例如，使用不同集合的依赖项安装）运行相同的测试的多个版本。

在 conda 生态系统中，通过多次调用 conda build 来实现相同的功能。

7. 测试开发人员的行为

由于设置项目以运行测试困难，因此很难为项目做出贡献。经验丰富的项目开发人员知道自己在做什么，但对于偶尔的开发人员来说则不太明显。

pyctdev 确保开发项目所需的依赖项明显，并鼓励开发人员保持它们是最新的（例如，通过在中立的 CI 机器上测试 doit develop_install）。

pyctdev 还试图捕获开发人员设置其环境的方式。例如，conda 安装的依赖项，以及在其上运行 python setup.py develop --no-deps。

8. 在不同的环境中进行测试

例如，doit package_build --test-python=py36 --test_requires=with_xarray --test-group=unit 将构建一个包并将其安装到 Python 3.6 环境中，然后进一步安装 with_xarray 依赖项，然后运行单元测试。with_xarray 的依赖项在 tox.ini 中指定（单元测试命令也是如此）。这与 ecosystem=pip 和 ecosystem=conda 一起工作。也可以有仅在特定测试环境中运行的额外测试命令（例如 with_xarray）。

doit test_unit 将在您的当前环境中运行单元测试。如果有针对特定环境的额外命令，当您选择它时将运行。例如，doit test_unit --test-group with_xarray。但是，测试命令不会更改您的当前环境，因此如果需要，您需要安装 with_xarray 依赖项。

9. 按需提供的包？简化打包配方？

除了指定依赖项一次之外，pyct 还尝试将其他包元数据仅表达一次。目前这位于 setup.py 中。然后使用模板进行 conda 构建。这防止了描述、URL、许可证等不匹配的常见情况。

pyctdev 预期项目首先在 pypi 和 anaconda.org 通道上发布。从这些来源，conda-forge 可以更新，然后是 anaconda defaults（但我们不一定是这些通道的维护者）。

pyctdev 目前主要支持纯 Python 包。虽然它们可能经常具有复杂、特定平台的依赖项，但 pyct 控制的包到目前为止都是纯 Python。因此，我们尽可能地构建 noarch:python conda 包。如果我们开始维护带有二进制代码的包，pyct 将扩展以支持特定平台的包，但到目前为止，我们的包都不需要这样做。

10. 依赖项的通道/来源

对于 python/pip：通常是 pypi.org。但可以指定其他 '通道'。例如 test.pypi.org 或私有服务器。

我们维护的HoloViz.org的conda包通常可以安装在Anaconda默认或conda-forge之上。我们目前将它们放在anaconda.org pyviz（发布版）和pyviz/label/dev（开发版本）上，并且只有我们的特定包在这个渠道上。出于各种原因，我们建议不要混合安装conda-forge和默认设置。对于有复杂需求的工程，我们建议优先使用其中一个。如果项目在其中一个或另一个上性能不佳，我们会提出建议。

我们的Travis CI上的项目开发构建和开发包发布使用pyviz/label/dev来获取其他包，而发布包构建仅使用pyviz。然后如果开发者对那些包满意，应该更新conda-forge和默认设置。

11. 如何结构化项目

尽管这不是必需的，但一个常见的结构可以简化多个类似项目。HoloViz项目的存储库通常看起来像

package/
package/tests
package/tests/data
package/examples/
package/examples/data
package/examples/assets
examples -> package/examples

doc/       # minimal nbsite skeleton only
doc/assets # e.g. favicon - not relevant to notebooks

我们尽量限制存储库中的内容和发送给用户安装的包之间的差异，以避免创建自定义包构建代码。

12. 统一运行各种工具的方式

通常，不清楚如何运行项目的测试。Pyct通过提供高级任务（如“运行单元测试”）来帮助解决这个问题。然而，pyctdev也鼓励只出现一次的内部命令定义。

目前，setup.cfg用于存储命令的全局选项（例如，flake8规则），而tox.ini用于存储用于不同事情的各种实际命令（例如，运行单元测试、在不同的环境中运行测试等）。（待办事项：项目之间共享什么，以及如何共享？我们宁愿没有pyctdev的配置文件...）

13. 测试的内容以及如何测试。

有各种运行测试的工具（例如pytest，nose）。pyctdev的目标是让我们的HoloViz项目尽可能使用相同的开发工具，并以相同的方式配置这些工具。

• 单元测试：pytest

• Flakes：pyflakes

• 示例

  • 笔记本运行无误：pytest插件nbsmoke

  • 笔记本Flakes：pytest插件nbsmoke

  • 笔记本“数据测试”：pytest插件nbva

• 性能/基准测试：（pytest-benchmark，自定义内容，airspeed velocity，等等）

• ...?

pytest具有定义（标记）和选择要运行的一组测试的功能。因此，pyctdev期望有

• “慢测试”（pytest -m slow）

• ...?

14. 文档

网站

• nbsite示例 -> 网站

实时文档

• 用户尝试示例的实时/浏览器方式：mybinder

15. 版本控制

通过git标签进行版本控制。版本仅在存储库的一个地方存储（一个git标签），并写入包中。需要知道版本的地方（__init__.py；打包：setup.py，meta.yaml；文档）都从单一来源读取。

存储在一个地方，并且它是标签而不是git仓库源代码，这使得自动化其他各种“发布时间”任务更容易。我们的项目通常使用autover（通过param）。

版本控制方案

• 我们使用vX.Y.Z

• 1.0之后，（待办事项：复制hv的方案？）

16. 在Travis上自动化发布类型任务

尽可能通过运行一个或两个doit命令，我们避免使用CI提供的魔法，除非确实不可避免或非常有用（例如，并行化构建等），因为我们需要支持多个CI系统（Linux和Mac的Travis CI，以及Windows的Appveyor）。

自动生成的包

每个（开发）发布

• conda包被构建并上传到anaconda.org（pyviz/label/dev）pyviz/label/main

• pip包（sdist zip，通用wheel）被构建并上传到（test.pypi.org）pypi.org

发布发生时推送一个vX.Y.Z标签。开发发布可以是“每次合并到主分支”（例如，对于成熟的工程），或者“每次推送vX.Y.ZaN样式标签”（例如，对于快速变化的工程）。

注意：“包构建”是指生成包，将包安装到干净的环境中，然后运行测试。

自动生成的网站

两种主要选项

1. 适用于年轻、快速发展的项目：一个主网站（默认：https://package.github.io/），在发布时更新（可能还有特殊的发布后标签，我们在其中修复了一些文档问题而不更改代码，这显然需要特别标记），还有一个单独的开发网站（默认：https://pyviz-docs.github.io/package-master），在每次向master推送时（或每次推送alpha/beta/rc格式标签时）更新。

2. 与1相同，但还会存档每个主要版本的网站（即X.Y的一个副本，每个新的.Z版本都会更新）直到我们最终删除它们。可能实际上只需将2作为默认选项，其定义是只有版本1.0或更高才被视为主要版本，在这种情况下，它将遵循政策1直到达到1.0，然后遵循政策2，因此对于年轻、快速发展的项目在发布1.0之前采取适当的行动，然后存档每个x.y版本。

注意：例如，对于datashader，目前使用Travis CI是不可行的（构建时间过长/使用太多内存/需要太大数据）。但Travis只是使用doit命令，因此可以在发布时在本地运行相同的命令。

17. 额外的CI事项

平台

• Ubuntu (Travis CI)

• MacOS (Travis CI)

• Windows (appveyor)

缓存

对于某些项目，每次从头开始安装miniconda和依赖项会占用相当多的构建时间。

因此支持miniconda/conda环境的缓存。（python/pip也支持，尽管那里速度不是问题）。

在许多方面，这可以是一个比从头开始安装更好的测试，因为许多开发者和用户将更新现有的conda安装/环境，而不是从头开始。

构建阶段/构建的并行化

而不是按顺序运行任务（消耗墙钟时间；一个任务可能会影响后续的任务），任务可以在并行中独立运行。

添加到文档中

• 生成固定的conda包
• 生成environment.yml