venv.EnvBuilder

class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False)

The EnvBuilder class accepts the following keyword arguments on instantiation:

• system_site_packages – a Boolean value indicating that the system Python site-packages should be available to the environment (defaults to False).
• clear – a Boolean value which, if true, will delete the contents of any existing target directory, before creating the environment.
• symlinks – a Boolean value indicating whether to attempt to symlink the Python binary (and any necessary DLLs or other binaries, e.g. pythonw.exe), rather than copying. Defaults to True on Linux and Unix systems, but False on Windows.
• upgrade – a Boolean value which, if true, will upgrade an existing environment with the running Python - for use when that Python has been upgraded in-place (defaults to False).
• with_pip – a Boolean value which, if true, ensures pip is installed in the virtual environment. This uses ensurepip with the --default-pip option.

Creators of third-party virtual environment tools will be free to use the provided EnvBuilder class as a base class.

The returned env-builder is an object which has a method, create:

create(env_dir)

This method takes as required argument the path (absolute or relative to the current directory) of the target directory which is to contain the virtual environment. The create method will either create the environment in the specified directory, or raise an appropriate exception.

The create method of the EnvBuilder class illustrates the hooks available for subclass customization:

def create(self, env_dir):
    """
    Create a virtualized Python environment in a directory.
    env_dir is the target directory to create an environment in.
    """
    env_dir = os.path.abspath(env_dir)
    context = self.ensure_directories(env_dir)
    self.create_configuration(context)
    self.setup_python(context)
    self.setup_scripts(context)
    self.post_setup(context)

Each of the methods ensure_directories(), create_configuration(), setup_python(), setup_scripts() and post_setup() can be overridden.

ensure_directories(env_dir)

Creates the environment directory and all necessary directories, and returns a context object. This is just a holder for attributes (such as paths), for use by the other methods. The directories are allowed to exist already, as long as either clear or upgrade were specified to allow operating on an existing environment directory.

create_configuration(context)

Creates the pyvenv.cfg configuration file in the environment.

setup_python(context)

Creates a copy of the Python executable (and, under Windows, DLLs) in the environment. On a POSIX system, if a specific executable python3.x was used, symlinks to python and python3 will be created pointing to that executable, unless files with those names already exist.

setup_scripts(context)

Installs activation scripts appropriate to the platform into the virtual environment.

post_setup(context)

A placeholder method which can be overridden in third party implementations to pre-install packages in the virtual environment or perform other post-creation steps.

In addition, EnvBuilder provides this utility method that can be called from setup_scripts() or post_setup() in subclasses to assist in installing custom scripts into the virtual environment.

install_scripts(context, path)

path is the path to a directory that should contain subdirectories “common”, “posix”, “nt”, each containing scripts destined for the bin directory in the environment. The contents of “common” and the directory corresponding to os.name are copied after some text replacement of placeholders:

• __VENV_DIR__ is replaced with the absolute path of the environment directory.
• __VENV_NAME__ is replaced with the environment name (final path segment of environment directory).
• __VENV_PROMPT__ is replaced with the prompt (the environment name surrounded by parentheses and with a following space)
• __VENV_BIN_NAME__ is replaced with the name of the bin directory (either bin or Scripts).
• __VENV_PYTHON__ is replaced with the absolute path of the environment’s executable.

The directories are allowed to exist (for when an existing environment is being upgraded).