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 этого окружения. Кроме того, все сценарии, установленные в окружении, должны запускаться и без его активации.

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

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

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

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 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://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)

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