Python invirtualenv module code documentation¶

Python module support functions for the invirtualenv scripts

InVirtualEnv Python Virtualenv Installer Module

Configuration Manipulation¶

Functions for handling the configuration settings

invirtualenv.config.cast_types(configuration, types_dict=None)¶

Update in place the configuration dictionary with inferred values if they aren’t specified.

Parameters:	configuration (dict) – config_types (dict, optional) – Types dictionary, defaults to value from config_types()

invirtualenv.config.generate_parsed_config_file(source=None, dest=None)¶

Generate a conf file with the environment variables expanded

Parameters:	source (str, optional) – The path to the source file dest (str, optional) – The path to the desired destination file
Returns:	Path to the generated config file
Return type:	str

invirtualenv.config.get_configuration(configuration=None)¶

Parse a configuration file

Parameters:	configuration (str or list, optional) – A configuration file or list of configuration files to parse, defaults to the deploy_default.conf file in the package and deploy.conf in the current working directory.
Returns:	The parsed configuration
Return type:	configparser

invirtualenv.config.get_configuration_dict(configuration=None, value_types=None)¶

Parse the configuration files

Parameters:	configuration (str or list, optional) – A configuration file or list of configuration files to parse, defaults to the deploy_default.conf file in the package and deploy.conf in the current working directory. value_types (dict, optional) – Dictionary containing classes to apply to specific items
Returns:	Configuration dictionary
Return type:	dict

invirtualenv.config.parse_arguments(configuration=None)¶

Parse the command line arguments

Parameters:	configuration (list, optional) – A list of config files to parse, defaults to the packaged deploy_default.conf and the deploy.conf file in the current directory.
Returns:	With the configuration based on the passed command line arguments and defaults from the deploy_default.conf file in the package.
Return type:	argparse namespace object

Deployment¶

Module to create/deploy a virtualenv

invirtualenv.deploy.build_deploy_virtualenv(arguments=None, configuration=None, update_existing=True, verbose=None)¶

Build and deploy a python virtualenv

Parameters:

arguments (argparse namespace, optional) – An argparse namespace with all of the required command line arguments defaults to parsing the command line arguments if not provided.
configuration (str or list, optional) – A configuration file or list of configuration files to parse, defaults to the deploy_default.conf file in the package and deploy.conf in the current working directory.
update_existing (bool) – If True, allow updating an existing virtualenv, Otherwise generate an exception. Default=True
verbose (bool) – If True, provides status output while running.

Raises:

AlreadyExists – The virtualenv already exists
BuildError – The specified package manifest cannot be deployed to the virtualenv
InsufficientPermissions – The current user lacks permissions to complete the specified operation
NoPackageVersions – A virtualenv_version_package was specified in the configuration but no versions for that package where found on artifactory.

invirtualenv.deploy.deployed_bin_files(venv)¶

Gets files that where deployed to the bin directory of the virtualenv.

Parameters:	venv (str) – Path the to virtualenv to do this bin_file links for
Returns:	Key = filename Value = sha256 hash
Return type:	dict

invirtualenv.deploy.fix_file_ownership(virtualenv, user, group)¶

Fix the file ownership of a virtualenv

Parameters:	virtualenv (str) – Virtualenv path user (str) – User to change to group (str) – Group to change to

:param : :type : return:

invirtualenv.deploy.install_python_dependencies(virtualenv, deps=None, requirements=None, upgrade=False, verbose=False, pip_version=None, use_index=True, use_local_wheels=False)¶

Install python dependencies from a requirements file or deploy.conf manifest

Parameters:

virtualenv (str) – The virtualenv to install into
deps (list, optional) – A list of python packages to install
requirements (str, optional) – The requirements.txt file to install from
upgrade (bool, optional) – Tell pip to upgrade packages when installing, Default=False
verbose (bool, optional) – Display command output when running the dependency operations, Default=False
use_index (bool, optional) – Allow pip to use an external index Default=True
use_local_wheels (bool, optional) – Install from local wheels directory instead of pypi Default=False

Raises:

BuildException - If package installation fails

invirtualenv.deploy.install_rpm_dependencies(deps=None, fail_missing=True)¶

Install rpm dependencies from deploy.conf manifest

Parameters:	deps (list, optional) – A list of rpm packages to install fail_missing (bool, optional) – Generate an exception and fail if the “yum” command is not available. default = True
Raises:	BuildException - If package installation fails

