venv — Создание виртуальных окружений

Создание виртуальных окружений

Виртуальные окружения создаются запуском модуля venv:

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

При этом создаётся целевой каталог (включая родительские каталоги, если необходимо), а в нём размещается файл pyvenv.cfg с ключом home, указывающим на установку Python, из которой была запущена команда. Также создаётся подкаталог bin (или Scripts в Windows), содержащий копию или символическую ссылку на исполняемый файл Python (в зависимости от платформы и аргументов, заданных при создании окружения). Кроме того, создаётся подкаталог lib/pythonX.Y/site-packages (в Windows — Lib\site-packages). Если указанный каталог уже существует, он будет использован повторно.

В Windows выполните команду venv следующим образом:

PS> python -m venv C:\path\to\new\virtual\environment

При запуске команды с параметром -h отображаются доступные параметры:

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

Creates virtual Python environments in one or more target directories.

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

ENV_DIR

Обязательный аргумент, указывающий каталог, в котором нужно создать окружение.

--system-site-packages

Предоставить виртуальному окружению доступ к системному каталогу site-packages.

--symlinks

Попытаться использовать символические ссылки вместо копий, если символические ссылки не используются на этой платформе по умолчанию.

--copies

Попытаться использовать копии вместо символических ссылок, даже если на этой платформе символические ссылки используются по умолчанию.

--clear

Перед созданием окружения удалить содержимое каталога окружения, если он уже существует.

--upgrade

Обновить каталог окружения для использования этой версии Python, предполагая, что Python был обновлён на месте.

--without-pip

Пропустить установку или обновление pip в виртуальном окружении (по умолчанию pip загружается начальным образом).

--prompt <PROMPT>

Задать альтернативный префикс приглашения для этого окружения.

--upgrade-deps

Обновить основные зависимости (pip) до последней версии на PyPI.

--without-scm-ignore-files

Не добавлять файлы игнорирования SCM в каталог окружения (по умолчанию поддерживается Git).

PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Создаваемый файл pyvenv.cfg также содержит ключ include-system-site-packages, которому присваивается значение true, если venv запускается с параметром --system-site-packages, и false в противном случае.

Если не указан параметр --without-pip, для загрузки pip в виртуальное окружение будет вызван ensurepip.

Для venv можно указать несколько путей. В этом случае в каждом из указанных путей будет создано идентичное виртуальное окружение с учётом заданных параметров.

Как работают виртуальные окружения

Когда интерпретатор Python запущен из виртуального окружения, sys.prefix и sys.exec_prefix указывают на каталоги виртуального окружения, а sys.base_prefix и sys.base_exec_prefix — на каталоги базовой установки Python, использованной для создания окружения. Чтобы определить, запущен ли текущий интерпретатор из виртуального окружения, достаточно проверить sys.prefix != sys.base_prefix.

Виртуальное окружение можно «активировать» с помощью сценария в его каталоге двоичных файлов (bin в POSIX; Scripts в Windows). Это добавит данный каталог в начало PATH, чтобы команда python запускала интерпретатор Python из окружения, а установленные сценарии можно было запускать без указания полного пути к ним. Способ вызова сценария активации зависит от платформы (<venv> необходимо заменить путём к каталогу, содержащему виртуальное окружение):

Вам не обязательно нужно активировать виртуальное окружение: при запуске Python можно просто указать полный путь к интерпретатору Python из этого окружения. Кроме того, все установленные в окружении сценарии должны запускаться и без его активации.

Для этого в сценарии, установленные в виртуальных окружениях, добавляется строка «шебанг», указывающая на интерпретатор Python из окружения: #!/<path-to-venv>/bin/python. Это означает, что сценарий будет запущен этим интерпретатором независимо от значения PATH. В Windows обработка строк «шебанг» поддерживается при наличии установленного диспетчера установки Python. Поэтому двойной щелчок по установленному сценарию в окне Проводника Windows должен запускать его с правильным интерпретатором, даже если окружение не активировано или отсутствует в PATH.

При активации виртуального окружения переменной среды VIRTUAL_ENV присваивается путь к окружению. Поскольку для использования виртуального окружения его активация не требуется, на VIRTUAL_ENV нельзя полагаться при определении того, используется ли виртуальное окружение.

