tox插件¶
2.0 新版功能.
越来越多的钩子通过编写插件使TOX可以在执行的不同阶段进行修改。
类tox pytest 和 devpi -用途 pluggy 为pip可安装的内部插件或devpi/pyPI发布的插件提供扩展机制。
使用插件¶
要开始使用插件,您需要将其安装在安装TOX主机的同一环境中。
例如。:
$ pip install tox-travis
您可以在PyPI上搜索可用的插件,方法是访问 PyPI 并搜索带有前缀的包 tox-
或者在描述中包含单词“plugin”。示例包括:
tox-ansible - Plugin for generating tox environments for tools like ansible-test
tox-asdf - A tox plugin that finds python executables using asdf
tox-backticks - Allows backticks within setenv blocks for populating
environment variables
tox-bindep - Runs bindep checks prior to tests
tox-bitbucket-status - Update bitbucket status for each env
tox-cmake - Build CMake projects using tox
tox-conda - Provides integration with the conda package manager
tox-current-env - Run tests in the current python environment
tox-docker - Launch a docker instance around test runs
tox-direct - Run everything directly without tox venvs
tox-envlist - Allows selection of a different tox envlist
tox-envreport - A tox-plugin to document the setup of used virtual
tox-factor - Runs a subset of tox test environments
tox-globinterpreter - tox plugin to allow specification of interpreter
tox-gh-actions - A plugin for helping to run tox in GitHub actions.
tox-ltt - Light-the-torch integration
tox-no-internet - Workarounds for using tox with no internet connection
tox-pdm - Utilizes PDM as the package manager and installer
tox-pip-extensions - Augment tox with different installation methods via
progressive enhancement.
tox-pipenv - A pipenv plugin for tox
tox-pipenv-install - Install packages from Pipfile
tox-poetry - Install packages using poetry
tox-py-backwards - tox plugin for py-backwards
tox-pyenv - tox plugin that makes tox use ``pyenv which`` to find
python executables
tox-pytest-summary - tox + Py.test summary
tox-run-before - tox plugin to run shell commands before the test
environments are created.
tox-run-command - tox plugin to run arbitrary commands in a virtualenv
tox-tags - Allows running subsets of environments based on tags
tox-travis - Seamless integration of tox into Travis CI
tox-venv - Use python3 venvs for python3 tox testenvs environments.
tox-virtualenv-no-download - Disable virtualenv's download-by-default in tox
可能还有一些插件还不能从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
钩子规范及相关接口¶
tox挂钩规范-请参阅https://pluggy.readthedocs.io/
- tox.hookspecs.tox_get_python_executable(envconfig)[源代码]¶
返回给定python基名的python可执行文件。
第一个返回可执行路径的插件/钩子将确定它。
envconfig
是Testenv配置,它包含每个Testenv配置,特别是.envname
和.basepython
设置。
- 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_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-accel 或 pip-faster .
注解
接口不稳定,此接口为试验性接口
tox.venv.VirtualEnv
.注解
此挂钩使用
firstresult=True
(见 pluggy first result only )--实现此操作的挂钩将一直运行,直到返回非``无`为止。
- class tox.config.Parser[源代码]¶
命令行和ini解析器控件对象。
- 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部分中的最终值。
- class tox.config.TestenvConfig[源代码]¶
Testenv配置对象。
除了一些核心属性/属性外,此配置对象还将每个testenv ini的所有属性都保存为属性,有关概述,请参阅“tox--help-ini”。
- config¶
全局TOX配置对象
- envname¶
测试环境名称
- property envpython¶
python可执行文件的路径。
- factors¶
一组因素
- property python_info¶
返回Virtualenv环境的sitepackagesdir。