深入理解tox-dev/tox项目配置指南

深入理解tox-dev/tox项目配置指南

tox Command line driven CI frontend and development task automation tool. 项目地址: https://gitcode.com/gh_mirrors/to/tox

配置概述

tox是一个流行的Python测试工具，它通过创建隔离的虚拟环境来运行测试。tox的配置可以分为两大类：

1. 核心配置：适用于所有tox环境的全局设置
2. 环境特定配置：仅适用于特定tox环境的设置

配置文件格式与发现机制

tox支持多种配置文件格式和位置，按以下优先级顺序查找：

1. tox.ini (INI格式)
2. setup.cfg (INI格式)
3. pyproject.toml (使用tool.tox表和legacy_tox_ini键的INI格式)
4. pyproject.toml (原生TOML格式)
5. tox.toml (原生TOML格式)

格式对比

| 特性 | INI格式 | TOML格式 | |------|--------|---------| | 历史 | 较早支持 | 2024年新增 | | 语法 | 简洁 | 更规范 | | 功能 | 更强大 | 较有限 | | 条件因素 | 支持 | 暂不支持 | | 生成环境 | 支持 | 暂不支持 |

配置文件详解

1. tox.ini配置示例

[tox]
min_version = 4.20
env_list =
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src

• [tox]：核心配置
• [testenv]：所有测试环境的基准配置
• [testenv:type]：特定环境(type)的配置

2. setup.cfg配置

与tox.ini类似，但核心配置放在[tox:tox]部分：

[tox:tox]
min_version = 4.0
env_list =
    3.13
    3.12
    type

3. pyproject.toml (INI风格)

[tool.tox]
legacy_tox_ini = """
    [tox]
    min_version = 4.0
    env_list =
        py310
        py39
        type
"""

4. pyproject.toml (原生TOML)

[tool.tox]
requires = ["tox>=4.19"]
env_list = ["3.13", "3.12", "type"]

[tool.tox.env_run_base]
description = "Run test under {base_python}"
commands = [["pytest"]]

[tool.tox.env.type]
description = "run type check on code base"
deps = ["mypy==1.11.2"]

5. tox.toml配置

requires = ["tox>=4.19"]
env_list = ["3.13", "3.12", "type"]

[env_run_base]
description = "Run test under {base_python}"
commands = [["pytest"]]

核心配置选项

基本配置

• requires：指定运行tox所需依赖(PEP 508格式)
• min_version：要求的最低tox版本
• env_list：默认运行的环境列表
• skip_missing_interpreters：是否跳过缺失的解释器

路径配置

• tox_root：项目根目录
• work_dir：tox工作目录(默认.tox)
• temp_dir：临时文件目录

打包配置

• no_package：是否跳过打包步骤
• package_env：打包环境名称(默认.pkg)
• package_root：打包根目录

环境配置选项

基础设置

• env_dir：环境目录
• env_tmp_dir：环境临时目录
• env_log_dir：环境日志目录

平台与变量

• platform：平台匹配正则表达式
• pass_env：传递给环境的变量
• set_env：设置环境变量

执行控制

• parallel_show_output：并行运行时是否显示输出
• recreate：是否总是重建环境
• allowlist_externals：允许的外部命令

最佳实践建议

1. 格式选择：

   • 新项目推荐使用原生TOML格式
   • 需要高级功能时使用INI格式

2. 版本控制：

   • 总是指定min_version确保兼容性
   • 使用requires明确依赖

3. 环境组织：

   • 使用env_list定义默认环境
   • 利用labels对环境进行分类

4. 变量管理：

   • 使用set_env集中管理环境变量
   • 谨慎使用pass_env传递变量

5. 跨平台考虑：

   • 注意不同平台的环境变量差异
   • 使用platform限制环境运行平台

通过合理配置tox，可以创建高效、可靠的测试环境，确保项目在不同Python版本和平台下的兼容性。

tox Command line driven CI frontend and development task automation tool. 项目地址: https://gitcode.com/gh_mirrors/to/tox