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.
- add_package_env(of_type)¶
Define a new packaging tox environment type.
- Parameters:
of_type (
type
[PackageToxEnv
]) – the new packaging environment type- Return type:
- 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.
- 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.
- 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:
- 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)¶
- property work_dir¶
- Returns:
working directory for this project
- property src_path¶
- Returns:
the location of the tox configuration source
- property options¶
- property core¶
- Returns:
the core configuration
- get_section_config(section, base, of_type, for_env, loaders=None)¶
- get_env(item, package=False, loaders=None)¶
Return the configuration for a given tox environment (will create if not exist yet).
- Parameters:
- Return type:
- Returns:
the tox environments config
- 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:
- 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
- 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)default (
Union
[Callable
[[Config
,str
|None
],TypeVar
(V
)],TypeVar
(V
)]) – the default value of the config valuedesc (
str
) – a help message describing the configurationpost_process (
Optional
[Callable
[[TypeVar
(V
)],TypeVar
(V
)]]) – a callback to post-process the configuration value after it has been loadedfactory (
Optional
[Callable
[[object
],Any
]]) – factory method used to build contained objects (ifof_type
is a container type it should perform the contained item creation, otherwise creates objects that match the type)
- Return type:
- Returns:
the new dynamic config definition
- add_constant(keys, desc, value)¶
Add a constant value.
- Parameters:
- Return type:
- 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).
- __iter__()¶
- __contains__(item)¶
Check if a configuration key is within the config set.
- unused()¶
- primary_key(key)¶
Get the primary key for a config 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.
- class tox.config.sets.EnvConfigSet(conf, section, env_name)¶
Bases:
ConfigSet
Configuration set for a tox environment.
- class tox.config.of_type.ConfigDefinition(keys, desc)¶
-
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.
- abstract sections()¶
Return a loader that loads the core configuration values.
- abstract envs(core_conf)¶
- Parameters:
core_conf (
CoreConfigSet
) – the core configuration set- Return type:
- Returns:
a list of environments defined within this source
- abstract get_tox_env_section(item)¶
- class tox.config.loader.api.Loader(section, overrides)¶
-
Loader loads configuration values and converts it.
- property section¶
Return the section of the configuration from where the values are extracted.
- abstract load_raw(key, conf, env_name)¶
Load the raw object from the config store.
- abstract found_keys()¶
A list of configuration keys found within the configuration.
- load(key, of_type, factory, conf, args)¶
Load a value (raw and then convert).
- Parameters:
- Return type:
TypeVar
(V
)- Returns:
the converted type
- build(key, of_type, factory, conf, raw, args)¶
Materialize the raw configuration value from the loader.
- class tox.config.loader.memory.MemoryLoader(**kwargs)¶
-
Loads configuration directly from data in memory.
- load_raw(key, conf, env_name)¶
Load the raw object from the config store.
- static to_bool(value)¶
Convert to boolean.
- static to_str(value)¶
Convert to string.
- static to_list(value, of_type)¶
Convert to list.
- static to_set(value, of_type)¶
Convert to set.
- static to_dict(value, of_type)¶
Convert to dictionary.
- static to_path(value)¶
Convert to path.
- static to_command(value)¶
Convert to a command to execute.
- class tox.config.loader.convert.Convert¶
-
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.
- abstract static to_str(value)¶
Convert to string.
- abstract static to_bool(value)¶
Convert to boolean.
- abstract static to_list(value, of_type)¶
Convert to list.
- abstract static to_set(value, of_type)¶
Convert to set.
- abstract static to_dict(value, of_type)¶
Convert to dictionary.
- abstract static to_path(value)¶
Convert to path.
- abstract static to_command(value)¶
Convert to a command to execute.
- 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)
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¶
- abstract property executor¶
- abstract property installer¶
- 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¶
- abstract property runs_on_platform¶
- property environment_variables¶
- execute_async(cmd, stdin, show=None, cwd=None, run_id='', executor=None)¶
- Return type:
- class tox.tox_env.runner.RunToxEnv(create_args)¶
-
- property environment_variables¶
- property package_envs¶
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.
- add_execute(outcome, run_id)¶
Add a command execution to the journal.
- property content¶
- Returns:
the env journal content (merges explicit keys and execution commands)
report¶
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(value, names=<not given>, *values, 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:
- Returns:
USER
if the standard input is tty type elseOFF
- 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
- log_run_done(lvl)¶
Log that the run was done.
- Parameters:
lvl (
int
) – the level on what to log as interpreted bylogging.log()
- Return type:
- property elapsed¶
- Returns:
time the execution took in seconds
- class tox.execute.api.Execute(colored)¶
Bases:
ABC
Abstract API for execution of a tox environment.
- call(request, show, out_err, env)¶
- Return type:
- abstract build_instance(request, options, out, err)¶
- Return type:
- class tox.execute.api.ExecuteStatus(options, out, err)¶
Bases:
ABC
- abstract property exit_code¶
- 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¶
- property text¶
- property content¶
installer¶
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.