Configuration settings

Overview

The uvoxen tool is configured using the pyproject.toml file. Most of the definitions are in the tool.uvoxen section, but it also parses the dependency-groups one and the project.classifiers list.

[project]
classifiers = [
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
]

[dependency-groups]
testenv-docker = [
  "build >= 1, < 2",
]
testenv-mypy = [
  {include-group = "testenv-unit-tests"},
  "mypy >= 1.7, < 2",
]
testenv-unit-tests = [
  "pytest >= 7, < 8",
]

[tool.uvoxen]
envlist = [
  "mypy",
  "unit-tests",
]

[tool.uvoxen.format.version]
major = 0
minor = 1

[tool.uvoxen.defs]
pyfiles = [
  "src/divert-and-modify",
  "tests/unit",
]

[tool.uvoxen.req]
header = """
# SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
# SPDX-License-Identifier: BSD-2-Clause

"""

[tool.uvoxen.tox]
env-order = [
  "format",
  "reformat",
  "ruff",
]

envlist-add = [
  "unit-tests-pytest-7",
]

footer = """

[testenv:unit-tests-pytest-7]
...
"""

[tool.uvoxen.env.mypy]
dependency-groups = [
  "testenv-mypy",
]
commands = [
  "mypy -- {[defs]pyfiles}",
]

[tool.uvoxen.env.unit-tests]
dependency-groups = [
  "testenv-unit-tests",
]
install-project = true
commands = [
  "pytest {posargs} tests/unit",
]

[tool.uvoxen.env.docker]
dependency-groups = [
  "testenv-docker",
]
install-project = true
passenv = [
  "TEST_DOCKER_OPTS",
]
commands = [
  "python3 -m test_docker run {env:TEST_DOCKER_OPTS}",
]

[tool.uvoxen.env.docker.setenv]
PYTHONPATH = "{toxinidir}/tests/docker/python"

Variable expansion

In several places (commands run via uv run, environment variables listed in setenv tables) the uvoxen tool will parse a string and substitute variable specifications with expanded values.

Variables from the defs section

The tool.uvoxen.defs section of the pyproject.toml file contains variables (strings or lists of strings) that may be expanded using the {[defs]varname} syntax.

Environment variables

The {env:NAME} syntax may be used to substitute the string value of a variable in the current process environment.

Default values ({env:NAME:DEFAULT}) or recursive substituton are not supported yet.

Predefined Tox variables

For compatibility with Tox environment definitions, the following will be expanded:

{envdir}: the full path to the virtual environment prepared for this test run
{posargs}: additional command-line arguments passed to the uv run subcommand
{toxinidir}: the full path to the directory containing the pyproject.toml file

Configuration settings

tool.uvoxen

General definitions for various uvoxen subcommands.

tool.uvoxen.defs

Table of strings or lists of strings.

The keys are variable names; the values will be expanded in commands to be run or environment variables to be set using Tox-like {[defs]varname} syntax. The values may contain variables themselves: {[defs]name} for other variables, {env:NAME} for environment variables, or predefined Tox ones such as {envdir}, {toxinidir}, etc.

Added in format version 0.1.

tool.uvoxen.envlist

List of strings.

The environment names to be run by default by the uv run subcommand, or to be output as tox.envlist by the tox generate / tox run ones.

Added in format version 0.1.

tool.uvoxen.format.version

The version of the format of the configuration file itself.

This version is similar to a semantic one: the major number will only be incremented on incompatible changes (removing a setting or changing the meaning or type of one), and the minor number will be incremenented when new settings are added, but the meaning of the existing ones is not changed. Thus, a version of uvoxen that is capable of parsing configuration files in the 2.3 format will be able to fully process files in the 2.0, 2.1, and 2.2 ones, and it will be able to read files in the 2.4 or 2.12 format, although some of their fields may be ignored.

There is no guarantee that versions of uvoxen will necessarily be able to read files with a lower major version of the format. The lowest and highest supported format versions are available as the format-min and format-max features in the output of the uvoxen --features command or the uvoxen.defs.FEATURES Python dictionary.

tool.uvoxen.format.version.major

Integer.

The major version number.

Added in format version 0.1.

tool.uvoxen.format.version.minor

Integer.

The minor version number.

Added in format version 0.1.

tool.uvoxen.req

Definitions for the req generate subcommand.

tool.uvoxen.req.footer

Multiline string.

One or more lines of text to be placed at the bottom of the generated file.

Added in format version 0.1.

tool.uvoxen.req.header

Multiline string.

One or more lines of text to be placed at the top of the generated file.

Added in format version 0.1.

tool.uvoxen.tox

Definitions for the tox generate subcommand.

tool.uvoxen.env-order

List of strings.

Environment names to be output first after the tox and defs sections of the generated file. Any environments not listed here will be output in lexicographical order of their names.

Added in format version 0.1.

tool.uvoxen.envlist-append

List of strings.

Environment names to append to the end of the tox.envlist variable.

Added in format version 0.1.

tool.uvoxen.tox.footer

Multiline string.

One or more lines of text to be placed at the bottom of the generated file.

Added in format version 0.1.

tool.uvoxen.tox.header

Multiline string.

One or more lines of text to be placed at the top of the generated file.

Added in format version 0.1.

tool.uvoxen.env

The definitions of the test environments themselves.

tool.uvoxen.env.NAME.allowlist-externals

List of strings

The names of allowed external commands that will be copied into the allowlist_externals parameter of the Tox environment.

Added in format version 0.1.

tool.uvoxen.env.NAME.commands

List of strings.

The commands to be run in succession for this test environment. When these commands are run via the uv run subcommand, Tox-style variables ({[defs]varname]}, {env:NAME}, {envdir}, {posargs}, etc.) will be expanded.

Added in format version 0.1.

tool.uvoxen.env.NAME.dependency-groups

List of strings.

The names of the dependency groups to be installed into the virtual environment when running this test. The groups must be defined in the dependency-groups top-level section of the pyproject.toml file.

Added in format version 0.1.

tool.uvoxen.env.NAME.install-dependencies

Boolean.

Whether this test environment needs the project dependencies (but not necessarily the project itself) to be installed into the virtual environment.

This parameter is ignored by the uv run subcommand, but it causes the uv generate one to omit the skip_install=True line, so that the project itself will be installed into the Tox virtual environment.

Added in format version 0.1.

tool.uvoxen.env.NAME.install-project

Boolean.

Whether this test environment needs the project itself to be installed into the virtual environment.

This parameter is ignored by the uv run subcommand, but it causes the uv generate one to omit the skip_install=True line, so that the project itself will be installed into the Tox virtual environment.

Added in format version 0.1.

tool.uvoxen.env.NAME.passenv

List of strings.

The names of additional environment variables that will be passed from the current process environment into the one where the test is run.

Added in format version 0.1.

tool.uvoxen.env.NAME.setenv

Table of strings.

The names and values of environment variables to be set when running the test. Variable specifications in the values will be expanded when the test is run via the uv run subcommand.

Added in format version 0.1.

tool.uvoxen.env.NAME.tags

List of strings.

Tags that will be copied into the tags parameter of the Tox environment so that it may later be selected or ordered for running by the tox-stages tool.

A uv run-stages subcommand is planned; it will also make use of these.

Added in format version 0.1.