venv —创建虚拟环境

版本 3.3 中的新Function。

源代码： Lib/venv/

---

venv模块提供了对使用其自己的站点目录(可以选择与系统站点目录隔离)创建轻型“虚拟环境”的支持。每个虚拟环境都有自己的 Python 二进制文件(与用于创建该环境的二进制文件的版本匹配)，并且可以在其站点目录中拥有自己独立的已安装 Python 软件包集。

有关 python 虚拟环境的更多信息，请参见 PEP 405。

创建虚拟环境

virtual environments的创建是pass执行命令venv完成的：

python3 -m venv /path/to/new/virtual/environment

运行此命令将创建目标目录(创建尚不存在的任何父目录)，并使用home键将pyvenv.cfg文件放置在其中，该文件指向运行该命令的 Python 安装(目标目录的通用名称为.venv)。它还会创建一个bin(在 Windows 上为Scripts)子目录，其中包含 Python 二进制文件/二进制文件的副本/符号链接(适用于创建环境时使用的平台或参数)。它还会创建一个(最初为空)lib/pythonX.Y/site-packages子目录(在 Windows 上是Lib\site-packages)。如果指定了现有目录，它将被重用。

自版本 3.6 起不推荐使用：pyvenv是为 Python 3.3 和 3.4 创建虚拟环境的推荐工具，其名称为Python 3.6 中已弃用。

在版本 3.5 中进行了更改：现在建议使用venv创建虚拟环境。

在 Windows 上，按如下所示调用venv命令：

c:\>c:\Python35\python -m venv c:\path\to\myenv

另外，如果您为Python installation配置了PATH和PATHEXT变量：

c:\>python -m venv c:\path\to\myenv

该命令(如果与-h一起运行)将显示可用选项：

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT]
            ENV_DIR [ENV_DIR ...]

Creates virtual Python environments in one or more target directories.

positional arguments:
  ENV_DIR               A directory to create the environment in.

optional arguments:
  -h, --help            show this help message and exit
  --system-site-packages
                        Give the virtual environment access to the system
                        site-packages dir.
  --symlinks            Try to use symlinks rather than copies, when symlinks
                        are not the default for the platform.
  --copies              Try to use copies rather than symlinks, even when
                        symlinks are the default for the platform.
  --clear               Delete the contents of the environment directory if it
                        already exists, before environment creation.
  --upgrade             Upgrade the environment directory to use this version
                        of Python, assuming Python has been upgraded in-place.
  --without-pip         Skips installing or upgrading pip in the virtual
                        environment (pip is bootstrapped by default)
  --prompt PROMPT       Provides an alternative prompt prefix for this
                        environment.

Once an environment has been created, you may wish to activate it, e.g. by
sourcing an activate script in its bin directory.

在版本 3.4 中进行了更改：默认情况下安装 pip，并添加了--without-pip和--copies选项

在版本 3.4 中进行了更改：在早期版本中，如果目标目录已存在，则将引发错误，除非提供了--clear或--upgrade选项。

创建的pyvenv.cfg文件还包含include-system-site-packages键，如果venv与--system-site-packages选项一起运行，则设置为true，否则为false。

除非给出--without-pip选项，否则将调用ensurepip将pip引导到虚拟环境中。

可以为venv提供多个路径，在这种情况下，将根据给定的选项在每个提供的路径上创建相同的虚拟环境。

创建虚拟环境后，可以使用虚拟环境的二进制目录中的脚本“激活”它。脚本的调用是特定于平台的(必须替换为包含虚拟环境的目录的路径)：

Platform	Shell	激活虚拟环境的命令
POSIX	bash/zsh	$ source /bin/activate
	fish	$。 /bin/activate.fish
	csh/tcsh	$ source /bin/activate.csh
	PowerShell Core	$ <venv>/bin/Activate.ps1
Windows	cmd.exe	C:\> <venv>\Scripts\activate.bat
	PowerShell	PS C：> \Scripts\Activate.ps1

