更好用的 Python 任务自动化工具：nox 官方教程

英文| nox tutorial

出处| nox 官方文档

译者| 豌豆花下猫@Python猫

Github地址：https://github.com/chinesehuazhou/nox_doc_cn

声明：本翻译基于CC BY-NC-SA 4.0受权协议，内容略有改动，转载请保留原文出处，请勿用于商业或非法用途。

本教程将引导你学会安装、配置和运行 Nox。

安装

Nox 能够经过pip轻松安装：

python3 -m pip install nox

你可能但愿使用用户站点(user site)来避免对全局的 Python install 形成混乱：

python3 -m pip install --user nox

或者，你也能够更精致，使用pipx：

pipx install nox

不管用哪一种方式，Nox 一般是要全局安装的，相似于 tox、pip和其它相似的工具。

若是你有兴趣在docker 内运行 nox，可使用 DockerHub 上的thekevjames/nox镜像，它包含全部 nox 版本的构建与及全部支持的 Python 版本。

若是你想在GitHub Actions中运行 nox ，则可使用Activatedleigh/setup-nox action，它将安装最新的 nox，并令 GitHub Actions 环境提供的全部 Python 版本可用。

编写配置文件

Nox 经过项目目录中一个名为 noxfile.py 的文件做配置 。这是一个 Python文件，定义了一组会话（sessions）。一个会话是一个环境和一组在这个环境中运行的命令。若是你熟悉 tox，会话就相似于它的环境。若是你熟悉 GNU Make，会话则相似于它的 target。

会话使用 @nox.session 装饰器做声明。这方式相似于 Flask 使用 @app.route。

下面是一个基本的 Nox 文件，对 example.py 运行flake8（你能够本身建立example.py）：

import nox

@nox.session
def lint(session):
    session.install("flake8")
    session.run("flake8", "example.py")

第一次运行 Nox

如今，你已经安装了 Nox 并拥有一个配置文件， 那就能够运行 Nox 了！在终端中打开项目的目录，而后运行nox 。你应该会看到相似这样的内容：

$ nox
nox > Running session lint
nox > Creating virtualenv using python3.7 in .nox/lint
nox > pip install flake8
nox > flake8 example.py
nox > Session lint was successful.

✨如今你已第一次成功地使用 Nox 啦！✨

本教程的其他部分将带你学习其它能够用 Nox 完成的常见操做。若是须要的话，你还能够跳至命令行用法和配置＆API文档。

安装依赖项

Nox 基本上是将 session.install 传递给 pip ，所以你能够用一般的方式来安装东西。这里有一些例子：

（1）一次安装一个或多个包：

@nox.session
def tests(session):
    # same as pip install pytest protobuf>3.0.0
    session.install("pytest", "protobuf>3.0.0")
    ...

（2）根据 requirements.txt 文件安装：

@nox.session
def tests(session):
    # same as pip install -r -requirements.txt
    session.install("-r", "requirements.txt")
    ...

（3）若是你的项目是一个 Python 包，而你想安装它：

@nox.session
def tests(session):
    # same as pip install .
    session.install(".")
    ...

运行命令

session.run 函数可以让你在会话的虚拟环境的上下文中运行命令。如下是一些示例：

（1）你能够安装和运行 Python 工具：

@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest")

（2）若是你想给一个程序传递更多的参数，只需给 run 添加更多参数便可：

@nox.session
def tests(session):
    session.install("pytest")
    session.run("pytest", "-v", "tests")

（3）你还能够传递环境变量：

@nox.session
def tests(session):
    session.install("black")
    session.run(
        "pytest",
        env={
            "FLASK_DEBUG": "1"
        }
    )

有关运行程序的更多选项和示例，请参见nox.sessions.Session.run()。

选择要运行的会话

一旦你的 Noxfile 中有多个会话，你会注意到 Nox 将默认运行全部的会话。尽管这颇有用，可是一般一次只须要运行一两个。

你可使用--sessions参数（或-s）来选择要运行的会话。你可使用--list参数显示哪些会话可用，哪些将会运行。这里有一些例子：

这是一个具备三个会话的 Noxfile：

import nox

@nox.session
def test(session):
    ...

@nox.session
def lint(session):
    ...

@nox.session
def docs(session):
    ...

若是你只运行nox --list ，则会看到全部会话都被选中：

Sessions defined in noxfile.py:

* test
* lint
* docs

sessions marked with * are selected,
sessions marked with - are skipped.

若是你运行nox --list --sessions lint，Nox 将只运行 lint 会话：

nox > Running session lint
nox > Creating virtualenv using python3 in .nox/lint
nox > ...
nox > Session lint was successful.

还有更多选择和运行会话的方法！你能够在命令行用法中阅读更多有关调用 Nox 的信息。