invirtualenv.deploy.link_deployed_bin_files(venv, destbin)¶

Link the deployed files from the venv bin directory into the destbin directory.

Writes a json list of the created links to conf/created_links.json in the virtualenv.

Parameters:	venv (str) – Path to the python virtualenv destbin (str) – Destination directory when the links should be
Returns:	Full path to files linked
Return type:	list

invirtualenv.deploy.unlink_deployed_bin_files(venv)¶

Undo/delete the symlinks created by link_deployed_bin_files()

Parameters:	venv (str) – Path to the root of the virtualenv

Exceptions¶

Exceptions generated by the invirtualenv module

exception invirtualenv.exceptions.AlreadyExists¶: Package already Exists exception

exception invirtualenv.exceptions.BuildException¶: There was an error Building the VirtualEnv

exception invirtualenv.exceptions.CommandNotFound¶: The command specified wasn’t found

exception invirtualenv.exceptions.InsufficientPermissions¶: The current user has insufficient permissions to complete the specified operation.

exception invirtualenv.exceptions.InvirtualenvError¶: An invirtualenv error occurred.

exception invirtualenv.exceptions.NoPackageVersions¶: Query of the Python PyPi repo returned no packages with the specified name.

exception invirtualenv.exceptions.PackageConfigFailure¶: Unable to create a package configuration file

exception invirtualenv.exceptions.PackageGenerationFailure¶: Package generation failed

Package Manipulation¶

Functions for managing packaging

invirtualenv.package.install_prereq_packages(test=False)¶

Install packages required to build python

Parameters:	test (bool, optional) – Don’t run the actual command, if True

invirtualenv.package.latest_package_version(package)¶

Get the latest version number for a package

Parameters:	package (str) – Package to get the latest version of
Returns:	Latest package version or an empty string if no versions are found
Return type:	str

invirtualenv.package.package_scripts_directory()¶

Get the package scripts directory

Returns str

The path to the directory containing the package scripts

invirtualenv.package.package_versions(package, pypi_url=None)¶

Get all versions of a package from pypi

Parameters:	package (str) – The python package to search for pypi_url (str, optional) – The pypi URL to send the request to, defaults to the production pypi endpoint.
Returns:	A list of all packages found on pypi. The list will be empty if there were no versions found.
Return type:	list

invirtualenv.package.strip_from_end(text, suffix)¶

Strip a substring from the end of a string

Parameters:	text (str) – The string to be evaluated suffix (str) – The suffix or substring to remove from the end of the text string
Returns:	A string with the substring removed if it was found at the end of the string.
Return type:	str

Utility¶

General utility functionality module

invirtualenv.utility.change_uid_gid(user_uid=None, user_gid=None)¶

preexec_fn to change the uid/gid when using subprocess

Parameters:	user_uid (int, optional) – The user UID to set to, does not set user uid if this is not passed user_gid (int, optional) – The user GID to set to, does not set the gid if this is not passed

invirtualenv.utility.chown_recursive(path, uid, gid)¶

Change the ownership of all files and directories in path

Parameters:	path (str) – The root path to start changing the ownership at uid, (int) – The uid to change the ownership to gid, (int) – The gid to change the ownership to

invirtualenv.utility.csv_list(value)¶

Convert a comma separated string into a list

Parameters:	value (str) – The string object to convert to a list
Returns:	A list based on splitting the string on the ‘,’ character
Return type:	list

invirtualenv.utility.display_header(text='', width=None, separator=None, outfile=None, collapse=False)¶

Display a textual header message. :param text: The text to print/display :type text: str :param width: The width (text wrap) of the header message.

This will be the current terminal width as determined by the ‘stty size’ shell command if not specified.

Parameters:	separator (str, optional) – The character or string to use as a horizontal separator. Will use ‘=’ if one is not specified. outfile (File, optional) – The File object to print the header text to. This will use sys.stdout if not specified.

:param : :type : return:

invirtualenv.utility.get_terminal_size()¶

Get the terminal rows and columns if we are running on an interactive terminal. :returns: * rows (int) – The number of rows on the current terminal.

columns (int) – The number of columns on the current terminal.

invirtualenv.utility.str_format_env(value)¶

Substitute values with environment variables in a string

