tox 配置规范

配置发现

目前,TOX支持按以下优先顺序排列的三个配置位置:

  1. pyproject.toml,

  2. tox.ini,

  3. setup.cfg .

就配置格式而言,目前我们只支持标准 ConfigParser “ini-style”格式(计划很快添加一个纯TOML格式)。 tox.inisetup.cfg 都是这样的文件。请注意, setup.cfg 要求内容位于 tox:toxtestenv 节,否则将被忽略。 pyproject.toml 另一方面是TOML格式。但是,您可以内联 ini-style 格式下的格式 tool.tox.legacy_tox_ini 键作为多行字符串。

在下面您可以找到 ini-style 格式,但您可能想略读一些 tox配置和使用示例 首先,请将本页作为参考。

tox 全局设置

全局设置在 tox 部分内容为:

[tox]
minversion = 3.4.0
minversion

定义运行所需的最低TOX版本;如果主机的TOX版本低于此版本,则该工具将创建一个环境,并为其提供满足以下条件的TOX版本 provision_tox_env .

requires(PEP-508一览表)

3.2.0 新版功能.

指定需要与tox安装同时存在的python包,才能启动tox版本(必须 PEP-508 符合)。使用此选项指定插件要求(或的版本 virtualenv -确定默认值 pipsetuptoolswheel TOX环境开始的版本)。如果未指定这些依赖项,则tox将创建 provision_tox_env 这样他们就会感到满意,并将所有调用委托给该环境。

[tox]
requires = tox-pipenv
           setuptools >= 30.0.0
provision_tox_env=.tox(字符串)

3.8.0 新版功能.

用于调配具有内部指定的所有依赖项的TOX的虚拟环境的名称 requiresminversion .

toxworkdir={toxinidir}/.tox(路径)

如果不存在,将创建用于生成其环境的TOX目录。

temp_dir={toxworkdir}/.tmp(路径)

放置TOX临时文件的目录。例如:我们在此目录中为项目包创建硬链接(如果可能,否则创建新副本)。这确保了TOX在并行运行时正常工作(因为每个会话都有自己的项目包副本-例如源代码分发)。

skipsdist=false(TRUE|FALSE)

指示是否执行打包操作的标志。将其设置为 true 当为应用程序而不是库使用TOX时。

setupdir={toxinidir}(路径)

指示打包根文件所在的位置(历史上 setup.py 对于 setuptools )。这将是执行打包时的工作目录。

distdir={toxworkdir}/dist(路径)

打包的源代码分发版应放入的目录。注意,这是在每次打包调用开始时清除的。

sdistsrc={toxworkdir}/dist(路径)

不要构建包,而是使用此路径下可用的最新包。您可以通过命令行标志覆盖它 --installpkg .

distshare={homedir}/.tox/distshare(路径)

要将打包的源代码分发移到的文件夹,则不会在打包调用之间清除此文件夹。关于Jenkins(EXISTS JENKINS_URLHUDSON_URL 环境变量)默认路径为 {{toxworkdir}}/distshare .

envlist(逗号分隔值)

确定符合以下条件的环境列表 tox 将按此顺序对发生的事件进行操作(如果找到任何事件,则不会进行进一步查找):

  • 命令行选项 -eENVLIST

  • 环境变量 TOXENV

  • tox.ini file's envlist

3.4.0 新版功能: 可以通过操作系统环境变量进一步过滤在TOX调用期间运行的哪些TOX环境 TOX_SKIP_ENV 正则表达式(例如 py27.* 方法 不要 评估以关键字开头的环境 py27 )。跳过的环境将记录在第二级详细级别。

skip_missing_interpreters=config(配置 |true| 假)

1.7.2 新版功能.

设置为 true 会强迫 tox 以返回成功,即使缺少某些指定的环境也是如此。这对于某些CI系统或在开发人员盒上运行时非常有用,在开发人员盒上,您可能只安装了所有受支持解释器的子集,但不想因此将构建标记为失败。不出所料,如果在调用时传递,命令行开关始终覆盖此设置。将其设置为 config 表示从配置文件中读取值。

ignore_basepython_conflict=false(TRUE|FALSE)

3.1.0 新版功能.

