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)

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

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)

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

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