Parameters:	value (str) – The string object to be formatted and converted into a list
Returns:	With env variable values substituded
Return type:	str

invirtualenv.utility.str_to_bool(value)¶

Convert a string too a bool object

Parameters:	value (str) – The string object to convert to a bool. The following case insensitive strings evaluate to True [‘true’, 1’, ‘up’, ‘on’]
Returns:	Boolean based on the string
Return type:	bool

invirtualenv.utility.str_to_dict(value)¶

Convert a newline terminated string of key=value into a dictionary.

Parameters:	value (str) – The string object to convert to a dictionary
Returns:	Dictionary based on the string
Return type:	dict

invirtualenv.utility.str_to_list(value)¶

Convert a newline terminated string into a list. Any empty lines will be removed from the result list.

Parameters:	value (str) – The string object to convert to a list
Returns:	List based on the string
Return type:	list

invirtualenv.utility.update_recursive(basedict, updatedict)¶

Recursively run update on a dictionary

Parameters:	basedict (dict) – First dictionary, which will contain the updated result updatedict (dict) – Second dictionary that will be be updated to basedict, conflicts will be replaced with the values from this dictionary.
Returns:	basedict updated to contain the values from updatedict
Return type:	dict

invirtualenv.utility.update_recursive_generator(basedict, updatedict)¶

Recursively run update on a dictionary

Parameters:	basedict (dict) – First dictionary, which will contain the updated result updatedict (dict) – Second dictionary that will be be updated to basedict, conflicts will be replaced with the values from this dictionary.
Returns:	basedict updated to contain the values from updatedict
Return type:	dict

invirtualenv.utility.which(command)¶

Function searches the path for the command executable

Parameters:	command (str) –
Returns:	Path to the command
Return type:	str
Raises:	CommandNotFound: – Command was not found

Static Standalone Binary Creation¶

Virtualenv Management¶

Functions for creating and managing python virtual environments

invirtualenv.virtualenv.build_virtualenv(name, directory, python_interpreter=None, user=None, verbose=False)¶

Build a virtualenv in a directory

Parameters:	name (str) – Name of the virtualenv to create directory (str) – Directory to create the virtualenv in python_interpreter (str, optional) – Python interpreter to provide in the virtualenv, defaults to the interpreter that is running the virtualenv command verbose (bool) – If True, provides status output while running.
Returns:	Full path to the root of the virtualenv directory
Return type:	str
Raises:	`BuildException` – The Virtualenv build failed

invirtualenv.virtualenv.default_virtualenv_directory()¶

Get the default virtualenv directory for the current system/platform

Returns:	The path to the default virtualenv directory
Return type:	str

invirtualenv.virtualenv.install_requirements(requirements, virtualenv, user=None, upgrade=False, verbose=False, pip_version=None, use_index=True, use_local_wheels=False)¶

Open one or more requirements files and run pip -r to install them

Parameters:

requirements (str) – Filename containing requirements
virtualenv (str) – Full path to the virtualenv to install into
user (str, optional) – The user:group to run the install as
upgrade (bool) – If True, tell pip to upgrade when running the install. Default=False
verbose (bool) – If True, provides status output while running.
pip_version (str, optional) – Install the requirements with the specified version of pip
use_index (bool, optional) – Allow pip to use an external index Default=True
use_local_wheels (bool, optional) – Install wheels from local directory Default=False

invirtualenv.virtualenv.remove_virtualenv(name, directory=None)¶: Remove a virtualenv from a directory :param name: :param directory: :return:

invirtualenv.virtualenv.upgrade_package_tools(virtualenv_directory, verbose=False)¶: Upgrade the packages used to install/build packages in the virtualenv :param virtualenv_directory: The directory that contains the virtualenv :type virtualenv_directory: str

invirtualenv.virtualenv.virtualenv_bin_file_hashes(virtualenv_dir)¶

Calculate a hash of all files in the virtualenv bin directory :param virtualenv_dir: The root directory of the virtualenv to operate on :type virtualenv_dir: str

Returns:	Key = Filename, value = hash
Return type:	dict

invirtualenv.virtualenv.virtualenv_command(install_virtualenv=False)¶

Return the virtualenv command

Parameters:	install_virtualenv (bool) – If True, Install virtualenv if necessary. default=False
Returns:	Path to the virtualenv command
Return type:	str