venv – Создание виртуальных окружений¶venv – Creation of virtual environments

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

Виртуальные окружения создаются выполнением модуля 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, будет вызван ensurepip для начальной установки pip в виртуальное окружение.

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

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

Когда интерпретатор 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 install manager. Таким образом, двойной щелчок по установленному скрипту в окне Проводника 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):
    """
    Создаёт виртуализированное окружение Python в указанном каталоге.
    Параметр env_dir – это целевой каталог, в котором создаётся окружение.
    """
    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: venv схема установки sysconfig используется для построения путей создаваемых каталогов.

Изменено в версии 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() ничего не делает, если не запущен из сборки в исходном дереве.

Изменено в версии 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¶An example of extending 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):
    """
    Данный построитель устанавливает setuptools и pip, чтобы с их помощью можно было
    устанавливать другие пакеты в созданное виртуальное окружение командой pip или easy_install.

    :param nodist: Если истина, setuptools и pip не устанавливаются в
                   созданное виртуальное окружение.
    :param nopip: Если истина, pip не устанавливается в созданное
                  виртуальное окружение.
    :param progress: Если setuptools или pip устанавливаются, за ходом установки
                     можно следить, передав вызываемый объект для отслеживания прогресса.
                     Если он указан, то вызывается с двумя
                     аргументами: строкой, описывающей текущий этап, и
                     контекстом, указывающим, откуда пришла эта строка.
                     Аргумент context может принимать одно из трёх значений:
                     'main' – вызов происходит из самой virtualize(),
                     а также 'stdout' и 'stderr' – строки берутся
                     из потоков вывода подпроцесса, который
                     используется для установки приложения.

                     Если вызываемый объект не указан, по умолчанию сведения о ходе выполнения
                     выводятся в 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):
        """
        Устанавливает пакеты, которые необходимо предварительно установить в создаваемое виртуальное окружение.
        создаваемое виртуальное окружение

        обрабатываемого запроса на создание виртуального окружения
                        запрос на создание обрабатывается
        """
        os.environ['VIRTUAL_ENV'] = context.env_dir
        if not self.nodist:
            self.install_setuptools(context)
        # Читает строки из потока вывода подпроцесса и либо передаёт их вызываемому объекту для отслеживания хода выполнения
        if not self.nopip and not self.nodist:
            self.install_pip(context)

    def reader(self, stream, context):
        """
        Читает строки из потока вывода подпроцесса и передаёт их в индикатор прогресса
        Загружает скрипт в папку с бинарными файлами виртуального окружения
        """
        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)
        # Устанавливает в виртуальное окружение
        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()
        # Очистка – больше не требуется
        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')
        # Очищает – больше не требуется
        os.unlink(distpath)

    def install_setuptools(self, context):
        """
        Устанавливает setuptools в виртуальное окружение

        обрабатываемого запроса на создание виртуального окружения
                        запрос на создание обрабатывается
        """
        url = "https://bootstrap.pypa.io/ez_setup.py"
        self.install_script(context, 'setuptools', url)
        # Устанавливает pip в виртуальное окружение.
        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):
        """
        Устанавливает pip в виртуальное окружение

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

Этот скрипт также доступен для загрузки онлайн.