针对不一样的多个 Python 进行测试

许多项目须要支持一个特定的 Python 版本或者多个 Python 版本。你能够经过给 @nox.session 指定 Python，来使 Nox 针对多个解释器运行会话。这里有一些例子：

（1）若是你但愿会话仅针对 Python 的单个版本运行：

@nox.session(python="3.7")
def test(session):
    ...

（2）若是你但愿会话在 Python 的多个版本上运行：

@nox.session(python=["2.7", "3.5", "3.7"])
def test(session):
    ...

你会注意到，运行nox --list将显示此会话已扩展为三个不一样的会话：

Sessions defined in noxfile.py:

* test-2.7
* test-3.5
* test-3.7

你可使用nox --sessions test运行全部 test 会话，也可使用列表中显示的全名来运行单个 test 会话，例如，nox --sessions test-3.5。有关选择会话的更多详细信息，请参见命令行用法文档。

你能够在会话的virtualenv配置里，阅读到更多关于配置会话所用的虚拟环境的信息。

与 conda 一块儿测试

一些项目，特别是在数据科学社区，须要在 conda 环境中测试其使用的状况。若是你但愿会话在 conda 环境中运行：

@nox.session(venv_backend="conda")
def test(session):
    ...

使用 conda 安装软件包：

session.conda_install("pytest")

能够用 pip 安装软件包进 conda 环境中，可是最好的实践是仅使用--no-deps 选项安装。这样能够避免 pip 安装的包与 conda 安装的包不兼容，防止 pip 破坏 conda 环境。

session.install("contexter", "--no-deps")
session.install("-e", ".", "--no-deps")

参数化

就像 Nox 能够控制运行多个解释器同样，它也可使用nox.parametrize()装饰器，来处理带有一系列不一样参数的会话。

这是一个简短示例，使用参数化对两个不一样版本的 Django 进行测试：

@nox.session
@nox.parametrize("django", ["1.9", "2.0"])
def test(session, django):
    session.install(f"django=={django}")
    session.run("pytest")

若是运行nox --list ，你将会看到 Nox 把一个会话扩展为了多个会话。每一个会话将得到你想传递给它的一个参数值：

Sessions defined in noxfile.py:

* test(django='1.9')
* test(django='2.0')

nox.parametrize() 的接口和用法特地相似于pytest的parametrize。这是 Nox 的一项极其强大的功能。你能够在参数化会话上，阅读更多有关参数化的信息与示例。

（译注：关于 pytest 和其它主流测试框架是如何使用参数化功能的？请参阅《Python 中如何实现参数化测试？》）

下一步

看看你！你如今基本上是一个 Nox 专家啦！✨

到了这一步，你还能够：

• 阅读更多文档，例如命令行用法和配置＆API。
• 给咱们反馈或做贡献，请参阅贡献。

玩得开心！💜

相关连接：

[1] nox tutorial: https://nox.thea.codes/en/stable/tutorial.html

[2] pip: https://pip.readthedocs.org/

[3] 用户站点: https://packaging.python.org/tutorials/installing-packages/%23installing-to-the-user-site#installing-to-the-user-site

[4] pipx: https://packaging.python.org/guides/installing-stand-alone-command-line-tools/

[5] docker: https://www.docker.com/

[6] thekevjames/nox镜像: https://hub.docker.com/r/thekevjames/nox

[7] GitHub Actions中: https://github.com/features/actions

[8] Activatedleigh/setup-nox action: https://github.com/marketplace/actions/setup-nox

[9] flake8: http://flake8.pycqa.org/en/latest/

[10] 命令行用法: https://nox.thea.codes/en/stable/usage.html

[11] 配置＆API: https://nox.thea.codes/en/stable/config.html

[12] nox.sessions.Session.run(): https://nox.thea.codes/en/stable/config.html%23nox.sessions.Session.run#nox.sessions.Session.run

[13] 会话的virtualenv配置: https://nox.thea.codes/en/stable/config.html%23virtualenv-config#virtualenv-config

[14] nox.parametrize(): https://nox.thea.codes/en/stable/config.html%23nox.parametrize#nox.parametrize

[15] pytest的parametrize: https://pytest.org/latest/parametrize.html%23_pytest.python.Metafunc.parametrize#_pytest.python.Metafunc.parametrize

[16] 参数化会话上: https://nox.thea.codes/en/stable/config.html%23parametrized#parametrized

[17] 贡献: https://nox.thea.codes/en/stable/CONTRIBUTING.html

公众号【Python猫】， 本号连载优质的系列文章，有喵星哲学猫系列、Python进阶系列、好书推荐系列、技术写做、优质英文推荐与翻译等等，欢迎关注哦。