API

tox objects

register

Manages the tox environment registry.

class tox.tox_env.register.ToxEnvRegister

Bases: object

tox environment registry.

add_run_env(of_type)

Define a new run tox environment type.

Parameters:

of_type (type[RunToxEnv]) – the new run environment type

Return type:

None

add_package_env(of_type)

Define a new packaging tox environment type.

Parameters:

of_type (type[PackageToxEnv]) – the new packaging environment type

Return type:

None

property env_runners
Returns:

run environment types currently defined

property default_env_runner
Returns:

the default run environment type

runner(name)

Lookup a run tox environment type by name.

Parameters:

name (str) – the name of the runner type

Return type:

type[RunToxEnv]

Returns:

the type of the runner type

package(name)

Lookup a packaging tox environment type by name.

Parameters:

name (str) – the name of the packaging type

Return type:

type[PackageToxEnv]

Returns:

the type of the packaging type

tox.tox_env.register.REGISTER

the tox register

config

class tox.config.cli.parser.ArgumentParserWithEnvAndConfig(*args, **kwargs)

Bases: ArgumentParser

Argument parser which updates its defaults by checking the configuration files and environmental variables.

fix_defaults()
Return type:

None

fix_default(action)
Return type:

None

static get_type(action)
Return type:

type[Any]

parse_args(args=None, namespace=None)
Return type:

Namespace

class tox.config.cli.parser.ToxParser(*args, root=False, add_cmd=False, **kwargs)

Bases: ArgumentParserWithEnvAndConfig

Argument parser for tox.

add_command(cmd, aliases, help_msg, handler)
Return type:

ArgumentParser

add_argument_group(*args, **kwargs)
Return type:

Any

add_argument(*args, of_type=None, **kwargs)
add_argument(option_string, option_string, ..., name=value, ...) → None
Return type:

Action

classmethod base()
Return type:

Self

classmethod core()
Return type:

Self

parse_known_args(args=None, namespace=None)
Return type:

tuple[Parsed, list[str]]

class tox.config.cli.parser.Parsed(**kwargs)

Bases: Namespace

CLI options.

property verbosity
Returns:

reporting verbosity

property is_colored
Returns:

flag indicating if the output is colored or not

exit_and_dump_after
class tox.config.main.Config

Bases: object

Main configuration object for tox.

pos_args(to_path)
Parameters:

to_path (Path | None) – if not None rewrite relative posargs paths from cwd to to_path

Return type:

tuple[str, ...] | None

Returns:

positional argument

property work_dir
Returns:

working directory for this project

property src_path
Returns:

the location of the tox configuration source

sections()
Return type:

Iterator[Section]

property options
property core
Returns:

the core configuration

get_section_config(section, base, of_type, for_env, loaders=None)
Return type:

TypeVar(T, bound= ConfigSet)

get_env(item, package=False, loaders=None)

Return the configuration for a given tox environment (will create if not exist yet).

Parameters:

  • item (str) – the name of the environment is

  • package (bool) – a flag indicating if the environment is of type packaging or not (only used for creation)

  • loaders (Optional[Sequence[Loader[Any]]]) – loaders to use for this configuration (only used for creation)

Return type:

EnvConfigSet

Returns:

the tox environments config

clear_env(name)
Return type:

None

class tox.config.loader.section.Section(prefix, name)

Bases: object

tox configuration section.

SEP = ':'

string used to separate the prefix and the section in the key

classmethod from_key(key)

Create a section from a section key.

Parameters:

key (str) – the section key

Return type:

Self

Returns:

the constructed section

property prefix
Returns:

the prefix of the section

property name
Returns:

the name of the section

property key
Returns:

the section key

class tox.config.loader.api.ConfigLoadArgs(chain, name, env_name)

Bases: object

Arguments that help loading a configuration value.

copy()
Return type:

ConfigLoadArgs

Returns:

create a copy of the object

class tox.config.sets.ConfigSet(conf, section, env_name)

Bases: ABC

A set of configuration that belong together (such as a tox environment settings, core tox settings).

loaders

active configuration loaders, can alter to change configuration values

get_configs()
Return type:

Generator[ConfigDefinition[Any], None, None]

Returns:

a mapping of config keys to their definitions

abstractmethod register_config()
Return type:

None

mark_finalized()
Return type:

None

