asv.environment

Manages an environment – a combination of a version of Python and set of dependencies.

Attributes

WIN

Exceptions

EnvironmentUnavailable

Common base class for all exceptions

Classes

Environment	Manage a single environment -- a combination of a particular
ExistingEnvironment	Manage a single environment -- a combination of a particular

Functions

iter_matrix(environment_type, pythons, conf[, ...])	Iterate through all combinations of the given requirement
_parse_matrix(matrix[, bare_keys])	Parse 'matrix' and include/exclude rule configuration entries.
_parse_exclude_include_rule(rule[, is_include])	Parse exclude/include rule by adding key types.
match_rule(target, rule)	Match rule to a target.
get_env_name(tool_name, python, requirements, ...[, build])	Get a name to uniquely identify an environment.
_untag_env_vars(tagged_env_vars[, build])
get_environments(conf, env_specifiers[, verbose])	Iterator returning Environment objects for all of the
_parse_matrix_entries(entries)	Parse mixed requirement / environment variable matrix entries
get_environment_class(conf, python)	Get a matching environment type class.
get_environment_class_by_name(environment_type)	Find the environment class with the given name.
is_existing_only(environments)	Check if the list of environments only contains ExistingEnvironment

Module Contents

asv.environment.WIN

asv.environment.iter_matrix(environment_type, pythons, conf, explicit_selection=False)

Iterate through all combinations of the given requirement matrix and python versions.

Yields

combinationdict of {(key_type, key_name): value, …}

Combination of environment settings. Possible key types are (‘req’, ‘env’, ‘env_nobuild’, ‘python’).

asv.environment._parse_matrix(matrix, bare_keys=())

Parse ‘matrix’ and include/exclude rule configuration entries.

It is in format:

{"key_type1": {"key1": value1, "key2, value2, ...},
 ...,
 "nondict_key1": nondict_value1,
 ...}

or in legacy format:

{"key1": value1, ..., "nondict_key1": nondict_value1, ...}

in which the key type is assumed to be “req”.

Parameters

matrix

Configuration matrix or rule entry

bare_keysiterable

Non-dictionary key values to store as is

Returns

parsed_matrix

Dictionary {(key_type, key): value, …}

asv.environment._parse_exclude_include_rule(rule, is_include=False)

Parse exclude/include rule by adding key types.

Parameters

ruledict

Keys must be str, values must be str or None. The keys ‘python’, ‘environment_type’, ‘sys_platform’, are parsed specially and result to the corresponding key types.

Returns

ruledict

Dictionary of {(key_type, key): value, …}

asv.environment.match_rule(target, rule)

Match rule to a target.

Parameters

targetdict

Dictionary containing [((key_type, key), value), …].

ruledict

Dictionary containing [((key_type, key), match), …], to be matched to target. Match can be str specifying a regexp that must match target[key], or None. None matches either None or a missing key in target. If match is not None, and the key is missing in target, the rule does not match. The key_type must match exactly.

Returns

matchedbool

Whether the rule matched. The rule matches if all keys match.

asv.environment.get_env_name(tool_name, python, requirements, tagged_env_vars, build=False)

Get a name to uniquely identify an environment.

Parameters

buildbool

Whether to omit non-build environment variables. The canonical name of the environment is the name with build=False.

asv.environment._untag_env_vars(tagged_env_vars, build=False)

asv.environment.get_environments(conf, env_specifiers, verbose=True)

Iterator returning Environment objects for all of the permutations of the given versions of Python and a matrix of requirements.

Parameters

confdict

asv configuration object

env_specifierslist of str

List of environment specifiers, in the format ‘env_name:python_spec’. If env_name is empty, autodetect it. If python_spec is missing, use those listed in the configuration file. Alternatively, can be the name given by Environment.name if the environment is in the matrix.

verbosebool, optional

Whether to display warnings about unknown environment types etc.

asv.environment._parse_matrix_entries(entries)

Parse mixed requirement / environment variable matrix entries to requirements and tagged environment variables.

asv.environment.get_environment_class(conf, python)

Get a matching environment type class.

Parameters

confdict

asv configuration object

pythonstr

Python version specifier. Acceptable values depend on the Environment plugins installed but generally are:

• ‘X.Y’: A Python version, in which case conda or virtualenv will be used to create a new environment.

• ‘python’ or ‘/usr/bin/python’: Search for the given executable on the search PATH, and use that. It is assumed that all dependencies and the benchmarked project itself are already installed.

asv.environment.get_environment_class_by_name(environment_type)

Find the environment class with the given name.

asv.environment.is_existing_only(environments)

Check if the list of environments only contains ExistingEnvironment

exception asv.environment.EnvironmentUnavailable

Common base class for all exceptions

class asv.environment.Environment(conf, python, requirements, tagged_env_vars)

Manage a single environment – a combination of a particular version of Python and a set of dependencies for the benchmarked project.

tool_name = None

matches_python_fallback = True

_env_dir

_repo_subdir

_install_timeout

_default_benchmark_timeout

_tagged_env_vars

_path = b'.'

_project

_is_setup = False

_cache

_build_root = b'.'

_requirements

_base_requirements

_build_command

_install_command

_uninstall_command

_global_env_vars

_set_commit_hash(commit_hash)

_set_build_dirs(build_dir, cache_dir)

_set_installed_commit_hash(commit_hash)

_get_installed_commit_hash()

_get_install_checksum()

property installed_commit_hash

classmethod matches(python)

Returns True if this environment subclass can handle the given Python specifier.

property name

Get a name to uniquely identify this environment.

property hashname

Get a hash to uniquely identify this environment.

property dir_name

Get the name of the directory where the environment resides. This is not necessarily unique, and may be shared across different environments.

property requirements

Return the requirements

property env_vars

All environment variables configured in the matrix.

property build_env_vars

Build-time environment variables configured in the matrix.

property python

check_presence()

Check whether the environment already exists.

create()

Create the environment on disk. If it doesn’t exist, it is created. Then, all of the requirements are installed into it.

abstract _setup()

Implementation for setting up the environment.

abstract run(args, **kwargs)

Start up the environment’s python executable with the given args.

_interpolate_commands(commands)

Parse a command list with interpolated variables to a sequence of commands.

Parameters

commands{list of str}

Commands to execute

Returns

run_commandslist of (cmd, env, return_codes, cwd)

Parsed commands to run.

_interpolate_and_run_commands(commands, default_cwd, extra_env=None)

checkout_project(repo, commit_hash)

Check out the working tree of the project at given commit hash

install_project(conf, repo, commit_hash)

Build and install the benchmarked project into the environment. Uninstalls any installed copy of the project first.

_install_project(repo, commit_hash, build_dir)

Run install commands

_uninstall_project()

Run uninstall commands

_build_project(repo, commit_hash, build_dir)

Run build commands

can_install_project()

Return True if specific revisions of the benchmarked project can be installed into this environment.

find_executable(executable)

Find an executable (eg. python, pip) in the environment.

If not found, raises OSError

run_executable(executable, args, **kwargs)

Run a given executable (eg. python, pip) in the environment.

load_info_file(path)

save_info_file(path)

Save a file with information about the environment into directory path.

class asv.environment.ExistingEnvironment(conf, executable, requirements, tagged_env_vars)

Manage a single environment – a combination of a particular version of Python and a set of dependencies for the benchmarked project.

tool_name = 'existing'

_executable

_requirements

property installed_commit_hash

classmethod matches(python)

Returns True if this environment subclass can handle the given Python specifier.

property name

Get a name to uniquely identify this environment.

check_presence()

Check whether the environment already exists.

create()

Create the environment on disk. If it doesn’t exist, it is created. Then, all of the requirements are installed into it.

_setup()

Implementation for setting up the environment.

install_project(conf, repo, commit_hash=None)

Build and install the benchmarked project into the environment. Uninstalls any installed copy of the project first.

can_install_project()

Return True if specific revisions of the benchmarked project can be installed into this environment.

run(args, **kwargs)

Start up the environment’s python executable with the given args.