Plugin API reference¶

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)¶

Overloads:

self, args (Iterable[str] | None), namespace (None) → Namespace
self, args (Iterable[str] | None), namespace (_N) → _N
self, namespace (_N) → _N

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, *, inherit=frozenset({'core', 'env'}))¶

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, ...)

Return type:: Action

classmethod base()¶

Return type:: Self

classmethod core()¶

Return type:: Self

parse_known_args(args=None, namespace=None)¶

Overloads:

self, args (Iterable[str] | None), namespace (None) → tuple[Parsed, list[str]]
self, args (Iterable[str] | None), namespace (_N) → tuple[_N, list[str]]
self, namespace (_N) → tuple[_N, 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(config_source, options, root, pos_args, work_dir, extra_envs)¶

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 factor_labels¶

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 (Sequence[Loader[Any]] | None) – 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)¶

Overloads:

self, keys (str | Sequence[str]), of_type (type[V]), default (Callable[[Config, str | None], V] | V), desc (str), post_process (Callable[[V], V] | None), factory (Factory[Any] | None) → ConfigDynamicDefinition[V]
self, keys (str | Sequence[str]), of_type (UnionType), default (Callable[[Config, str | None], V | None] | V | None), desc (str), post_process (Callable[[V | None], V | None] | None), factory (Factory[Any] | None) → ConfigDynamicDefinition[V | None]

Add configuration value.

Parameters:

keys (str | Sequence[str]) – the keys under what to register the config (first is primary key)
of_type (type[TypeVar(V)] | Union) – 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 (Callable[[TypeVar(V)], TypeVar(V)] | None) – a callback to post-process the configuration value after it has been loaded
factory (Callable[[object], Any] | None) – 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)

Returns:

the new dynamic config definition

add_constant(keys, desc, value)¶

Add a constant value.

Parameters:

keys (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.

default_set_env_loader¶

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:

section (Section) – the section to load
base (list[str] | None) – base sections to fallback to
override_map (Mapping[str, list[Override]]) – a list of overrides to apply
conf (ConfigSet) – the config set to use

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, all_keys=())¶

Load a value (raw and then convert).

Parameters:

key (str) – the key under it lives
of_type (type[TypeVar(V)] | Union) – the type to convert to
factory (Callable[[object], TypeVar(V)] | None) – 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
all_keys (Iterable[str]) – all alias keys for this config entry (to collect overrides from any alias)

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)] | Union) – 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:

raw (TypeVar(T)) – the raw type
of_type (type[TypeVar(V)] | Union) – python type
factory (Callable[[object], TypeVar(V)] | None) – factory method to build the object

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

allow_post_commands_after_interrupt(enabled)¶

Context manager to allow commands_post execution after interrupt when enabled.

Return type:: Iterator[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(enabled, name)¶

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

property shell_cmd_redacted¶

Returns:: the command to run as a shell command with secret-looking flag values masked

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

outcome¶

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:: int

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

unavailable_envs()¶

Get dict of unavailable environment names to runner names.

Return type:: dict[str, str]
Returns:: dict mapping environment name to runner name

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