add_config(keys, of_type, default, desc, post_process=None, factory=None)

Add configuration value.

Parameters:

  • keys (Union[str, Sequence[str]]) – the keys under what to register the config (first is primary key)

  • of_type (type[TypeVar(V)]) – the type of the config value

  • default (Union[Callable[[Config, str | None], TypeVar(V)], TypeVar(V)]) – the default value of the config value

  • desc (str) – a help message describing the configuration

  • post_process (Optional[Callable[[TypeVar(V)], TypeVar(V)]]) – a callback to post-process the configuration value after it has been loaded

  • factory (Optional[Callable[[object], Any]]) – factory method used to build contained objects (if of_type is a container type it should perform the contained item creation, otherwise creates objects that match the type)

Return type:

ConfigDynamicDefinition[TypeVar(V)]

Returns:

the new dynamic config definition

add_constant(keys, desc, value)

Add a constant value.

Parameters:

  • keys (Union[str, Sequence[str]]) – the keys under what to register the config (first is primary key)

  • desc (str) – a help message describing the configuration

  • value (TypeVar(V)) – the config value to use

Return type:

ConfigConstantDefinition[TypeVar(V)]

Returns:

the new constant config value

load(item, chain=None)

Get the config value for a given key (will materialize in case of dynamic config).

Parameters:

  • item (str) – the config key

  • chain (list[str] | None) – a chain of configuration keys already loaded for this load operation (used to detect circles)

Return type:

Any

Returns:

the configuration value

__iter__()
Return type:

Iterator[str]

Returns:

iterate through the defined config keys (primary keys used)

__contains__(item)

Check if a configuration key is within the config set.

Parameters:

item (str) – the configuration value

Return type:

bool

Returns:

a boolean indicating the truthiness of the statement

unused()
Return type:

list[str]

Returns:

Return a list of keys present in the config source but not used

primary_key(key)

Get the primary key for a config key.

Parameters:

key (str) – the config key

Return type:

str

Returns:

the key that’s considered the primary for the input key

property name
property env_name
class tox.config.sets.CoreConfigSet(conf, section, root, src_path)

Bases: ConfigSet

Configuration set for the core tox config.

register_config()
Return type:

None

class tox.config.sets.EnvConfigSet(conf, section, env_name)

Bases: ConfigSet

Configuration set for a tox environment.

register_config()
Return type:

None

class tox.config.of_type.ConfigDefinition(keys, desc)

Bases: ABC, Generic[T]

Abstract base class for configuration definitions.

class tox.config.of_type.ConfigDynamicDefinition(keys, desc, of_type, default, post_process=None, factory=None)

Bases: ConfigDefinition[T]

A configuration definition that comes from a source (such as in memory, an ini file, a toml file, etc.).

class tox.config.of_type.ConfigConstantDefinition(keys, desc, value)

Bases: ConfigDefinition[T]

A configuration definition whose value is defined upfront (such as the tox environment name).

class tox.config.source.api.Source(path)

Bases: ABC

Source is able to return a configuration value (for either the core or per environment source).

FILENAME = ''
path

the path to the configuration source

get_loaders(section, base, override_map, conf)

Return a loader that loads settings from a given section name.

Parameters:
Return type:

Iterator[Loader[Any]]

Returns:

the loaders to use

abstractmethod transform_section(section)
Return type:

Section

abstractmethod get_loader(section, override_map)
Return type:

Optional[Loader[Any]]

abstractmethod get_base_sections(base, in_section)
Return type:

Iterator[Section]

abstractmethod sections()

Return a loader that loads the core configuration values.

Return type:

Iterator[Section]

Returns:

the core loader from this source

abstractmethod envs(core_conf)
Parameters:

core_conf (CoreConfigSet) – the core configuration set

Return type:

Iterator[str]

Returns:

a list of environments defined within this source

abstractmethod get_tox_env_section(item)
Return type:

tuple[Section, list[str], list[str]]

Returns:

the section for a tox environment

abstractmethod get_core_section()
Return type:

Section

Returns:

the core section

class tox.config.loader.api.Override(value)

Bases: object

An override for config definitions.

class tox.config.loader.api.Loader(section, overrides)

Bases: Convert[T]

Loader loads configuration values and converts it.

Parameters:

overrides (list[Override]) – A list of overrides to be applied.