您不需要特别来激活环境；激活只是将虚拟环境的二进制目录添加到您的路径中，以便“ python”调用虚拟环境的 Python 解释器，您可以运行已安装的脚本，而不必使用其完整路径。但是，安装在虚拟环境中的所有脚本都应在不激活的情况下可运行，并自动与虚拟环境的 Python 一起运行。

您可以pass在 Shell 程序中键入“ deactivate”来停用虚拟环境。确切的机制是特定于平台的，并且是内部实现的详细信息(通常将使用脚本或 shell 函数)。

3.4 版中的新Function：fish和csh激活脚本。

3.8 版中的新增Function：在 POSIX 下安装了 PowerShell 激活脚本以支持 PowerShell Core。

API

上面描述的高级方法使用了一个简单的 API，该 API 为第三方虚拟环境创建者提供了根据自己的需求EnvBuilder类定制环境创建的机制。

• • class * venv. EnvBuilder(* system_site_packages = False ， clear = False ， symlinks = False ， upgrade = False ， with_pip = False ， prompt = None *)
  • EnvBuilder类在实例化时接受以下关键字参数：

• system_site_packages –一个布尔值，指示系统 Python 站点包应为环境可用(默认为False)。

• clear –一个布尔值，如果为 true，则将在创建环境之前删除任何现有目标目录的内容。

• symlinks –一个布尔值，指示是否try符号链接 Python 二进制文件而不是进行复制。

• upgrade-一个布尔值，如果为 true，将使用运行中的 Python 升级现有环境-在该 Python 就地升级时使用(默认为False)。

• with_pip –一个布尔值，如果为 true，则确保在虚拟环境中安装了 pip。这将ensurepip与--default-pip选项一起使用。

• prompt –激活虚拟环境后将使用的字符串(默认为None，这意味着将使用环境的目录名称)。

在版本 3.4 中进行了更改：添加了with_pip参数

3.6 版的新Function：添加了prompt参数

第三方虚拟环境工具的创建者可以自由使用提供的EnvBuilder类作为 Base Class。

返回的 env-builder 是一个具有create方法的对象：

• create(* env_dir *)
  • pass指定要包含虚拟环境的目标目录(绝对目录或相对于当前目录)来创建虚拟环境。 create方法将在指定目录中创建环境，或引发适当的异常。

EnvBuilder类的create方法说明了可用于子类定制的钩子：

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)

方法ensure_directories()，create_configuration()，setup_python()，setup_scripts()和post_setup()中的每一个都可以被覆盖。

• ensure_directories(* env_dir *)

  • 创建环境目录和所有必需的目录，并返回一个上下文对象。这只是属性(例如路径)的所有者，供其他方法使用。只要指定clear或upgrade以允许在现有环境目录上进行操作，就允许目录已经存在。

• create_configuration(上下文)

  • 在环境中创建pyvenv.cfg配置文件。

• setup_python(上下文)

  • 在环境中创建到 Python 可执行文件的副本或符号链接。在 POSIX 系统上，如果使用了特定的可执行文件python3.x，则将创建指向该可执行文件的指向python和python3的符号链接，除非已经存在具有这些名称的文件。

• setup_scripts(上下文)

  • 将适合平台的激活脚本安装到虚拟环境中。

• post_setup(上下文)

  • 可以在第三方实现中覆盖的占位符方法，以在虚拟环境中预安装软件包或执行其他创建后的步骤。

在版本 3.7.2 中进行了更改：Windows 现在使用python[w].exe重定向程序脚本，而不是复制实际的二进制文件。在 3.7.2 中，除非从源树中的构建运行，否则只有setup_python()不会执行任何操作。

在版本 3.7.3 中进行了更改：Windows 将重定向程序脚本复制为setup_python()而不是setup_scripts()的一部分。在 3.7.2 中不是这种情况。使用符号链接时，原始可执行文件将被链接。

另外，EnvBuilder提供了此 Util 方法，可以在子类中从setup_scripts()或post_setup()调用该方法，以帮助将自定义脚本安装到虚拟环境中。

