venv_management.api module

The public API.

Summary

Functions:

`check_environment`	Returns: A 2-tuple containing the status output of the setup command, and text output
`discard_virtual_env`	Discard a virtual environment.
`driver_name`	Get the name of the driver.
`ensure_virtual_env`	Ensure a virtualenv with the given name and version exists.
`has_virtualenvwrapper`	Determine whether virtualenvwrapper available and working.
`list_virtual_envs`	A list of virtualenv names.
`make_virtual_env`	Make a virtual env.
`python_executable_path`	Find the Python executable for a virtual environment.
`python_name`	Find the name of the Python in a virtual environment.
`python_version`	Find the version of the Python in virtual environment.
`remove_virtual_env`	Remove a virtual environment.
`resolve_virtual_env`	Given the name of a virtual environment, get its path.
`virtual_env`	A context manager that ensures a virtualenv with the given name and version exists.

Reference

venv_management.api.check_environment() → Tuple[int, str][source]: Returns: A 2-tuple containing the status output of the setup command, and text output

venv_management.api.has_virtualenvwrapper()[source]

Determine whether virtualenvwrapper available and working.

Returns: True if virtualenvwrapper is available and working, otherwise False.

venv_management.api.list_virtual_envs() → List[str][source]

A list of virtualenv names.

Returns: A list of string names in case-sensitive alphanumeric order.
Raises: ImplementationNotFound – If no virtualenvwrapper implementation could be found.

venv_management.api.make_virtual_env(name, *, python=None, project_path=None, packages=None, requirements_file=None, system_site_packages=False, pip=True, setuptools=True, wheel=True)[source]

Make a virtual env.

Parameters

name – The name of the virtual environment.
python – The target interpreter for which to create a virtual environment, either the name of the executable, or full path.
project_path – An optional path to a project which will be associated with the new virtual environment.
packages – An optional sequence of package names for packages to be installed.
requirements_file – An optional path to a requirements file to be installed.
system_site_packages – If True, give access to the system site packages.
pip – If True, or ‘latest’ the latest pip will be installed. If False, pip will not be installed. If ‘bundled’, the bundled version will be installed. If a specific version string is given, that version will be installed.
setuptools – If True, or ‘latest’ the latest pip will be installed. If False, setuptools will not be installed. If ‘bundled’, the bundled version will be installed. If a specific version string is given, that version will be installed.
wheel – If True, or ‘latest’ the latest pip will be installed. If False, wheel will not be installed. If ‘bundled’, the bundled version will be installed. If a specific version string is given, that version will be installed.

Returns

The Path to the root of the virtualenv, or None if the path could not be determined.

Raises

RuntimeError – If the virtualenv could not be created.

venv_management.api.resolve_virtual_env(name)[source]

Given the name of a virtual environment, get its path.

Parameters

environment. (The name of a virtual) –

Returns

The path to the virtual environment directory.

Raises

ValueError – If the virtual environment name is not known.
RuntimeError – If the path could not be determined.

venv_management.api.virtual_env(name, expected_version=None, *, force=False, **kwargs)[source]

A context manager that ensures a virtualenv with the given name and version exists.

Irrespective of whether the virtual environment already exists, it will be removed when the context manager exits.

Parameters

name – The name of the environment to check for.
expected_version – An optional required version as a string. “3.8” will match “3.8.2”
force – Force replacement of an existing virtual environment which has the wrong version.
**kwargs – Arguments which will be forwarded to mkvirtualenv if the environment needs to be created.

Returns

A context manager that manages the lifecycle of the virtual environment.

Raises

RuntimeError – If the virtual environment couldn’t be created or replaced.

venv_management.api.ensure_virtual_env(name, expected_version=None, *, force=False, **kwargs)[source]

Ensure a virtualenv with the given name and version exists.

Parameters

name – The name of the environment to check for.
expected_version – An optional required version as a string. “3.8” will match “3.8.2”
force – Force replacement of an existing virtual environment which has the wrong version.
**kwargs – Arguments which will be forwarded to mkvirtualenv if the environment needs to be created.

Returns

The path to the virtual environment.

Raises

RuntimeError – If the virtual environment couldn’t be created or replaced.

venv_management.api.remove_virtual_env(name: str)[source]

Remove a virtual environment.

Parameters

name – The name of the virtual environment to remove.

Raises

ValueError – If there is no environment with the given name.
RuntimeError – If the virtualenv could not be removed.

venv_management.api.discard_virtual_env(name: str)[source]

Discard a virtual environment.

Parameters

name – The name of the virtual environment to remove.

Raises

RuntimeError – If the virtualenv could not be removed.
ValueError – If the name is empty.

venv_management.api.python_executable_path(env_dirpath: Union[pathlib.Path, str]) → pathlib.Path[source]

Find the Python executable for a virtual environment.

Parameters: env_dirpath – The path to the root of a virtual environment (Path or str).
Returns: A Path object to the executable.
Raises: ValueError – If the env_dirpath is not a virtual environment.

venv_management.api.python_name(env_dirpath: Union[pathlib.Path, str]) → str[source]

Find the name of the Python in a virtual environment.

Parameters: env_dirpath – The path to the root of a virtual environment (Path or str).
Returns: A descriptive string.
Raises: ValueError – If the env_dirpath is not a virtual environment.

venv_management.api.python_version(env_dirpath: Union[pathlib.Path, str]) → str[source]

Find the version of the Python in virtual environment.

Parameters: env_dirpath – The path to the root of a virtual environment (Path or str).
Returns: A version string, such as “3.8.1”
Raises: ValueError – If the env_dirpath is not a virtual environment.

venv_management.api.driver_name() → str[source]: Get the name of the driver.