Деактивировать виртуальное окружение можно, введя в оболочке команду deactivate. Конкретный способ зависит от платформы и является внутренней деталью реализации (обычно используется сценарий или функция оболочки).

API

Описанный выше высокоуровневый метод использует простой API, предоставляющий сторонним создателям виртуальных окружений механизмы настройки их создания в соответствии с потребностями. Основой этого API является класс EnvBuilder.

class venv.EnvBuilder(system_site_packages=False, clear=False, symlinks=False, upgrade=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())

При создании экземпляра класса EnvBuilder принимает следующие именованные аргументы:

• system_site_packages — логическое значение, указывающее, должны ли системные пакеты site-packages Python быть доступны окружению (по умолчанию False).
• clear — логическое значение; если оно истинно, перед созданием окружения удаляется содержимое существующего целевого каталога.
• symlinks — логическое значение, указывающее, следует ли попытаться создать символическую ссылку на двоичный файл Python вместо его копирования.
• upgrade — логическое значение; если оно истинно, существующее окружение будет обновлено с помощью запущенного Python. Предназначено для случаев обновления Python на месте (по умолчанию False).
• with_pip — логическое значение; если оно истинно, в виртуальном окружении устанавливается pip. Для этого используется ensurepip с параметром --default-pip.
• prompt — строка, используемая после активации виртуального окружения (по умолчанию None, то есть используется имя каталога окружения). Если указана специальная строка ".", в качестве приглашения используется базовое имя текущего каталога.
• upgrade_deps — обновить основные модули venv до последних версий на PyPI.
• scm_ignore_files — создать файлы игнорирования для указанных в итерируемом объекте систем контроля версий (SCM). Поддержка определяется наличием метода с именем create_{scm}_ignore_file. По умолчанию поддерживается только "git" с помощью create_git_ignore_file().

Изменено в версии 3.4: Добавлен параметр with_pip

Изменено в версии 3.6: Добавлен параметр prompt

Изменено в версии 3.9: Добавлен параметр upgrade_deps

Изменено в версии 3.13: Добавлен параметр scm_ignore_files

EnvBuilder можно использовать в качестве базового класса.

create(env_dir)

Создаёт виртуальное окружение, принимая целевой каталог (абсолютный или относительный путь от текущего каталога), в котором оно будет размещено. Метод create либо создаст окружение в указанном каталоге, либо вызовет соответствующее исключение.

Метод create класса EnvBuilder демонстрирует хуки, доступные для настройки подклассов:

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)

Создаёт каталог окружения и все необходимые отсутствующие подкаталоги, а затем возвращает объект-контекст. Этот объект-контейнер хранит атрибуты (например, пути), используемые другими методами. Если EnvBuilder создаётся с аргументом clear=True, содержимое каталога окружения очищается, после чего заново создаются все необходимые подкаталоги.

Возвращаемый объект-контекст — это types.SimpleNamespace со следующими атрибутами:

• env_dir — расположение виртуального окружения. Используется для __VENV_DIR__ в сценариях активации (см. install_scripts()).
• env_name — имя виртуального окружения. Используется для __VENV_NAME__ в сценариях активации (см. install_scripts()).
• prompt — приглашение, используемое сценариями активации. Используется для __VENV_PROMPT__ в сценариях активации (см. install_scripts()).
• executable — базовый исполняемый файл Python, используемый виртуальным окружением. Учитывает случай, когда виртуальное окружение создано из другого виртуального окружения.
• inc_path — путь include виртуального окружения.
• lib_path — путь purelib виртуального окружения.
• bin_path — путь к сценариям виртуального окружения.
• bin_name — имя пути к сценариям относительно расположения виртуального окружения. Используется для __VENV_BIN_NAME__ в сценариях активации (см. install_scripts()).
• env_exe — имя интерпретатора Python в виртуальном окружении. Используется для __VENV_PYTHON__ в сценариях активации (см. install_scripts()).
• env_exec_cmd — имя интерпретатора Python с учётом перенаправлений файловой системы. Его можно использовать для запуска Python в виртуальном окружении.