property section

Return the section of the configuration from where the values are extracted.

abstractmethod load_raw(key, conf, env_name)

Load the raw object from the config store.

Parameters:

  • key (str) – the key under what we want the configuration

  • env_name (str | None) – load for env name

  • conf (Config | None) – the global config object

Return type:

TypeVar(T)

abstractmethod found_keys()

A list of configuration keys found within the configuration.

Return type:

set[str]

load(key, of_type, factory, conf, args)

Load a value (raw and then convert).

Parameters:

  • key (str) – the key under it lives

  • of_type (type[TypeVar(V)]) – the type to convert to

  • factory (Optional[Callable[[object], TypeVar(V)]]) – factory method to build the object

  • conf (Config | None) – the configuration object of this tox session (needed to manifest the value)

  • args (ConfigLoadArgs) – the config load arguments

Return type:

TypeVar(V)

Returns:

the converted type

build(key, of_type, factory, conf, raw, args)

Materialize the raw configuration value from the loader.

Parameters:

  • future – a future which when called will provide the converted config value

  • key (str) – the config key

  • of_type (type[TypeVar(V)]) – the config type

  • conf (Config | None) – the global config

  • raw (TypeVar(T)) – the raw value

  • args (ConfigLoadArgs) – env args

Return type:

TypeVar(V)

class tox.config.loader.memory.MemoryLoader(**kwargs)

Bases: Loader[Any]

Loads configuration directly from data in memory.

load_raw(key, conf, env_name)

Load the raw object from the config store.

Parameters:

  • key (Any) – the key under what we want the configuration

  • env_name (str | None) – load for env name

  • conf (Config | None) – the global config object

Return type:

Any

found_keys()

A list of configuration keys found within the configuration.

Return type:

set[str]

static to_bool(value)

Convert to boolean.

Parameters:

value (Any) – the value to convert

Return type:

bool

Returns:

a boolean representation of the value

static to_str(value)

Convert to string.

Parameters:

value (Any) – the value to convert

Return type:

str

Returns:

a string representation of the value

static to_list(value, of_type)

Convert to list.

Parameters:

  • value (Any) – the value to convert

  • of_type (type[Any]) – the type of elements in the list

Return type:

Iterator[Any]

Returns:

a list representation of the value

static to_set(value, of_type)

Convert to set.

Parameters:

  • value (Any) – the value to convert

  • of_type (type[Any]) – the type of elements in the set

Return type:

Iterator[Any]

Returns:

a set representation of the value

static to_dict(value, of_type)

Convert to dictionary.

Parameters:

  • value (Any) – the value to convert

  • of_type (tuple[type[Any], type[Any]]) – a tuple indicating the type of the key and the value

Return type:

Iterator[tuple[Any, Any]]

Returns:

a iteration of key-value pairs that gets populated into a dict

static to_path(value)

Convert to path.

Parameters:

value (Any) – the value to convert

Return type:

Path

Returns:

path representation of the value

static to_command(value)

Convert to a command to execute.

Parameters:

value (Any) – the value to convert

Return type:

Command | None

Returns:

command representation of the value

static to_env_list(value)

Convert to a tox EnvList.

Parameters:

value (Any) – the value to convert

Return type:

EnvList

Returns:

a list of tox environments from the value

class tox.config.loader.convert.Convert

Bases: ABC, Generic[T]

A class that converts a raw type to a given tox (python) type.

to(raw, of_type, factory)

Convert given raw type to python type.

Parameters:
Return type:

TypeVar(V)

Returns:

the converted type

abstractmethod static to_str(value)

Convert to string.

Parameters:

value (TypeVar(T)) – the value to convert

Return type:

str

Returns:

a string representation of the value

abstractmethod static to_bool(value)

Convert to boolean.

Parameters:

value (TypeVar(T)) – the value to convert

Return type:

bool

Returns:

a boolean representation of the value

abstractmethod static to_list(value, of_type)

Convert to list.

Parameters:

  • value (TypeVar(T)) – the value to convert

  • of_type (type[Any]) – the type of elements in the list

Return type:

Iterator[TypeVar(T)]

Returns:

a list representation of the value

abstractmethod static to_set(value, of_type)

Convert to set.

Parameters:

  • value (TypeVar(T)) – the value to convert

  • of_type (type[Any]) – the type of elements in the set