• install_scripts(上下文，路径)

  • • path *是目录的路径，该目录应包含子目录“ common”，“ posix”，“ nt”，每个子目录包含用于环境中 bin 目录的脚本。在替换占位符的一些文本之后，将复制“ common”的内容和与os.name对应的目录：

• __VENV_DIR__被替换为环境目录的绝对路径。

• __VENV_NAME__替换为环境名称(环境目录的finally路径段)。

• __VENV_PROMPT__替换为提示符(环境名称用括号括起来，并带有以下空格)

• __VENV_BIN_NAME__替换为 bin 目录的名称(bin或Scripts)。

• __VENV_PYTHON__被替换为环境可执行文件的绝对路径。

目录允许存在(用于升级现有环境时)。

还有一个模块级的便捷Function：

• venv. create(* env_dir ， system_site_packages = False ， clear = False ， symlinks = False ， with_pip = False ， prompt = None *)
  • 使用给定的关键字参数创建一个EnvBuilder，并使用* env_dir *参数调用其create()方法。

版本 3.3 中的新Function。

在版本 3.4 中进行了更改：添加了with_pip参数

在版本 3.6 中更改：添加了prompt参数

扩展 EnvBuilder 的示例

以下脚本显示了如何pass实现一个子类来扩展EnvBuilder，该子类将 setuptools 和 pip 安装到创建的虚拟环境中：

import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlparse
from urllib.request import urlretrieve
import venv

class ExtendedEnvBuilder(venv.EnvBuilder):
    """
    This builder installs setuptools and pip so that you can pip or
    easy_install other packages into the created virtual environment.

    :param nodist: If true, setuptools and pip are not installed into the
                   created virtual environment.
    :param nopip: If true, pip is not installed into the created
                  virtual environment.
    :param progress: If setuptools or pip are installed, the progress of the
                     installation can be monitored by passing a progress
                     callable. If specified, it is called with two
                     arguments: a string indicating some progress, and a
                     context indicating where the string is coming from.
                     The context argument can have one of three values:
                     'main', indicating that it is called from virtualize()
                     itself, and 'stdout' and 'stderr', which are obtained
                     by reading lines from the output streams of a subprocess
                     which is used to install the app.

                     If a callable is not specified, default progress
                     information is output to sys.stderr.
    """

    def __init__(self, *args, **kwargs):
        self.nodist = kwargs.pop('nodist', False)
        self.nopip = kwargs.pop('nopip', False)
        self.progress = kwargs.pop('progress', None)
        self.verbose = kwargs.pop('verbose', False)
        super().__init__(*args, **kwargs)

    def post_setup(self, context):
        """
        Set up any packages which need to be pre-installed into the
        virtual environment being created.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Can't install pip without setuptools
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Read lines from a subprocess' output stream and either pass to a progress
        callable (if specified) or write progress information to sys.stderr.
        """
        progress = self.progress
        while True:
            s = stream.readline()
            if not s:
                break
            if progress is not None:
                progress(s, context)
            else:
                if not self.verbose:
                    sys.stderr.write('.')
                else:
                    sys.stderr.write(s.decode('utf-8'))
                sys.stderr.flush()
        stream.close()

    def install_script(self, context, name, url):
        _, _, path, _, _, _ = urlparse(url)
        fn = os.path.split(path)[-1]
        binpath = context.bin_path
        distpath = os.path.join(binpath, fn)
        # Download script into the virtual environment's binaries folder
        urlretrieve(url, distpath)
        progress = self.progress
        if self.verbose:
            term = '\n'
        else:
            term = ''
        if progress is not None:
            progress('Installing %s ...%s' % (name, term), 'main')
        else:
            sys.stderr.write('Installing %s ...%s' % (name, term))
            sys.stderr.flush()
        # Install in the virtual environment
        args = [context.env_exe, fn]
        p = Popen(args, stdout=PIPE, stderr=PIPE, cwd=binpath)
        t1 = Thread(target=self.reader, args=(p.stdout, 'stdout'))
        t1.start()
        t2 = Thread(target=self.reader, args=(p.stderr, 'stderr'))
        t2.start()
        p.wait()
        t1.join()
        t2.join()
        if progress is not None:
            progress('done.', 'main')
        else:
            sys.stderr.write('done.\n')
        # Clean up - no longer needed
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Install setuptools in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://bitbucket.org/pypa/setuptools/downloads/ez_setup.py'
        self.install_script(context, 'setuptools', url)
        # clear up the setuptools archive which gets downloaded
        pred = lambda o: o.startswith('setuptools-') and o.endswith('.tar.gz')
        files = filter(pred, os.listdir(context.bin_path))
        for f in files:
            f = os.path.join(context.bin_path, f)
            os.unlink(f)

    def install_pip(self, context):
        """
        Install pip in the virtual environment.

        :param context: The information for the virtual environment
                        creation request being processed.
        """
        url = 'https://raw.github.com/pypa/pip/master/contrib/get-pip.py'
        self.install_script(context, 'pip', url)

