前言:
NoxfileNox 默认在一个名为noxfile.py的文件中查找配置。在运行 nox 时,你可以使用 --noxfile参数指定其它的文件。
定义会话格式:session(func=None, python=None, py=None, reuse_venv=None, name=None, venv_backend=None),将被装饰的函数指定为一个会话。
Nox 会话是通过被@nox.session装饰的标准 Python 函数来配置的。
例如:
import nox @nox.session def tests(session): session.run('pytest')
会话描述你可以使用文档字符串向会话中添加一个描述。第一行内容会在列出会话时显示。
例如:
import nox @nox.session def tests(session): """Run the test suite.""" session.run('pytest')
nox --list命令将显示出:
$ nox --list Available sessions: * tests -> Run the test suite.
会话名称默认情况下,Nox 使用被装饰函数的名称作为会话的名称。这对于绝大多数项目都非常有效,但是,如果需要,你也可以使用 @nox.session 的 name 参数来自定义会话的名称。
例如:
import nox @nox.session(name="custom-name") def a_very_long_function_name(session): print("Hello!")
nox --list 命令将显示:
$ nox --list Available sessions: * custom-name
你可以告诉 nox 使用自定义的名称运行会话:
$ nox --session "custom-name" Hello!
配置会话的virtualenv默认情况下,Nox 在为每个会话创建一个新的 virtualenv 时,会使用 Nox 所用的同一个解释器。如果你使用 Python 3.6 安装了 nox,则 nox 将默认在所有会话中使用 Python 3.6。
通过给 @nox.session 指定 python 参数(或其别名 py),你可以告诉 nox 使用不同的 Python 解释器/版本:
@nox.session(python='2.7') def tests(session): pass
你还可以告诉 Nox 使用多个 Python 解释器运行你的会话。Nox 将为指定的每个解释器创建一个单独的 virtualenv 并运行会话。例如,下面的会话将运行两次——一次使用 Python 2.7,一次使用 Python 3.6:
@nox.session(python=['2.7', '3.6']) def tests(session): pass
当你提供一个版本号时,Nox 会自动添加 python 来确定可执行文件的名称。但是,Nox 也可以接受完整的可执行名称。如果你想使用 pypy 来测试,例如:
@nox.session(python=['2.7', '3.6', 'pypy-6.0']) def tests(session): pass
当准备你的会话时,Nox 将为每个解释器创建单独的会话。你可以在运行 nox --list 的时候看到这些会话。例如这个 Noxfile:
@nox.session(python=['2.7', '3.5', '3.6', '3.7']) def tests(session): pass
将产生这些会话:
* tests-2.7 * tests-3.5 * tests-3.6 * tests-3.7
注意,这个扩展发生在参数化之前,所以你仍然可以对多个解释器的会话进行参数化。
如果你想完全禁止创建 virtualenv,你可以设置 python 参数为 False:
@nox.session(python=False) def tests(session): pass
最后,你还可以指定每次都重用 virtualenv,而不是重新创建:
@nox.session( python=['2.7', '3.6'], reuse_venv=True) def tests(session): pass
将参数传入会话通常往测试会话中传递参数是很有用的。下面是一个简单示例,演示了如何使用参数对特定文件作测试:
@nox.session def test(session): session.install('pytest') if session.posargs: test_files = session.posargs else: test_files = ['test_a.py', 'test_b.py'] session.run('pytest', *test_files)
现在如果你运行:
nox
那么 nox 将运行:
pytest test_a.py test_b.py
但如果你运行:
nox -- test_c.py
那么 nox 将运行:
pytest test_c.py
参数化会话会话的参数可以用nox.parametrize() 装饰器来作参数化。
下面是一个典型的参数化安装 Django 版本的例子:
@nox.session @nox.parametrize('django', ['1.9', '2.0']) def tests(session, django): session.install(f'django=={django}') session.run('pytest')
当你运行nox时,它会创建两个不同的会话:
$ nox nox > Running session tests(django='1.9') nox > pip install django==1.9 ... nox > Running session tests(djano='2.0') nox > pip install django==2.0
nox.parametrize() 的接口和用法故意跟pytest的参数化 相类似。
格式:parametrize(arg_names, arg_values_list, ids=None)
作用是参数化一个会话。
将 arg_values_list 列表赋给对应的 arg_names,为装饰的会话函数添加新的调用。参数化在会话发现期间执行,每次调用都作为 nox 的单个会话出现。
参数:
你也可以堆叠装饰器,令其产生组合了参数的会话,例如:
@nox.session @nox.parametrize('django', ['1.9', '2.0']) @nox.parametrize('database', ['postgres', 'mysql']) def tests(session, django, database): ...
如果运行nox —list,你将看到它生成了以下的会话集:
* tests(database='postgres', django='1.9') * tests(database='mysql', django='1.9') * tests(database='postgres', django='2.0') * tests(database='mysql', django='2.0')
如果你只想运行一个参数化会话,请参阅"指定参数化会话"部分。
为参数化的会话起友好的名称自动生成的参数化会话的名称,如tests(django='1.9', database='postgres'),即使用关键字过滤,也可能很长且很难处理。
在此场景中,可以为参数化会话提供辅助的自定义 id 。
这两个例子是等价的:
@nox.session @nox.parametrize('django', ['1.9', '2.0'], ids=['old', 'new']) def tests(session, django): ... @nox.session @nox.parametrize('django', [ nox.param('1.9', id='old'), nox.param('2.0', id='new'), ]) def tests(session, django): ...
当运行nox --list时,你将看到它们的新 id:
* tests(old) * tests(new)
你可以用nox --sessions "tests(old)",以此类推。
这也适用于堆叠参数化。id 是在组合期间组合的。
例如:
@nox.session @nox.parametrize( 'django', ['1.9', '2.0'], ids=["old", "new"]) @nox.parametrize( 'database', ['postgres', 'mysql'], ids=["psql", "mysql"]) def tests(session, django, database): ...
运行nox --list时会产生这些会话:
* tests(psql, old) * tests(mysql, old) * tests(psql, new) * tests(mysql, new)
会话对象Nox 将使用 Session 类的一个实例来调用你的会话函数。
class Session(runner) :
会话对象被传递到用户自定义的每个会话函数中。
这是在 Nox 会话中安装软件包和运行命令的主要途径。
调用conda install来在会话环境中的安装软件包。
直接安装软件包:
session.conda_install('pandas') session.conda_install('numpy', 'scipy') session.conda_install('--channel=conda-forge', 'dask==2.1.0')
根据 requirements.txt 文件来安装软件包:
session.conda_install('--file', 'requirements.txt') session.conda_install('--file', 'requirements-dev.txt')
不破坏 conda 已安装的依赖而安装软件包:
session.install('.', '--no-deps') # Install in editable mode. session.install('-e', '.', '--no-deps')
剩下的关键字参数跟 run() 相同。
直接安装包:
session.install('pytest') session.install('requests', 'mock') session.install('requests[security]==2.9.1')
根据 requirements.txt 文件来安装软件包:
session.install('-r', 'requirements.txt') session.install('-r', 'requirements-dev.txt')
安装当前的包:
session.install('.') # Install in editable mode. session.install('-e', '.')
剩下的关键字参数跟 run() 相同。
此方法是幂等的;对同一会话的多次通知无效。
参数:target (Union[str, Callable])——需要通知的会话。这可以指定适当的字符串(与nox -s 的使用相同)或使用函数对象。
命令必须安装字符串列表指定,例如:
session.run('pytest', '-k', 'fast', 'tests/') session.run('flake8', '--import-order-style=google')
你不能把所有东西都当作一个字符串传递。例如,不可以这样:session.run('pytest -k fast tests/')
你可以用env 为命令设置环境变量:
session.run( 'bash', '-c', 'echo $SOME_ENV', env={'SOME_ENV': 'Hello'})
你还可以使用success_codes ,告诉 nox 将非零退出码视为成功。例如,如果你想将 pytest 的“tests discovered, but none selected”错误视为成功:
session.run( 'pytest', '-k', 'not slow', success_codes=[0, 5])
在 Windows 上,像del这样的内置命令不能直接调用,但是你可以使用cmd /c 来调用它们:
session.run('cmd', '/c', 'del', 'docs/modules.rst')
参数:
修改 Noxfile 中的 Nox 行为Nox 有各种命令行参数,可用于修改其行为。其中一些还可以在 Noxfile 中使用 nox.options 指定。例如,如果你想将 Nox 的 virtualenvs 存储在不同的目录中,而不需要每次都将它传递给 nox:
import nox nox.options.envdir = ".cache" @nox.session def tests(session): ...
或者,如果你想提供一组默认运行的会话:
import nox nox.options.sessions = ["lint", "tests-3.6"] ...
以下的选项可以在 Noxfile 中指定:
在调用 nox 时,命令行上指定的任何选项都优先于 Noxfile 中指定的选项。如果在命令行上指定了--sessions或--keywords,那么在 Noxfile 中指定的两个选项都将被忽略。