Return type:

Iterator[TypeVar(T)]

Returns:

a set representation of the value

abstractmethod static to_dict(value, of_type)

Convert to dictionary.

Parameters:

  • value (TypeVar(T)) – the value to convert

  • of_type (tuple[type[Any], type[Any]]) – a tuple indicating the type of the key and the value

Return type:

Iterator[tuple[TypeVar(T), TypeVar(T)]]

Returns:

a iteration of key-value pairs that gets populated into a dict

abstractmethod static to_path(value)

Convert to path.

Parameters:

value (TypeVar(T)) – the value to convert

Return type:

Path

Returns:

path representation of the value

abstractmethod static to_command(value)

Convert to a command to execute.

Parameters:

value (TypeVar(T)) – the value to convert

Return type:

Command | None

Returns:

command representation of the value

abstractmethod static to_env_list(value)

Convert to a tox EnvList.

Parameters:

value (TypeVar(T)) – the value to convert

Return type:

EnvList

Returns:

a list of tox environments from the value

class tox.config.types.EnvList(envs)

Bases: object

A tox environment list.

__iter__()
Return type:

Iterator[str]

Returns:

iterator that goes through the defined env-list

class tox.config.types.Command(args)

Bases: object

A command to execute.

ignore_exit_code

a flag indicating if the exit code should be ignored

invert_exit_code

a flag for flipped exit code (non-zero = success, 0 = error)

args

the command line arguments

property shell
Returns:

a shell representation of the command (platform dependent)

tox.config.loader.convert.Factory

alias of Callable[[object], T] | None

environments

class tox.tox_env.api.ToxEnv(create_args)

Bases: ABC

A tox environment.

journal

handler to the tox reporting system

conf

the config set to use for this environment

core

the core tox config set

options

CLI options

log_handler

handler to the tox reporting system

property cache
abstractmethod static id()
Return type:

str

abstract property executor
abstract property installer
register_config()
Return type:

None

property env_dir
Returns:

the tox environments environment folder

property env_tmp_dir
Returns:

the tox environments temp folder

property env_log_dir
Returns:

the tox environments log folder

property name
setup()

Setup the tox environment.

Return type:

None

teardown()
Return type:

None

abstract property runs_on_platform
property environment_variables
execute(cmd, stdin, show=None, cwd=None, run_id='', executor=None)
Return type:

Outcome

interrupt()

Interrupt the execution of a tox environment.

Return type:

None

execute_async(cmd, stdin, show=None, cwd=None, run_id='', executor=None)
Return type:

Iterator[ExecuteStatus]

display_context(suspend)
Return type:

Iterator[None]

close_and_read_out_err()
Return type:

tuple[bytes, bytes] | None

class tox.tox_env.runner.RunToxEnv(create_args)

Bases: ToxEnv, ABC

register_config()
Return type:

None

interrupt()

Interrupt the execution of a tox environment.

Return type:

None

get_package_env_types()
Return type:

tuple[str, str] | None

property environment_variables
property package_envs
mark_active()
Return type:

None

class tox.tox_env.package.PackageToxEnv(create_args)

Bases: ToxEnv, ABC

register_config()
Return type:

None

abstractmethod perform_packaging(for_env)
Return type:

list[Package]

register_run_env(run_env)
Return type:

Generator[tuple[str, str], PackageToxEnv, None]

mark_active_run_env(run_env)
Return type:

None

teardown_env(conf)
Return type:

None

abstractmethod child_pkg_envs(run_conf)
Return type:

Iterator[PackageToxEnv]

class tox.tox_env.package.Package

Bases: object

package.

journal

class tox.journal.env.EnvJournal

Bases: object

Report the status of a tox environment.

__setitem__(key, value)

Add a new entry under key into the event journal.

Parameters:

  • key (str) – the key under what to add the data

  • value (Any) – the data to add

Return type:

None

__bool__()
Return type:

bool

Returns:

a flag indicating if the event journal is on or not

add_execute(outcome, run_id)

Add a command execution to the journal.

Parameters:

  • outcome (Outcome) – the execution outcome

  • run_id (str) – the execution id

Return type:

None

property content
Returns:

the env journal content (merges explicit keys and execution commands)

report

class tox.report.ToxHandler(level, is_colored, out_err)

Bases: StreamHandler

