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#
Return type:

Iterable[str]

Returns:

run environment types currently defined

property default_env_runner#
Return type:

str

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:

TypeVar(ToxParserT, bound= ToxParser)

classmethod core()#
Return type:

TypeVar(ToxParserT, bound= ToxParser)

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#
Return type:

int

Returns:

reporting verbosity

property is_colored#
Return type:

bool

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 (Optional[Path]) – if not None rewrite relative posargs paths from cwd to to_path

Return type:

Optional[tuple[str, ...]]

Returns:

positional argument

property work_dir#
Return type:

Path

Returns:

working directory for this project

property src_path#
Return type:

Path

Returns:

the location of the tox configuration source

sections()#
Return type:

Iterator[Section]

property options#
Return type:

Parsed

property core#
Return type:

CoreConfigSet

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

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

TypeVar(_Section, bound= Section)

Returns:

the constructed section

property prefix#
Return type:

Optional[str]

Returns:

the prefix of the section

property name#
Return type:

str

Returns:

the name of the section

property key#
Return type:

str

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

abstract 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, Optional[str]], 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 (Optional[list[str]]) – 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#
Return type:

str

property env_name#
Return type:

Optional[str]

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

abstract transform_section(section)#
Return type:

Section

abstract get_loader(section, override_map)#
Return type:

Optional[Loader[Any]]

abstract get_base_sections(base, in_section)#
Return type:

Iterator[Section]

abstract sections()#

Return a loader that loads the core configuration values.

Return type:

Iterator[Section]

Returns:

the core loader from this source

abstract envs(core_conf)#
Parameters:

core_conf (CoreConfigSet) – the core configuration set

Return type:

Iterator[str]

Returns:

a list of environments defined within this source

abstract get_tox_env_section(item)#
Return type:

tuple[Section, list[str]]

Returns:

the section for a tox environment

abstract 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 a configuration value and converts it.

property section#
Return type:

Section

abstract 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 (Optional[str]) – load for env name

  • conf (Optional[Config]) – the global config object

Return type:

TypeVar(T)

abstract 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 (Optional[Config]) – 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(future, key, of_type, conf, raw, args)#

Materialize the raw configuration value from the loader.

Parameters:
  • future (Future[TypeVar(V)]) – 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 (Optional[Config]) – the global config

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

  • args (ConfigLoadArgs) – env args

Return type:

Generator[TypeVar(T), None, None]

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

abstract 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

abstract 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

abstract 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

abstract 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

abstract 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

abstract static to_path(value)#

Convert to path.

Parameters:

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

Return type:

Path

Returns:

path representation of the value

abstract static to_command(value)#

Convert to a command to execute.

Parameters:

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

Return type:

Command

Returns:

command representation of the value

abstract 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

args#

the command line arguments

property shell#
Return type:

str

Returns:

a shell representation of the command (platform dependent)

tox.config.loader.convert.Factory#

alias of Optional[Callable[[object], T]]

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#
Return type:

Info

abstract static id()#
Return type:

str

abstract property executor#
Return type:

Execute

abstract property installer#
Return type:

Installer[Any]

register_config()#
Return type:

None

property env_dir#
Return type:

Path

Returns:

the tox environments environment folder

property env_tmp_dir#
Return type:

Path

Returns:

the tox environments temp folder

property env_log_dir#
Return type:

Path

Returns:

the tox environments log folder

property name#
Return type:

str

setup()#

Setup the tox environment.

Return type:

None

teardown()#
Return type:

None

abstract property runs_on_platform#
Return type:

str

property environment_variables#
Return type:

dict[str, str]

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:

Optional[tuple[bytes, bytes]]

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:

Optional[tuple[str, str]]

property environment_variables#
Return type:

dict[str, str]

property package_envs#
Return type:

Iterable[PackageToxEnv]

mark_active()#
Return type:

None

class tox.tox_env.package.PackageToxEnv(create_args)#

Bases: ToxEnv, ABC

register_config()#
Return type:

None

abstract 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

abstract 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#
Return type:

dict[str, Any]

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#
Return type:

str

Returns:

the current tox environment name

property stdout#
Return type:

TextIOWrapper

Returns:

the current standard output

property stderr#
Return type:

TextIOWrapper

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#
Return type:

str

Returns:

the command to run as a shell command

class tox.execute.request.StdinSource(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

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

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#
Return type:

float

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]

abstract 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#
Return type:

Optional[int]

abstract wait(timeout=None)#
Return type:

Optional[int]

abstract write_stdin(content)#
Return type:

None

abstract interrupt()#
Return type:

None

set_out_err(out, err)#
Return type:

tuple[SyncWrite, SyncWrite]

property out#
Return type:

bytearray

property err#
Return type:

bytearray

property metadata#
Return type:

dict[str, Any]

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

Bases: ABC

An instance of a command execution

property out_handler#
Return type:

Callable[[bytes], None]

property err_handler#
Return type:

Callable[[bytes], None]

abstract property cmd#
Return type:

Sequence[str]

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#
Return type:

str

property content#
Return type:

bytearray

installer#

class tox.tox_env.installer.Installer(tox_env)#

Bases: ABC, Generic[T]

abstract installed()#
Return type:

Any

Returns:

a list of packages installed (JSON dump-able)

abstract install(arguments, section, of_type)#
Return type:

None

session#

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

Bases: object

Runtime state holder.

property envs#
Return type:

EnvSelector

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 (Optional[str]) – the secondary key of the information

Return type:

Iterator[tuple[bool, Optional[Any]]]

Returns:

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

reset()#
Return type:

None