tox允许通过以下方式设置环境的python版本 basepython 设置。如果没有设置,TOX可以从环境名称设置默认值(例如 py37 暗示Python3.7)。在这一点上,将python版本与环境名称进行匹配已成为意料之中的事情,当某些配置不这样做时,这会导致意外。为了帮助用户保持理智,只要环境名称版本与预期不符,就会发出警告。在未来的TOX版本中,此警告将成为错误。

此外,通过将此标志设置为,我们允许硬实施此规则(并绕过警告 true 。在这种情况下,我们忽略 basepython 而是始终使用从Python名称隐含的基本Python。这允许您配置 basepython 而不会影响具有隐含的基本python版本的环境。

isolated_build=false(TRUE|FALSE)

3.3.0 新版功能.

激活隔离生成环境。TOX将使用虚拟环境从源代码树构建源代码分发。对于生成工具和参数,请使用 pyproject.toml 中指定的文件 PEP-517PEP-518 。要指定虚拟环境Python版本定义,请使用 isolated_build_env 配置节。

isolated_build_env=.package(字符串)

3.3.0 新版功能.

用于从源树创建源分发的虚拟环境的名称。

Jenkins覆盖

可以重写 Jenkins 实例(检测是通过检查 JENKINS_URL 环境变量)通过使用 tox:jenkins 章节:

[tox:jenkins]
commands = ...  # override settings for the jenkins context

tox 环境

测试环境在 testenv 部门和个人 testenv:NAME 横断面,其中 NAME 是特定环境的名称。

[testenv]
commands = ...

[testenv:NAME]
commands = ...

在顶层定义的设置 testenv 节由各个环境自动继承,除非被覆盖。测试环境名称可以由字母数字字符和短划线组成,例如: py38-django30 。名称将在短划线上拆分成多个因子,意思是 py38-django30 将分为两个因素: py38django30 . tox 定义了许多默认因子,这些因子对应于Python的各种版本和实现,并为 basepython

  • pyNM: configures basepython = pythonN.M

  • pyN: configures basepython = pythonN

  • py: configures basepython = python

  • pypyN: configures basepython = pypyN

  • pypy: configures basepython = pypy

  • jythonN: configures basepython = jythonN

  • jython: configures basepython = jython

It is also possible to define what's know as generative names, where an individual section maps to multiple environments. For example, py{37,38}-django{30,31} would generate four environments, each consisting of two factors: py37-django30 (py37, django30), py37-django31 (py37, django31), py38-django30 (py38, django30), and py38-django31 (py38, django31). Combined, these features provide the ability to write very concise tox.ini files. This is discussed further in below.

tox 环境设置

可以放入的完整设置列表 testenv* 章节:

basepython(名称或路径)

将用于创建虚拟环境的Python解释器的名称或路径,这实际上决定了我们将创建虚拟隔离环境的Python。使用此选项可以指定tox环境的python版本。如果未指定,将使用虚拟环境因素(例如名称部分)自动设置一个。例如, py37 方法 python3.7py3 方法 python3py 方法 python . provision_tox_env 环境不会从 toxenv 部分。

在 3.1 版更改: 解析此值后,如果解释器报告的版本号与名称中隐含的版本号不同,则默认情况下将打印一条警告。但是,如果 ignore_basepython_conflict 则忽略该值,并且我们强制 basepython 从因子名称中隐含。

commands(ARGVLIST)

要调用进行测试的命令。仅在以下情况下执行 commands_pre 成功。

每行都解释为一个命令;但是,可以通过以行结尾来将命令拆分到多行 \ 性格。

命令将以顺序方式逐个执行,直到其中一个失败(其退出代码为非零)或所有命令都成功。通过在命令前面加上破折号,可以忽略命令的退出代码(意味着它们始终被认为是成功的 (- )-这类似于如何 make 菜谱行得通。只有当所有命令(这些+SETUP+TEARDOWN)都成功时(通过忽略退出代码),环境的结果才被认为是成功的 - 或成功退出码值为零)。

笔记

虚拟环境二进制路径( bin 文件夹)被放在操作系统的前面 PATH ,这意味着命令将首先尝试从虚拟环境内部解析为可执行文件,并且只有在虚拟环境外部才会尝试解析为可执行文件。因此, python 翻译为虚拟环境 python (具有与 basepythonpip 翻译为虚拟环境 pip .

commands_pre(ARGVLIST)

3.4 新版功能.

在运行之前要运行的命令 commands 。所有评估和配置逻辑均适用于 commands .

commands_post(ARGVLIST)

3.4 新版功能.

运行后要运行的命令 commands 。执行,而不考虑两者的结果 commandscommands_pre 。所有评估和配置逻辑均适用于 commands .

install_command=python -m pip install {opts} {packages}(ARGV)

1.6 新版功能.

确定用于将软件包安装到虚拟环境中的命令;测试中的软件包及其依赖项(使用定义 deps )。必须包含替换密钥 {{packages}} 它将被要安装的程序包替换。你也应该接受 {{opts}} 如果您使用的是pip--它将包含索引服务器选项,如 --pre (配置为 pip_pre )和潜在的索引选项(来自已弃用的 indexserver 选择权。

list_dependencies_command=python -m pip freeze(ARGV)

2.4 新版功能.

这个 list_dependencies_command 设置用于列出安装到虚拟环境中的软件包。

ignore_errors=false(TRUE|FALSE)

2.0 新版功能.

如果 false ,则一个命令的非零退出代码将中止该环境的命令执行。如果 true ,则一个命令的非零退出代码将被忽略,并将执行其他命令。总体状态将是“命令失败”,也就是说,如果任何命令失败,TOX将退出非零状态。

请注意,此设置类似于 -k--keep-going GNU make选项。

请注意,在TOX 2.0中,与处理来自命令的错误相关的TOX的默认行为发生了变化。默认情况下,TOX<2.0会忽略错误。默认情况下,tox>=2.0将在出现错误时中止,这在CI和命令执行工具中更安全、更典型,因为如果安装某些必备组件失败,则运行测试没有意义,如果测试失败,则尝试部署也没有意义。

pip_pre=false(TRUE|FALSE)

1.9 新版功能.

如果 true ,添加 --preopts 传递给 install_command .如果 install_command 使用pip,这将导致它安装没有指定版本的任何依赖项的最新可用预发布。如果 false ,pip将仅安装未固定依赖项的最终版本。

路过 --pre tox的命令行选项将强制执行此操作 true 对所有的提斯腾夫人来说。

如果您的 install_command 不使用pip。

allowlist_externals(多行列表)

3.18 新版功能.

每一行都指定一个命令名(采用glob样式模式格式),该命令名可在 commands 部分,而不触发“未安装在Virtualenv中”警告。示例:如果您使用Unix make 对于运行测试,您可以列出 allowlist_externals=makeallowlist_externals=/usr/bin/make 如果你想要更精确的话。如果您不想在任何情况下使用tox发出警告,只需使用 allowlist_externals=* 它将与所有命令匹配(不推荐)。

注解

whitelist_externals 与具有相同的含义和用法 allowlist_externals 但它现在已被弃用。

changedir={toxinidir}(路径)

执行测试命令时切换到此工作目录。

注解

如果该目录尚不存在,则会创建该目录。

deps(多行列表)

环境依赖项-安装到环境中(请参见 install_command )在环境创建之后的项目之前。每行一个依赖项(文件、URL或包名)。一定是 PEP-508 顺从的。所有安装程序命令都使用 toxinidir 作为当前工作目录。

[testenv]
deps =
    pytest
    pytest-cov >= 3.5
    pywin32 >=1.0 ; sys_platform == 'win32'
    octomachinery==0.0.13  # pyup: < 0.1.0 # disable feature updates

在 2.3 版更改.

现在不建议使用索引服务器,也不鼓励使用索引服务器。

在 3.9 版更改.

在与依赖项相同的行上注释支持。将内容提供给安装工具时,我们将从第一个注释标记中剥离内容(包括 (# )前面有一个或多个空格。例如,如果依赖项是 octomachinery==0.0.13  # pyup: < 0.1.0 # disable feature updates 它将会变成公正的 octomachinery==0.0.13 .

platform(REGEX)

2.0 新版功能.

Testenv可以定义一个新的 platform 设置为正则表达式。如果定义了非空表达式,并且该表达式与 sys.platform string将跳过整个测试环境,并且不会执行任何命令。正在运行 tox -e <platform_name> 将针对特定平台运行命令并跳过睡觉。

setenv(多行列表)

0.9 新版功能.

每行都包含一个name=value环境变量设置,它将用于所有测试命令调用以及将sdist包安装到虚拟环境中。

请注意,在更新PATH变量时,可以考虑使用变量替换当前值并处理路径分隔符。

[testenv]
setenv   =
    PYTHONPATH = {env:PYTHONPATH}{:}{toxinidir}

3.20 新版功能.

支持评论。以以下字符开头的行 # 被忽略。

支持环境文件。以 file| 包含要加载的环境文件的路径。环境文件中的规则与 setenv (相同的更换和注释支持)。

passenv(空格分隔-全局名称)

2.0 新版功能.

执行测试命令时应从tox调用环境复制到测试环境的通配符环境变量名列表。如果指定的环境变量在tox调用环境中不存在,它将被忽略。您可以使用 *? 将多个环境变量与一个名称匹配。环境变量名列表不区分大小写,所有大小写匹配的变量都将被传递。例如,传递 A 都会通过 Aa .

始终传递一些变量以确保标准库函数或工具(如pip)的基本功能:

  • 在所有平台上通过: CURL_CA_BUNDLEPATHLANGLANGUAGELD_LIBRARY_PATHPIP_INDEX_URLPIP_EXTRA_INDEX_URLREQUESTS_CA_BUNDLESSL_CERT_FILEHTTP_PROXYHTTPS_PROXYNO_PROXY

  • 窗户: SYSTEMDRIVESYSTEMROOTPATHEXTTEMPTMP

    NUMBER_OF_PROCESSORS, USERPROFILE, MSYSTEM

  • 其他(例如UNIX、MacOS): TMPDIR

属性覆盖这些变量。 setenv 选择权。

如果定义了 TOX_TESTENV_PASSENV 环境变量(在tox调用环境中)可以定义其他空格分隔的变量名,这些变量名将传递给测试命令环境。

在 2.7 版更改: PYTHONPATH 如果显式定义,将传递给下一代。如果 PYTHONPATH 存在于主机环境中,但 not 声明于 passenv 将发出警告。

recreate=false(TRUE|FALSE)

如果此选项为true,请始终重新创建虚拟环境。如果此选项为FALSE, tox 的解决机制将用于确定是否重新创建环境。

downloadcache(路径)

IGNORED --由于pip-8在默认情况下具有缓存,因此现在忽略此选项。请将其从您的配置中删除,因为将来的 tox 版本可能会在其上发出声音。

sitepackages=false(TRUE|FALSE)

设置为 true 如果您想要创建也可以访问全局安装的软件包的虚拟环境。

警告

如果命令行工具也是全局安装的,则必须确保使用安装在viralenv中的工具,方法是使用 python -m <command line tool> (如果该工具支持)或 {{envbindir}}/<command line tool> .

如果您忘记这样做,您将收到如下警告::

WARNING: test command found but not installed in testenv
    cmd: /path/to/parent/interpreter/bin/<some command>
    env: /foo/bar/.tox/python
Maybe you forgot to specify a dependency? See also the allowlist_externals envconfig setting.
alwayscopy=false(TRUE|FALSE)

设置为 true 如果您希望viralenv始终复制文件而不是符号链接。

这在硬链接不起作用的情况下很有用(例如,使用Windows来宾在VMS中运行)。

download=false(TRUE|FALSE)

3.10 新版功能.

设置为 true 如果您希望viralenv将pip/round/setuptools升级到最新版本。如果(且仅当)您想要选择特定版本(不一定是最新版本),则可以添加例如 VIRTUALENV_PIP=20.3.3 敬你的setenv。

args_are_paths=true(TRUE|FALSE)

处理传递给的位置参数 tox 作为文件系统路径,并且-如果它们存在于文件系统上-根据 changedir 。由于文件系统上存在检查,默认值为true,尝试重写通常是安全的。

envtmpdir={envdir}/tmp(路径)

为viralenv定义一个临时目录,该目录将在每次调用测试命令组之前清除。

envlogdir={envdir}/log(路径)

定义用于记录的目录,tox将在该目录中放置工具调用的日志。

indexserver(URL)

0.9 新版功能.

(已弃用,将在未来版本中删除)多行 name = URL Python包服务器的定义。依赖项可以指定使用指定的索引服务器(通过 :indexservername:depname 图案。这个 default indexserver定义确定未限定作用域的依赖项和sdist安装的安装位置。示例:

[tox]
indexserver =
    default = https://mypypi.org

将使tox从此PyPI索引服务器安装所有依赖项(包括安装项目sdist包时)。

envdir={toxworkdir}/{envname}(路径)

1.5 新版功能.

用户可以设置环境的具体路径。如果路径不是绝对路径,它将被视为相对于 {{toxinidir}} .

usedevelop=false(TRUE|FALSE)

1.6 新版功能.

在开发模式下使用“setup.py developer”安装当前软件包,而不是从 sdist 包裹。(这使用pip的 -e 选项,因此如果您指定了自定义 install_command 这不支持 -e

skip_install=false(TRUE|FALSE)

1.9 新版功能.

请勿安装当前软件包。当您需要Virtualenv管理,但不想将当前软件包安装到该环境中时,可以使用此功能。

ignore_outcome=false(TRUE|FALSE)

2.2 新版功能.

如果设置为TRUE,则此测试的失败结果不会导致 tox 测试失败,只会产生警告。

extras(多行列表)

2.4 新版功能.

要随sdist或developer安装一起安装的“附加”列表。例如, extras = testing 等于 [testing] 在一个 pip install 指挥部。如果出现以下情况,则不会安装这些组件 skip_installtrue .

description=no description(单行文本)

环境的简短描述,这将用于在列出任何详细级别高于零的命令行的环境时向用户解释环境。

parallel_show_output=false(布尔)

3.7.0 新版功能.

如果设置为True,则在并行模式下运行时将始终显示输出内容。

depends(逗号分隔值)

3.7.0 新版功能.

这取决于tox环境。在运行此环境之前,TOX将尝试运行所有相关环境。格式与 envlist (允许使用因子)。

警告

depends 不会将依赖项拉入到运行目标中,例如,如果您选择 py27,py36,coverage 通过 -e tox检测只能检测这三个(即使 coverage 可指定为 depends 其他目标也是如此-例如 py27, py35, py36, py37

suicide_timeout=0.0(浮动)

3.15.2 新版功能.

当通过Ctrl+C发送中断时,SIGINT被发送到所有前台进程。这个 :conf:``suicide_timeout` `在收到(某些情况下是重复的)来自tox的SIGINT之前,给正在运行的进程提供清理和退出的时间。

interrupt_timeout=0.3(浮动)

3.15.0 新版功能.

当tox被中断时,它将信号传播到子进程 :conf:``suicide_timeout` 秒。如果进程在以下情况下仍未退出 :conf:``interrupt_timeout `秒,则其发送SIGTERM。

terminate_timeout=0.2(浮动)

3.15.0 新版功能.

当tox中断时,在等待之后 :conf:``interrupt_timeout` 秒,它将信号传播到子进程,等待 :conf:``interrupt_timeout 秒,向其发送SIGTERM,等待 :conf:``terminate_timeout `秒,如果它还没有退出,则向它发送SIGKILL。

替代品

任何 key=value 在ini文件中的设置可以通过 {{...}} 字符串替换模式。

属性可以省略大括号。 \ 字符(如果需要),例如::

commands = echo "\{posargs\}" = {posargs}

请注意一些替换(例如 posargs, env) may have addition values attached to it, via the : character (e.g. `` Poargs``-默认值, env - key). Such substitutions cannot have a space after the : character (e.g. `` {posargs:Magic}``位于ini配置内的行首(这将被解析为阶乘 {{posargs ,具有价值魔力)。

全球可用的替代

{toxinidir}

所在的目录 tox.ini 位于

{toxworkdir}

创建虚拟环境的目录和用于打包的子目录所在的目录。

{homedir}

用户主目录路径。

{distdir}

将在其中创建sdist软件包的目录

{distshare}

(已弃用)sdist软件包将复制到的目录,以便其他进程或tox运行可以访问它们。

{:}

特定于操作系统的路径分隔符 (: 在尼克斯家族上, ; 在Windows上)。可用于 setenv ,当目标变量为PATH变量时(例如PATH或PYTHONPATH)。

{/}

操作系统特定的目录分隔符 (/ 在尼克斯家族上, \\ 在Windows上)。用于从预设路径派生文件名,作为需要 \\ 在Windows上。例如: {{distdir}}{{/}}file.txt 。当使用用Python编写的命令时,通常不需要它。

环境变量替换

如果您指定如下替换字符串::

{env:KEY}

则该值将被检索为 os.environ['KEY'] 如果环境变量不存在,则引发错误。

使用默认值替换环境变量

如果您指定如下替换字符串::

{env:KEY:DEFAULTVALUE}

则该值将被检索为 os.environ['KEY'] 如果环境变量不存在,则替换为DEFAULTVALUE。

如果您指定如下替换字符串::

{env:KEY:}

则该值将被检索为 os.environ['KEY'] 如果环境变量不存在,则替换为空字符串。

替换也可以嵌套。在这种情况下,它们从最里面的表达式开始展开::

{env:KEY:{env:DEFAULT_OF_KEY}}

上面的示例大致相当于 os.environ.get('KEY', os.environ['DEFAULT_OF_KEY'])

交互式外壳替换

只有当tox在交互式shell(标准输入)中运行时,才可以注入配置值::

{tty:ON_VALUE:OFF_VALUE}

第一个值是当交互式终端可用时要注入的值,第二个值是当交互式终端不可用时要使用的值。后者是可选的。这样做的一个很好的用例是,例如,将 --pdb 最热的旗帜。

命令中位置参数的替换

1.0 新版功能.

如果您指定如下替换字符串::

{posargs:DEFAULTS}

然后,该值将被提供给tox命令的位置参数替换:

tox arg1 arg2

在本例中,位置参数部分将替换为 arg1 arg2 。如果未指定位置参数,则将使用默认值的值。如果DEFAULTS包含其他替换字符串,如 {{env:*}} ,它们将被解释。,

使用替身 -- 如果您还想将选项传递给基础测试命令,例如::

tox -- --opt1 ARG1

将使 --opt1 ARG1 出现在所有测试命令中,其中 []{{posargs}} 已指定。缺省情况下(请参见 args_are_paths 设置), tox 如果每个位置参数是相对路径并且存在于文件系统上,则将其重写为相对于 changedir 设置。

以前版本的tox支持 [.*] 使用默认值表示位置参数的模式。此格式已弃用。使用 {{posargs:DEFAULTS}} 来指定那些。

替换其他节中的值

1.4 新版功能.

其他部分的值可以通过以下方式引用:

{[sectionname]valuename}

您可以使用它来避免重复的配置值。您可以将默认值放在一个节中,然后在其他节中引用它们,以避免重复相同的值:

[base]
deps =
    pytest
    mock
    pytest-xdist

[testenv:dulwich]
deps =
    dulwich
    {[base]deps}

[testenv:mercurial]
deps =
    mercurial
    {[base]deps}

生成环境,条件设置

1.8 新版功能.

假设您想要针对python2.7、python3.6以及依赖项的几个版本(比如Django 1.5和Django 1.6)测试包。你可以写下2个字就可以做到这一点。 2 = 4 ``[testenv: ]``节,然后在 envlist .

但是,更好的方法如下所示:

[tox]
envlist = {py27,py36}-django{15,16}

[testenv]
deps =
    pytest
    django15: Django>=1.5,<1.6
    django16: Django>=1.6,<1.7
    py36: unittest2
commands = pytest

这使用了两个新的TOX-1.8设备:

  • 生成性环境列表声明,其中每个环境名称由环境部分或“因素”组成

  • “因素”特定设置

让我们一步一步地来看这个。

生成性环境列表

envlist = {py36,py27}-django{15,16}

这是bash样式的语法,将创建 2*2=4 类似于以下内容的环境名称::

py27-django15
py27-django16
py36-django15
py36-django16

您仍然可以将环境与生成的环境一起显式列出:

envlist = {py27,py36}-django{15,16}, docs, flake

请记住,内空格字符(换行符除外) {{}} 被剥离,因此以下行定义了相同的环境名称:

envlist = {py27,py36}-django{ 15, 16 }, docs, flake

注解

为了帮助理解变量将如何生成分段值,您可以要求tox使用一个新选项显示它们的扩展::

$ tox -l
py27-django15
py27-django16
py36-django15
py36-django16
docs
flake

生成节名

3.15 新版功能.

使用类似的语法,可以生成节::

[testenv:py{27,36}-flake]

这等效于定义不同的部分:

$ tox -a
py27-flake
py36-flake

当您需要与默认环境不同的环境,但仍希望利用因子条件设置时,它非常有用。

因素和因素条件设置

如前所述,由连字符分隔的环境名称部分称为因子,可用于有条件地设置值。在列表设置中,如 depscommands 您可以自由混合可选行和无条件行:

[testenv]
deps =
    pytest
    django15: Django>=1.5,<1.6
    django16: Django>=1.6,<1.7
    py36: unittest2

逐行阅读:

  • pytest 将无条件地包括在内,

  • Django>=1.5,<1.6 将包括在包含以下内容的环境中 django15 因素,

  • Django>=1.6,<1.7 同样依赖于 django16 因素,

  • unittest2 将为Python 3.6环境加载。

TOX提供了许多与Python解释器版本相对应的默认因子。上面的条件设置将导致 python3.6python2.7 用作基本 Python ,例如 python3.6 如果当前环境包含 py36 因素。

注解

配置 basepython 对于使用默认因子的环境,将导致警告。配置 ignore_basepython_conflict 如果您希望显式忽略这些冲突,则允许您定义全局 basepython 适用于所有环境 除了 那些有违约因素的人。

复杂因素条件

有时,您需要为几个因素指定同一行,或者为多个因素的组合创建特殊情况。下面是你是如何做到这一点的:

[tox]
envlist = py{27,34,36}-django{15,16}-{sqlite,mysql}

[testenv]
deps =
    py34-mysql: PyMySQL     # use if both py34 and mysql are in the env name
    py27,py36: urllib3      # use if either py36 or py27 are in the env name
    py{27,36}-sqlite: mock  # mocking sqlite in python 2.x & 3.6
    !py34-sqlite: mock      # mocking sqlite, except in python 3.4
    sqlite-!py34: mock      # (same as the line above)
    !py34-!py36: enum34     # use if neither py34 nor py36 are in the env name

先看一下第一个 deps 排队。它展示了如何通过将组合因子连接在一起,来为组合因子特例。此特定行声明 PyMySQL 将为Python 3.4、MySQL环境加载,例如 py34-django15-mysqlpy34-django16-mysql .

第二行显示了如何对几个因素使用相同的设置-通过用逗号分隔列出它们。不仅可以列出简单的因素,还可以列出它们的组合,如 py27-sqlite,py36-sqlite .

其余的行都具有相同的效果,并且使用条件相当于 py27-sqlite,py36-sqlite 。添加它们只是为了帮助演示以下内容:

  • 因子表达式如何以与envlist中相同的方式展开

  • 如何通过在否定因子前面加上前缀来使用否定因子条件 !

  • 将各因子连在一起的顺序无关紧要

注解

因子不会根据环境名称进行子字符串匹配,而是每个带连字符的表达式都被拆分为 - 如果它的所有非否定因素,并且没有一个它的否定因素也是环境的因素,则该条件被认为对该环境成立。

例如,环境 py36-mysql-!dev

  • 将由表达式匹配 py36py36-mysqlmysql-py36

  • 但不是 py2py36-sqlpy36-mysql-dev .

因子和值替换是兼容的

可以将值替换和因子表达式混合使用。例如::

[tox]
envlist = py27,py36,coverage

[testenv]
deps =
    flake8
    coverage: coverage

[testenv:py27]
deps =
    {[testenv]deps}
    pytest

使用以前的配置,它将安装:

  • flake8pytest 用于以下项目的包 py27 环境。

  • flake8 用于以下项目的包 py36 环境。

  • flake8coverage 用于以下项目的包 coverage 环境。

高级设置

处理长度较长的解释器指令

对于支持可执行文本文件(带有分隔符的脚本)的系统,系统将尝试解析解释器指令,以确定要在目标文本文件上执行的程序。什么时候 tox 在文件容器中准备虚拟环境,该文件容器具有较大的长度(e.x。使用Jenkins管道),系统可能无法调用定义超出系统限制的解释器的Shebang脚本(e.x。Linux限制为128个; BINPRM_BUF_SIZE )。若要解决受解释器指令限制的环境,用户可以通过定义 TOX_LIMITED_SHEBANG 调用前的环境变量 tox ::

export TOX_LIMITED_SHEBANG=1

启用解决方法后,所有由tox调用的文本文件可执行文件都将由其解释器指令解析并显式执行 tox .

注入的环境变量

TOX将注入以下环境变量,您可以使用这些变量来测试您的命令是否在TOX内运行:

3.4 新版功能.

  • TOX_WORK_DIR env var设置为tox工作目录

  • TOX_ENV_NAME 设置为当前运行的tox环境名称。

  • TOX_ENV_DIR 设置为当前的 tox 环境工作目录。

  • TOX_PACKAGE 打包阶段结果路径(对于检查和断言构建的包本身很有用)。

  • TOX_PARALLEL_ENV 设置为当前运行的TOX环境名称,仅当在并行模式下运行时。

笔记

这适用于所有tox env(也是隔离打包)和所有调用的外部命令(例如install命令-pip)。

其他规则及备注

  • path 规格:如果指定了 path 是相对路径,它将被视为相对于 toxinidir ,配置文件所在的目录。

CLI

tox

tox 选项

usage: tox [--version] [-h] [--help-ini] [-v] [-q] [--showconfig] [-l] [-a] [-c CONFIGFILE] [-e envlist] [--devenv ENVDIR] [--notest] [--sdistonly] [--skip-pkg-install] [-p [VAL]] [-o]
           [--parallel--safe-build] [--installpkg PATH] [--develop] [-i URL] [--pre] [-r] [--result-json PATH] [--discover PATH [PATH ...]] [--hashseed SEED] [--force-dep REQ]
           [--sitepackages] [--alwayscopy] [-s [val]] [--workdir PATH]
           [args [args ...]]
args

可用于命令位置替换的其他参数

--version

向标准输出报告版本信息。

-h, --help

显示有关选项的帮助

--help-ini, --hi

显示有关ini-name的帮助

-v, --verbose

增加报告输出的详细程度。-vv模式关闭软件包安装的输出重定向,高于级别2的详细程度标志将传递给pip(少了两个级别)。

-q, --quiet

逐渐静默报告输出。

--showconfig

显示实时配置(默认情况下为所有环境,仅有-l默认目标,具体通过TOXENV/-e)

-l, --listenvs

显示测试环境列表(如果详细,请提供说明)

-a, --listenvs-all

显示所有已定义环境的列表(如果详细,请提供说明)

-c <configfile>

包含‘tox.ini’文件的配置文件名或目录。

-e <envlist>

针对指定环境工作(全部选择全部)。

--devenv <envdir>

根据由指定的环境的TOX配置在ENVDIR中设置开发环境 -e (-e默认为py)。

--notest

跳过调用测试命令。

--sdistonly

仅执行sdist打包活动。

--skip-pkg-install

跳过此运行的包安装

-p <val>, --parallel <val>

并行运行tox环境,参数控制限制:ALL、AUTO或MISSING参数-CPU计数,某个正数,0关闭

-o, --parallel-live

在运行环境时连接到标准输出

--parallel--safe-build

(已弃用)确保两个tox版本可以并行运行(使用tox工作目录中扩展名为.lock的锁定文件)

--installpkg <path>

使用指定的软件包安装到venv中,而不是创建sdist。

--develop

通过‘pip-e’使用‘setup.py developer’在venv中安装软件包。

-i <url>, --index-url <url>

设置indexserver url(如果URL的格式为name=url,请专门设置‘name’indexserver的url)

--pre

安装依赖项的预发布和开发版本。这将把--pre选项传递给install_command(默认情况下是pip)。

-r, --recreate

强制重新创建虚拟环境

--result-json <path>

编写一个json文件,其中包含有关所有命令和结果的详细信息。

--discover <path>

对于python发现,首先尝试以下路径下的python可执行文件

--hashseed <seed>

在运行命令之前,将PYTHONHASHSEED设置为种子。默认为范围内的随机整数 [1,4294967295] ( [11024] 在Windows上)。传递“noset”会抑制此行为。

--force-dep <req>

在配置虚拟环境时强制其中一个依赖项的特定版本。请求示例‘pytest<2.7’或‘Django>=1.6’。

--sitepackages

在所有环境中将Sitepackages设置覆盖为True

--alwayscopy

在所有环境中将始终检查设置覆盖为True

-s, --skip-missing-interpreters

不要通过缺少解释器的测试:{config,true,false}选项

--workdir <path>

tox 工作目录