with_context(name)

Set a new tox environment context.

Parameters:

name (str) – the name of the tox environment

Return type:

Iterator[None]

property name
Returns:

the current tox environment name

property stdout
Returns:

the current standard output

property stderr
Returns:

the current standard error

update_verbosity(verbosity)
Return type:

None

execute

class tox.execute.request.ExecuteRequest(cmd, cwd, env, stdin, run_id, allow=None)

Bases: object

Defines a commands execution request.

cmd

the command to run

cwd

the working directory to use

env

the environment variables to use

stdin

the type of standard input interaction allowed

run_id

an id to identify this run

property shell_cmd
Returns:

the command to run as a shell command

class tox.execute.request.StdinSource(*values)

Bases: Enum

OFF = 0

input disabled

USER = 1

input via the standard input

API = 2

input via programmatic access

static user_only()
Return type:

StdinSource

Returns:

USER if the standard input is tty type else OFF

class tox.execute.api.Outcome(request, show_on_standard, exit_code, out, err, start, end, cmd, metadata)

Bases: object

Result of a command execution.

OK = 0
request

the execution request

show_on_standard

a flag indicating if the execution was shown on stdout/stderr

exit_code

the exit code for the execution

out

the standard output of the execution

err

the standard error of the execution

start

a timer sample for the start of the execution

end

a timer sample for the end of the execution

cmd

the command as executed

metadata

additional metadata attached to the execution

assert_success()

Assert that the execution succeeded.

Return type:

None

assert_failure()

Assert that the execution failed.

Return type:

None

log_run_done(lvl)

Log that the run was done.

Parameters:

lvl (int) – the level on what to log as interpreted by logging.log()

Return type:

None

property elapsed
Returns:

time the execution took in seconds

out_err()
Return type:

tuple[str, str]

Returns:

a tuple of the standard output and standard error

class tox.execute.api.Execute(colored)

Bases: ABC

Abstract API for execution of a tox environment.

call(request, show, out_err, env)
Return type:

Iterator[ExecuteStatus]

abstractmethod build_instance(request, options, out, err)
Return type:

ExecuteInstance

classmethod register_conf(env)
Return type:

None

class tox.execute.api.ExecuteStatus(options, out, err)

Bases: ABC

abstract property exit_code
abstractmethod wait(timeout=None)
Return type:

int | None

abstractmethod write_stdin(content)
Return type:

None

abstractmethod interrupt()
Return type:

None

set_out_err(out, err)
Return type:

tuple[SyncWrite, SyncWrite]

property out
property err
property metadata
class tox.execute.api.ExecuteInstance(request, options, out, err)

Bases: ABC

An instance of a command execution.

property out_handler
property err_handler
abstract property cmd
class tox.execute.stream.SyncWrite(name, target, color=None)

Bases: object

Make sure data collected is synced in-memory and to the target stream on every newline and time period.

Used to propagate executed commands output to the standard output/error streams visible to the user.

REFRESH_RATE = 0.1
handler(content)

A callback called whenever content is written.

Return type:

None

colored()
Return type:

Iterator[None]

property text
property content

installer

class tox.tox_env.installer.Installer(tox_env)

Bases: ABC, Generic[T]

abstractmethod installed()
Return type:

Any

Returns:

a list of packages installed (JSON dump-able)

abstractmethod install(arguments, section, of_type)
Return type:

None

session

class tox.session.state.State(options, args)

Bases: object

Runtime state holder.

property envs
Returns:

provides access to the tox environments

class tox.session.env_select.EnvSelector(state)

Bases: object

iter(*, only_active=True, package=False)

Get tox environments.

Parameters:

  • only_active (bool) – active environments are marked to be executed in the current target

  • package (bool) – return package environments

Return type:

Iterator[str]

Returns:

an iteration of tox environments

ensure_only_run_env_is_active()
Return type:

None

class tox.tox_env.info.Info(path)

Bases: object

Stores metadata about the tox environment.

compare(value, section, sub_section=None)

Compare new information with the existing one and update if differs.

Parameters:

  • value (Any) – the value stored

  • section (str) – the primary key of the information

  • sub_section (str | None) – the secondary key of the information

Return type:

Iterator[tuple[bool, Any | None]]

Returns:

a tuple where the first value is if it differs and the second is the old value

reset()
Return type:

None