def main(args=None):
    compatible = True
    if sys.version_info < (3, 3):
        compatible = False
    elif not hasattr(sys, 'base_prefix'):
        compatible = False
    if not compatible:
        raise ValueError('This script is only for use with '
                         'Python 3.3 or later')
    else:
        import argparse

        parser = argparse.ArgumentParser(prog=__name__,
                                         description='Creates virtual Python '
                                                     'environments in one or '
                                                     'more target '
                                                     'directories.')
        parser.add_argument('dirs', metavar='ENV_DIR', nargs='+',
                            help='A directory in which to create the
                                 'virtual environment.')
        parser.add_argument('--no-setuptools', default=False,
                            action='store_true', dest='nodist',
                            help="Don't install setuptools or pip in the "
                                 "virtual environment.")
        parser.add_argument('--no-pip', default=False,
                            action='store_true', dest='nopip',
                            help="Don't install pip in the virtual "
                                 "environment.")
        parser.add_argument('--system-site-packages', default=False,
                            action='store_true', dest='system_site',
                            help='Give the virtual environment access to the '
                                 'system site-packages dir.')
        if os.name == 'nt':
            use_symlinks = False
        else:
            use_symlinks = True
        parser.add_argument('--symlinks', default=use_symlinks,
                            action='store_true', dest='symlinks',
                            help='Try to use symlinks rather than copies, '
                                 'when symlinks are not the default for '
                                 'the platform.')
        parser.add_argument('--clear', default=False, action='store_true',
                            dest='clear', help='Delete the contents of the '
                                               'virtual environment '
                                               'directory if it already '
                                               'exists, before virtual '
                                               'environment creation.')
        parser.add_argument('--upgrade', default=False, action='store_true',
                            dest='upgrade', help='Upgrade the virtual '
                                                 'environment directory to '
                                                 'use this version of '
                                                 'Python, assuming Python '
                                                 'has been upgraded '
                                                 'in-place.')
        parser.add_argument('--verbose', default=False, action='store_true',
                            dest='verbose', help='Display the output '
                                               'from the scripts which '
                                               'install setuptools and pip.')
        options = parser.parse_args(args)
        if options.upgrade and options.clear:
            raise ValueError('you cannot supply --upgrade and --clear together.')
        builder = ExtendedEnvBuilder(system_site_packages=options.system_site,
                                       clear=options.clear,
                                       symlinks=options.symlinks,
                                       upgrade=options.upgrade,
                                       nodist=options.nodist,
                                       nopip=options.nopip,
                                       verbose=options.verbose)
        for d in options.dirs:
            builder.create(d)

if __name__ == '__main__':
    rc = 1
    try:
        main()
        rc = 0
    except Exception as e:
        print('Error: %s' % e, file=sys.stderr)
    sys.exit(rc)

该脚本也可以下载online。