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
,Optional
[str
]],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 a configuration value and converts it.
- property section#
- 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.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.
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=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:
- 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.