tox插件

2.0 新版功能.

越来越多的钩子通过编写插件使TOX可以在执行的不同阶段进行修改。

类tox pytestdevpi -用途 pluggy 为pip可安装的内部插件或devpi/pyPI发布的插件提供扩展机制。

使用插件

要开始使用插件,您需要将其安装在安装TOX主机的同一环境中。

例如。:

$ pip install tox-travis

您可以通过键入以下命令在PyPI上搜索可用的插件 pip search tox 对于带有前缀的包裹,则为过滤 tox- 或者在描述中包含单词“plugin”。您将得到类似以下内容的输出::

tox-pipenv (1.4.1)                   - A pipenv plugin for tox
tox-pyenv (1.1.0)                    - tox plugin that makes tox use ``pyenv which`` to find
                                       python executables
tox-globinterpreter (0.3)            - tox plugin to allow specification of interpreter
                                       locationspaths to use
tox-venv (0.2.0)                     - Use python3 venvs for python3 tox testenvs
tox-cmake (0.1.1)                    - Build CMake projects using tox
tox-tags (0.2.0)                     - Allows running subsets of environments based on tags
tox-travis (0.10)                    - Seamless integration of tox into Travis CI
tox-py-backwards (0.1)               - tox plugin for py-backwards
tox-pytest-summary (0.1.2)           - tox + Py.test summary
tox-envreport (0.2.0)                - A tox-plugin to document the setup of used virtual
                                       environments.
tox-no-internet (0.1.0)              - Workarounds for using tox with no internet connection
tox-virtualenv-no-download (1.0.2)   - Disable virtualenv's download-by-default in tox
tox-run-command (0.4)                - tox plugin to run arbitrary commands in a virtualenv
tox-pip-extensions (1.2.1)           - Augment tox with different installation methods via
                                       progressive enhancement.
tox-run-before (0.1)                 - tox plugin to run shell commands before the test
                                       environments are created.
tox-docker (1.0.0)                   - Launch a docker instance around test runs
tox-bitbucket-status (1.0)           - Update bitbucket status for each env
tox-pipenv-install (1.0.3)           - Install packages from Pipfile

可能还有一些插件还不能从PyPI获得,可以直接从Github或Bitbucket等源主机安装(或者从本地克隆)。请参阅相关的 pip documentation .

要查看已安装的内容,您可以拨打 tox --version 要获取主机的版本以及所有已安装插件的名称和位置,请执行以下操作:

3.0.0 imported from /home/ob/.virtualenvs/tmp/lib/python3.6/site-packages/tox/__init__.py
registered plugins:
    tox-travis-0.10 at /home/ob/.virtualenvs/tmp/lib/python3.6/site-packages/tox_travis/hooks.py

创建插件

从模板开始