Изменено в версии 3.11: Для формирования путей создаваемых каталогов используется схема установки sysconfig venv.

Изменено в версии 3.12: В контекст добавлен атрибут lib_path, а объект-контекст получил документацию.

create_configuration(context)

Создаёт в окружении файл конфигурации pyvenv.cfg.

setup_python(context)

Создаёт копию исполняемого файла Python в окружении или символическую ссылку на него. В POSIX-системах, если использовался определённый исполняемый файл python3.x, будут созданы символические ссылки python и python3 на этот исполняемый файл, если файлы с такими именами ещё не существуют.

setup_scripts(context)

Устанавливает в виртуальное окружение сценарии активации, подходящие для платформы.

upgrade_dependencies(context)

Обновляет основные пакеты-зависимости venv (в настоящее время pip) в окружении. Для этого из оболочки запускается исполняемый файл pip из окружения.

Добавлено в версии 3.9.

Изменено в версии 3.12: setuptools больше не является основной зависимостью venv.

post_setup(context)

Метод-заполнитель, который можно переопределить в сторонних реализациях для предварительной установки пакетов в виртуальное окружение или выполнения других действий после его создания.

install_scripts(context, path)

Этот метод можно вызывать из setup_scripts() или post_setup() в подклассах, чтобы упростить установку пользовательских сценариев в виртуальное окружение.

path — путь к каталогу, в котором должны находиться подкаталоги common, posix, nt; каждый из них содержит сценарии, предназначенные для каталога bin в окружении. Содержимое common и каталога, соответствующего os.name, копируется с предварительной заменой некоторых текстовых заполнителей:

• __VENV_DIR__ заменяется абсолютным путём к каталогу окружения.
• __VENV_NAME__ заменяется именем окружения (последним компонентом пути к каталогу окружения).
• __VENV_PROMPT__ заменяется приглашением (именем окружения в круглых скобках с последующим пробелом).
• __VENV_BIN_NAME__ заменяется именем каталога bin (bin или Scripts).
• __VENV_PYTHON__ заменяется абсолютным путём к исполняемому файлу окружения.

Каталоги могут уже существовать (например, если обновляется существующее окружение).

create_git_ignore_file(context)

Создаёт в виртуальном окружении файл .gitignore, из-за которого система контроля версий Git игнорирует весь каталог.

Добавлено в версии 3.13.

Изменено в версии 3.7.2: Теперь в Windows для python[w].exe используются сценарии-перенаправители вместо копирования самих двоичных файлов. В версии 3.7.2 метод setup_python() ничего не делает, если Python не запущен из сборки в дереве исходного кода.

Изменено в версии 3.7.3: В Windows сценарии-перенаправители копируются в рамках setup_python(), а не setup_scripts(). В версии 3.7.2 это было не так. При использовании символических ссылок создаются ссылки на исходные исполняемые файлы.

Также имеется вспомогательная функция на уровне модуля:

venv.create(env_dir, system_site_packages=False, clear=False, symlinks=False, with_pip=False, prompt=None, upgrade_deps=False, *, scm_ignore_files=frozenset())

Создаёт EnvBuilder с указанными именованными аргументами и вызывает его метод create(), передавая аргумент env_dir.

Добавлено в версии 3.3.

Изменено в версии 3.4: Добавлен параметр with_pip

Изменено в версии 3.6: Добавлен параметр prompt

Изменено в версии 3.9: Добавлен параметр upgrade_deps

Изменено в версии 3.13: Добавлен параметр scm_ignore_files

Пример расширения EnvBuilder

В следующем сценарии показано, как расширить EnvBuilder, реализовав подкласс, который устанавливает setuptools и pip в созданное виртуальное окружение:

import os
import os.path
from subprocess import Popen, PIPE
import sys
from threading import Thread
from urllib.parse import urlsplit
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, _, _ = urlsplit(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://bootstrap.pypa.io/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://bootstrap.pypa.io/get-pip.py'
        self.install_script(context, 'pip', url)


def main(args=None):
    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)

Этот сценарий также доступен для скачивания в Интернете.