乐趣区

关于python:Python-任务自动化工具nox-的配置与-API

jiezi

Noxfile
Nox 默认在一个名为 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 的单个会话呈现。

参数：

  • arg_names (Sequence[str])——一系列参数名称
  • arg_values_list (Sequence[Union[Any, Tuple]])——参数值列表决定了应用不同参数值调用会话的频率。如果只指定了一个参数名，那么这就是一个简略的值列表，例如[1,2,3]。如果指定了 N 个参数名，这必须是一个 N 元组的列表，其中每个元素为其各自的参数名指定一个值，例如 [(1,’a’), (2,’b’)]。
  • ids (Sequence[str]) ——可选项，一系列测试 id，被参数化的参数应用。

你也能够重叠装璜器，令其产生组合了参数的会话，例如:

@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 会话中装置软件包和运行命令的次要路径。

  • bin¶——virtualenv 的 bin 目录
  • cd(dir)¶——chdir() 的一个别名
  • chdir(dir)¶——更改以后的工作目录
  • conda_install(args, *kwargs)¶

调用 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() 雷同。

  • env¶——一个环境变量的字典，传给所有的命令。
  • error(args, *kwargs)¶——立刻停止会话并随便地记录一个谬误。
  • install(args, *kwargs)¶ ——调用 pip 在会话的 virtualenv 里安装包。

间接安装包：

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() 雷同。

  • interactive¶ ——如果 Nox 在交互式会话中运行，则返回 True，否则返回 False。
  • log(args, *kwargs)¶——在会话期间输入一份日志。
  • notify(target)¶ ——将给定的会话放在队列的开端。

此办法是幂等的；对同一会话的屡次告诉有效。
参数：target (Union[str, Callable])——须要告诉的会话。这能够指定适当的字符串 (与 nox -s 的应用雷同) 或应用函数对象。

  • posargs¶ ——用于设置从命令行上传给 nox 的额定参数。
  • python¶ ——传给 @nox.session 的 Python 版本。
  • run(args, env=None, kwargs)¶ ——运行一个命令。

命令必须装置字符串列表指定，例如：

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')

参数：

  • env (dict or None)——用于向命令公开的环境变量字典。默认状况下，传递所有环境变量。
  • silent (bool) ——静默命令输入，除非命令失败。默认为 False。
  • success_codes (list, tuple, or None)——一系列被认为是胜利的返回码。默认状况下，只有 0 被认为是胜利的。
  • external (bool) ——如果为 False(默认值)，那么不在 virtualenv 门路中的程序将收回告警。如果为 True，则不会收回告警。这些告警能够应用 –error-on-external-run 将其转换为谬误。这对没有 virtualenv 的会话没有影响。
  • skip(args, *kwargs)¶ ——立刻跳出会话，并随便记录一个告警。
  • virtualenv¶ ——运行所有命令的 virtualenv。

批改 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.options.envdir 等同于指定 –envdir.
  • nox.options.sessions 等同于指定 -s or –sessions.
  • nox.options.keywords 等同于指定 -k or –keywords.
  • nox.options.reuse_existing_virtualenvs 等同于指定 –reuse-existing-virtualenvs。通过在调用时指定 –no-reuse-existing-virtualenvs，你能够强制勾销它。
  • nox.options.stop_on_first_error 等同于指定 –stop-on-first-error. 通过在调用时指定 –no-stop-on-first-error，你能够强制勾销它。
  • nox.options.error_on_missing_interpreters 等同于指定 –error-on-missing-interpreters。通过在调用时指定 –no-error-on-missing-interpreters，你能够强制勾销它。
  • nox.options.error_on_external_run 等同于指定 –error-on-external-run. 通过在调用时指定 –no-error-on-external-run，你能够强制勾销它。
  • nox.options.report 等同于指定 –report。

在调用 nox 时，命令行上指定的任何选项都优先于 Noxfile 中指定的选项。如果在命令行上指定了 –sessions 或 –keywords，那么在 Noxfile 中指定的两个选项都将被疏忽。

以上就是本次分享的所有内容，想要理解更多 python 常识欢送返回公众号：Python 编程学习圈，发送“J”即可收费获取，每日干货分享

退出移动版