你可以创建一个新的tox插件,所有的花哨都可以通过 Cookiecutter 模板(请参见 cookiecutter-tox-plugin -这将创建一个完整的、具有许可证、文档和配置项的PyPI可发布、有文档记录的项目。

$ pip install -U cookiecutter
$ cookiecutter gh:tox-dev/cookiecutter-tox-plugin

教程:一个最小的tox插件

注解

这是演示拥有一个内部使用的工作插件所绝对需要的最小实现。要从这样的插件转移到可发布的插件,您可以应用 cookiecutter -f cookiecutter-tox-plugin 并使代码适应在cookiecuter中使用的基于包的结构。

让我们考虑一下,您想要通过在一次成功的 tox 运行结束时显示焰火来扩展 tox 行为(不过,我们不会深入讨论如何显示焰火的细节)。

要创建工作插件,您至少需要一个具有tox入口点的python项目和一个实现tox指定的一个或多个基于插件的挂钩的python模块(使用 @tox.hookimpl 装饰者作为标记)。

最小结构:

$ mkdir tox-fireworks
$ cd tox-fireworks
$ touch tox_fireworks.py
$ touch setup.py

内容 tox_fireworks.py

import pluggy

hookimpl = pluggy.HookimplMarker("tox")


@hookimpl
def tox_addoption(parser):
    """Add command line option to display fireworks on request."""


@hookimpl
def tox_configure(config):
    """Post process config after parsing."""


@hookimpl
def tox_runenvreport(config):
    """Display fireworks if all was fine and requested."""

注解

钩子规范及相关接口 详情

setup.py 内容:

from setuptools import setup

setup(
    name="tox-fireworks",
    py_modules=["tox_fireworks"],
    entry_points={"tox": ["fireworks = tox_fireworks"]},
    classifiers=["Framework:: tox"],
)

使用 tox- 前缀在 tox-fireworks 这是一个既定的约定,能够从项目名称中看出这是一个用于TOX的插件。它还使查找变得更容易,例如 pip search 'tox-' 一旦它在PyPI上发布。

要使您的新插件可以被tox发现,您需要安装它。在开发过程中,您应该使用 -e--editable ,以便对代码的更改立即生效:

$ pip install -e </path/to/tox-fireworks>

将您的插件发布到PyPI

如果你认为世界上的睡觉可以通过你的插件获利,你可以把它发布到PyPI。

您需要向添加更多元数据 setup.py (见 cookiecutter-tox-plugin 有关完整示例,请参阅 setup.py docs

注解

确保您的插件项目名称前缀为 tox- 很容易通过例如 pip search tox-

您可以按如下方式发布它:

$ cd </path/to/tox-fireworks>
$ python setup.py sdist bdist_wheel upload

注解

您还可以使用 twine 用于安全上传。

有关打包和部署Python项目的更多信息,请参见 Python Packaging Guide .

钩子规范及相关接口

tox挂钩规范-请参阅https://pluggy.readthedocs.io/

tox.hookspecs.tox_addoption(parser)[源代码]

向argparse风格的解析器对象添加命令行选项。

tox.hookspecs.tox_cleanup(session)[源代码]

恰好在销毁会话之前调用,从而允许任何最终清理操作

tox.hookspecs.tox_configure(config)[源代码]

在解析命令行选项并读取ini-file之后调用。

请注意,配置对象布局可能会在主要TOX版本之间发生变化。

tox.hookspecs.tox_get_python_executable(envconfig)[源代码]

返回给定python基名的python可执行文件。

第一个返回可执行路径的插件/钩子将确定它。

envconfig 是Testenv配置,它包含每个Testenv配置,特别是 .envname.basepython 设置。

tox.hookspecs.tox_package(session, venv)[源代码]

返回要为给定venv安装的软件包。

为每个环境调用一次。

tox.hookspecs.tox_runenvreport(venv, action)[源代码]

获取此venv中已安装的软件包和版本。

这可以用于替代(即非pip)包管理器,这个插件应该返回一个 list 类型的 str

tox.hookspecs.tox_runtest(venv, redirect)[源代码]

做一下这个房间的测试。

注解

此挂钩使用 firstresult=True (见 pluggy first result only )--实现此操作的挂钩将一直运行,直到返回非``无`为止。

tox.hookspecs.tox_runtest_post(venv)[源代码]

在为此venv运行测试后执行任意操作。

这可用于对通过/失败状态进行每分钟测试报告。

tox.hookspecs.tox_runtest_pre(venv)[源代码]

在为此venv运行测试之前执行任意操作。

例如,这可以用来指示给定venv的测试已经开始。

tox.hookspecs.tox_testenv_create(venv, action)[源代码]

执行此venv的创建操作。

一些用法示例:

  • add 行为,但仍使用tox的实现来设置viralenv,实现此挂钩,但不返回值(或显式返回 None

  • 覆盖 tox的viralenv创建,实现此钩子并返回一个非`None``‘值。

注解

接口不稳定,此接口为试验性接口 tox.venv.VirtualEnv .

注解

此挂钩使用 firstresult=True (见 pluggy first result only )--实现此操作的挂钩将一直运行,直到返回非``无`为止。

tox.hookspecs.tox_testenv_install_deps(venv, action)[源代码]

执行此venv的安装依赖项操作。

一些用法示例:

  • add 行为,但仍使用tox的实现来安装依赖项,实现此挂钩,但不返回值(或显式返回 None )。一种用例可能是安装(或确保)非Python依赖项,如Debian包。

  • 覆盖 TOX的依赖项安装,实现此挂钩并返回非 None value. One use-case may be to install via a different installation tool such as pip-accelpip-faster .

注解

接口不稳定,此接口为试验性接口 tox.venv.VirtualEnv .

注解

此挂钩使用 firstresult=True (见 pluggy first result only )--实现此操作的挂钩将一直运行,直到返回非``无`为止。

class tox.config.Parser[源代码]

命令行和ini解析器控件对象。

add_argument(*args, **kwargs)[源代码]

向命令行分析器添加参数。这采用了相同的论点, argparse.ArgumentParser.add_argument .

add_testenv_attribute(name, type, help, default=None, postprocess=None)[源代码]

为“testenv”部分添加一个ini-file变量。

类型被指定为字符串,如“bool”、“line-list”、“string”、“argv”、“path”、“argvlist”。

这个 postprocess 函数将为每个TESTEV调用,如 postprocess(testenv_config=testenv_config, value=value) 在哪里? value 是从ini读取的值(或默认值), testenv_config 是一个 tox.config.TestenvConfig 实例,该实例将接收所有ini变量作为对象属性。

任何后处理函数都必须返回一个值,然后该值将被设置为TESTEV部分中的最终值。

add_testenv_attribute_obj(obj)[源代码]

添加一个ini文件变量作为对象。

它的工作方式是 add_testenv_attribute 函数,但需要对象上的“name”、“type”、“help”和“postprocess”属性。

class tox.config.Config[源代码]

全局Tox配置对象。

args

包含所有解析的命令行选项的选项命名空间

envconfigs

映射环境名称->环境配置

class tox.config.TestenvConfig[源代码]

Testenv配置对象。

除了一些核心属性/属性外,此配置对象还将每个testenv ini的所有属性都保存为属性,有关概述,请参阅“tox--help-ini”。

config

全局TOX配置对象

envname

测试环境名称

property envpython

python可执行文件的路径。

factors

一组因素

get_envbindir()[源代码]

脚本/二进制文件所在目录的路径。

get_envpython()[源代码]

python/jython可执行文件的路径。

get_envsitepackagesdir()[源代码]

返回Virtualenv环境的sitepackagesdir。

注意:仅在执行过程中可用,在解析过程中不可用。

property python_info

返回Virtualenv环境的sitepackagesdir。

class tox.venv.VirtualEnv[源代码]
getcommandpath(name, venv=True, cwd=None)[源代码]

返回指定命令名的绝对路径(字符串或本地路径)。

  • 如果它是本地路径,我们会将其重写为相对路径。

  • 如果venv为True,我们将检查命令是来自venv还是允许来自外部。

property name

测试环境名称。

property path

环境基目录的路径。

update(action)[源代码]

返回更新实际venv以匹配配置的状态字符串。如果状态字符串为空,则一切正常。

class tox.session.Session[源代码]

将配置、报告、venv创建和测试捆绑在一起的会话对象。