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

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

Создание виртуальных окружений выполняется с помощью команды venv:

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

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

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

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

Альтернативно, если вы настроили переменные PATH и PATHEXT для вашей установки Python:

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

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

usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear]
            [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps]
            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.
  --upgrade-deps        Upgrade core dependencies: pip setuptools to the
                        latest version in PyPI

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

Созданный файл 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 Launcher for 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)¶

Класс 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

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

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

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

Создатели сторонних инструментов для виртуальных окружений могут свободно использовать предоставленный класс EnvBuilder в качестве базового класса.

Возвращаемый env-builder – это объект, у которого есть метод create:

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.12: Атрибут lib_path был добавлен в контекст, и объект контекста был задокументирован.

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

create_configuration(context)¶

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

setup_python(context)¶

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

setup_scripts(context)¶

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

upgrade_dependencies(context)¶

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

Новое в версии 3.9.

post_setup(context)¶

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

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

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

Кроме того, EnvBuilder предоставляет этот вспомогательный метод, который можно вызвать из setup_scripts() или post_setup() в подклассах для установки пользовательских скриптов в виртуальное окружение.

install_scripts(context, path)¶

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

• __VENV_DIR__ заменяется на абсолютный путь к каталогу окружения.

• __VENV_NAME__ заменяется на имя окружения (последний сегмент пути к каталогу окружения).

• __VENV_PROMPT__ заменяется на приглашение (имя окружения в скобках и с последующим пробелом)

• __VENV_BIN_NAME__ заменяется на имя каталога bin ( bin или Scripts).

• __VENV_PYTHON__ заменяется на абсолютный путь к исполняемому файлу окружения.

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

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

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

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

Новое в версии 3.3.

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

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

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

Пример расширения 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 urlparse
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, _, _, _ = urlparse(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://bitbucket.org/pypa/setuptools/downloads/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 в виртуальное окружение

        обрабатываемого запроса на создание виртуального окружения
                        запрос на создание обрабатывается
        """
        url = 'https://bootstrap.pypa.io/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)

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